GLib.Sequence¶

record (struct)

The Sequence struct is an opaque data type representing a sequence data type.

Methods¶

append¶

def append(self, data: int | None = ...) -> SequenceIter

Adds a new item to the end of seq.

Parameters:

data — the data for the new item

foreach¶

def foreach(self, func: Func) -> None

Calls func for each item in the sequence passing user_data to the function. func must not modify the sequence itself.

Parameters:

func — the function to call for each item in seq

free¶

def free(self) -> None

Frees the memory allocated for seq. If seq has a data destroy function associated with it, that function is called on all items in seq.

get_begin_iter¶

def get_begin_iter(self) -> SequenceIter

Returns the begin iterator for seq.

get_end_iter¶

def get_end_iter(self) -> SequenceIter

Returns the end iterator for seg

get_iter_at_pos¶

def get_iter_at_pos(self, pos: int) -> SequenceIter

Returns the iterator at position pos. If pos is negative or larger than the number of items in seq, the end iterator is returned.

Parameters:

pos — a position in seq, or -1 for the end

get_length¶

def get_length(self) -> int

Returns the positive length (>= 0) of seq. Note that this method is O(h) where h' is the height of the tree. It is thus more efficient to use [Sequence.is_empty`](./Sequence.md#method-is_empty) when comparing the length to zero.

insert_sorted¶

def insert_sorted(self, data: int | None, cmp_func: CompareDataFunc) -> SequenceIter

Inserts data into seq using cmp_func to determine the new position. The sequence must already be sorted according to cmp_func; otherwise the new position of data is undefined.

cmp_func is called with two items of the seq, and cmp_data. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first.

Note that when adding a large amount of data to a Sequence, it is more efficient to do unsorted insertions and then call Sequence.sort or Sequence.sort_iter.

Parameters:

data — the data to insert
cmp_func — the function used to compare items in the sequence

insert_sorted_iter¶

def insert_sorted_iter(self, data: int | None, iter_cmp: SequenceIterCompareFunc) -> SequenceIter

Like Sequence.insert_sorted, but uses a GSequenceIterCompareFunc instead of a GCompareDataFunc as the compare function.

iter_cmp is called with two iterators pointing into seq. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first.

Note that when adding a large amount of data to a Sequence, it is more efficient to do unsorted insertions and then call Sequence.sort or Sequence.sort_iter.

Parameters:

data — data for the new item
iter_cmp — the function used to compare iterators in the sequence

is_empty¶

def is_empty(self) -> bool

Returns True if the sequence contains zero items.

This function is functionally identical to checking the result of Sequence.get_length being equal to zero. However this function is implemented in O(1) running time.

lookup¶

def lookup(self, data: int | None, cmp_func: CompareDataFunc) -> SequenceIter | None

Returns an iterator pointing to the position of the first item found equal to data according to cmp_func and cmp_data. If more than one item is equal, it is not guaranteed that it is the first which is returned. In that case, you can use SequenceIter.next and SequenceIter.prev to get others.

cmp_func is called with two items of the seq, and cmp_data. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first.

This function will fail if the data contained in the sequence is unsorted.

Parameters:

data — data to look up
cmp_func — the function used to compare items in the sequence

lookup_iter¶

def lookup_iter(self, data: int | None, iter_cmp: SequenceIterCompareFunc) -> SequenceIter | None

Like Sequence.lookup, but uses a GSequenceIterCompareFunc instead of a GCompareDataFunc as the compare function.

iter_cmp is called with two iterators pointing into seq. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first.

This function will fail if the data contained in the sequence is unsorted.

Parameters:

data — data to look up
iter_cmp — the function used to compare iterators in the sequence

prepend¶

def prepend(self, data: int | None = ...) -> SequenceIter

Adds a new item to the front of seq

Parameters:

data — the data for the new item

search¶

def search(self, data: int | None, cmp_func: CompareDataFunc) -> SequenceIter

Returns an iterator pointing to the position where data would be inserted according to cmp_func and cmp_data.

cmp_func is called with two items of the seq, and cmp_data. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first.

If you are simply searching for an existing element of the sequence, consider using Sequence.lookup.

This function will fail if the data contained in the sequence is unsorted.

Parameters:

data — data for the new item
cmp_func — the function used to compare items in the sequence

search_iter¶

def search_iter(self, data: int | None, iter_cmp: SequenceIterCompareFunc) -> SequenceIter

Like Sequence.search, but uses a GSequenceIterCompareFunc instead of a GCompareDataFunc as the compare function.

iter_cmp is called with two iterators pointing into seq. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first.

If you are simply searching for an existing element of the sequence, consider using Sequence.lookup_iter.

This function will fail if the data contained in the sequence is unsorted.

Parameters:

data — data for the new item
iter_cmp — the function used to compare iterators in the sequence

sort¶

def sort(self, cmp_func: CompareDataFunc) -> None

