Sequence#

class Sequence(*args, **kwargs)#

The Sequence struct is an opaque data type representing a [sequence][glib-Sequences] data type.

Methods#

class Sequence
append(data: Any = None) → SequenceIter#

Adds a new item to the end of seq.

Added in version 2.14.

Parameters:

data – the data for the new item

foreach(func: Callable[[Any, Any], None], user_data: Any = None) → None#

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

Added in version 2.14.

Parameters:

  • func – the function to call for each item in seq

  • user_data – user data passed to func

classmethod foreach_range(end: SequenceIter, func: Callable[[Any, Any], None], user_data: Any = None) → None#

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

Added in version 2.14.

Parameters:

  • end – a SequenceIter

  • func – a Func

  • user_data – user data passed to func

free() → 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.

Added in version 2.14.

classmethod get() → Any | None#

Returns the data that iter points to.

Added in version 2.14.

get_begin_iter() → SequenceIter#

Returns the begin iterator for seq.

Added in version 2.14.

get_end_iter() → SequenceIter#

Returns the end iterator for seg

Added in version 2.14.

get_iter_at_pos(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.

Added in version 2.14.

Parameters:

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

get_length() → 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 :func:`~gi.repository.GLib.Sequence.is_empty when comparing the length to zero.

Added in version 2.14.

classmethod insert_before(data: Any = None) → SequenceIter#

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

Added in version 2.14.

Parameters:

data – the data for the new item

insert_sorted(data: Any, cmp_func: Callable[[Any, Any, Any], int], cmp_data: Any = None) → 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 sort() or sort_iter().

Added in version 2.14.

Parameters:

  • data – the data to insert

  • cmp_func – the function used to compare items in the sequence

  • cmp_data – user data passed to cmp_func.

insert_sorted_iter(data: Any, iter_cmp: Callable[[SequenceIter, SequenceIter, Any], int], cmp_data: Any = None) → SequenceIter#

Like insert_sorted(), but uses a SequenceIterCompareFunc instead of a CompareDataFunc 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 sort() or sort_iter().

Added in version 2.14.

Parameters:

  • data – data for the new item

  • iter_cmp – the function used to compare iterators in the sequence

  • cmp_data – user data passed to iter_cmp

is_empty() → bool#

Returns True if the sequence contains zero items.

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

Added in version 2.48.

lookup(data: Any, cmp_func: Callable[[Any, Any, Any], int], cmp_data: Any = None) → 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 next() and 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.

Added in version 2.28.

Parameters:

  • data – data to look up

  • cmp_func – the function used to compare items in the sequence

  • cmp_data – user data passed to cmp_func

lookup_iter(data: Any, iter_cmp: Callable[[SequenceIter, SequenceIter, Any], int], cmp_data: Any = None) → SequenceIter | None#

Like lookup(), but uses a SequenceIterCompareFunc instead of a CompareDataFunc 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.

Added in version 2.28.

Parameters:

  • data – data to look up

  • iter_cmp – the function used to compare iterators in the sequence

  • cmp_data – user data passed to iter_cmp

classmethod move(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.

Added in version 2.14.

Parameters:

dest – a SequenceIter pointing to the position to which the item is moved

classmethod move_range(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.

Added in version 2.14.

Parameters:
prepend(data: Any = None) → SequenceIter#

Adds a new item to the front of seq

Added in version 2.14.

Parameters:

data – the data for the new item

classmethod range_get_midpoint(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.

Added in version 2.14.

Parameters:

end – a SequenceIter

classmethod remove() → 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.

Added in version 2.14.

Returns:

0 if the file was successfully removed, -1 if an error occurred

classmethod remove_range(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.

Added in version 2.14.

Parameters:

end – a SequenceIter

search(data: Any, cmp_func: Callable[[Any, Any, Any], int], cmp_data: Any = None) → 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 lookup().

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

Added in version 2.14.

Parameters:

  • data – data for the new item

  • cmp_func – the function used to compare items in the sequence

  • cmp_data – user data passed to cmp_func

search_iter(data: Any, iter_cmp: Callable[[SequenceIter, SequenceIter, Any], int], cmp_data: Any = None) → SequenceIter#

Like search(), but uses a SequenceIterCompareFunc instead of a CompareDataFunc 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 lookup_iter().

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

Added in version 2.14.

Parameters:

  • data – data for the new item

  • iter_cmp – the function used to compare iterators in the sequence

  • cmp_data – user data passed to iter_cmp

classmethod set(data: Any = 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.

Added in version 2.14.

Parameters:

data – new data for the item

sort(cmp_func: Callable[[Any, Any, Any], int], cmp_data: Any = None) → 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.

Added in version 2.14.

Parameters:

  • cmp_func – the function used to sort the sequence

  • cmp_data – user data passed to cmp_func

classmethod sort_changed(cmp_func: Callable[[Any, Any, Any], int], cmp_data: Any = None) → 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.

Added in version 2.14.

Parameters:

  • cmp_func – the function used to compare items in the sequence

  • cmp_data – user data passed to cmp_func.

classmethod sort_changed_iter(iter_cmp: Callable[[SequenceIter, SequenceIter, Any], int], cmp_data: Any = None) → None#

Like sort_changed(), but uses a SequenceIterCompareFunc instead of a CompareDataFunc 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.

Added in version 2.14.

Parameters:

  • iter_cmp – the function used to compare iterators in the sequence

  • cmp_data – user data passed to cmp_func

sort_iter(cmp_func: Callable[[SequenceIter, SequenceIter, Any], int], cmp_data: Any = None) → None#

Like sort(), but uses a SequenceIterCompareFunc instead of a CompareDataFunc 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.

Added in version 2.14.

Parameters:

  • cmp_func – the function used to compare iterators in the sequence

  • cmp_data – user data passed to cmp_func

classmethod swap(b: SequenceIter) → None#

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

Added in version 2.14.

Parameters:

b – a SequenceIter