Sorts seq using cmp_func.

cmp_func is passed two items of seq and should return 0 if they are equal, a negative value if the first comes before the second, and a positive value if the second comes before the first.

Parameters:

cmp_func — the function used to sort the sequence

sort_iter¶

def sort_iter(self, cmp_func: SequenceIterCompareFunc) -> None

Like Sequence.sort, but uses a GSequenceIterCompareFunc instead of a GCompareDataFunc as the compare function

cmp_func is called with two iterators pointing into seq. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first.

Parameters:

cmp_func — the function used to compare iterators in the sequence

Static functions¶

foreach_range¶

@staticmethod
def foreach_range(begin: SequenceIter, end: SequenceIter, func: Func) -> None

Calls func for each item in the range (begin, end) passing user_data to the function. func must not modify the sequence itself.

Parameters:

begin — a SequenceIter
end — a SequenceIter
func — a GFunc

get¶

@staticmethod
def get(iter: SequenceIter) -> int | None

Returns the data that iter points to.

Parameters:

iter — a SequenceIter

insert_before¶

@staticmethod
def insert_before(iter: SequenceIter, data: int | None = ...) -> SequenceIter

Inserts a new item just before the item pointed to by iter.

Parameters:

iter — a SequenceIter
data — the data for the new item

move¶

@staticmethod
def move(src: SequenceIter, dest: SequenceIter) -> None

Moves the item pointed to by src to the position indicated by dest. After calling this function dest will point to the position immediately after src. It is allowed for src and dest to point into different sequences.

Parameters:

src — a SequenceIter pointing to the item to move
dest — a SequenceIter pointing to the position to which the item is moved

move_range¶

@staticmethod
def move_range(dest: SequenceIter, begin: SequenceIter, end: SequenceIter) -> None

Inserts the (begin, end) range at the destination pointed to by dest. The begin and end iters must point into the same sequence. It is allowed for dest to point to a different sequence than the one pointed into by begin and end.

If dest is None, the range indicated by begin and end is removed from the sequence. If dest points to a place within the (begin, end) range, the range does not move.

Parameters:

dest — a SequenceIter
begin — a SequenceIter
end — a SequenceIter

range_get_midpoint¶

@staticmethod
def range_get_midpoint(begin: SequenceIter, end: SequenceIter) -> SequenceIter

Finds an iterator somewhere in the range (begin, end). This iterator will be close to the middle of the range, but is not guaranteed to be exactly in the middle.

The begin and end iterators must both point to the same sequence and begin must come before or be equal to end in the sequence.

Parameters:

begin — a SequenceIter
end — a SequenceIter

remove¶

@staticmethod
def remove(iter: SequenceIter) -> None

Removes the item pointed to by iter. It is an error to pass the end iterator to this function.

If the sequence has a data destroy function associated with it, this function is called on the data for the removed item.

Parameters:

iter — a SequenceIter

remove_range¶

@staticmethod
def remove_range(begin: SequenceIter, end: SequenceIter) -> None

Removes all items in the (begin, end) range.

If the sequence has a data destroy function associated with it, this function is called on the data for the removed items.

Parameters:

begin — a SequenceIter
end — a SequenceIter

set¶

@staticmethod
def set(iter: SequenceIter, data: int | None = ...) -> None

Changes the data for the item pointed to by iter to be data. If the sequence has a data destroy function associated with it, that function is called on the existing data that iter pointed to.

Parameters:

iter — a SequenceIter
data — new data for the item

sort_changed¶

@staticmethod
def sort_changed(iter: SequenceIter, cmp_func: CompareDataFunc) -> None

Moves the data pointed to by iter to a new position as indicated by cmp_func. This function should be called for items in a sequence already sorted according to cmp_func whenever some aspect of an item changes so that cmp_func may return different values for that item.

cmp_func is called with two items of the seq, and cmp_data. It should return 0 if the items are equal, a negative value if the first item comes before the second, and a positive value if the second item comes before the first.

Parameters:

iter — A SequenceIter
cmp_func — the function used to compare items in the sequence

sort_changed_iter¶

@staticmethod
def sort_changed_iter(iter: SequenceIter, iter_cmp: SequenceIterCompareFunc) -> None

Like Sequence.sort_changed, but uses a GSequenceIterCompareFunc instead of a GCompareDataFunc as the compare function.

iter_cmp is called with two iterators pointing into the Sequence that iter points into. It should return 0 if the iterators are equal, a negative value if the first iterator comes before the second, and a positive value if the second iterator comes before the first.

Parameters:

iter — a SequenceIter
iter_cmp — the function used to compare iterators in the sequence

swap¶

@staticmethod
def swap(a: SequenceIter, b: SequenceIter) -> None

Swaps the items pointed to by a and b. It is allowed for a and b to point into difference sequences.

Parameters:

a — a SequenceIter
b — a SequenceIter