:right-sidebar: True Sequence =================================================================== .. currentmodule:: gi.repository.GLib .. class:: Sequence(*args, **kwargs) :no-contents-entry: The :obj:`~gi.repository.GLib.Sequence` struct is an opaque data type representing a [sequence][glib-Sequences] data type. Methods ------- .. rst-class:: interim-class .. class:: Sequence :no-index: .. method:: append(data: ~typing.Any = None) -> ~gi.repository.GLib.SequenceIter Adds a new item to the end of ``seq``\. .. versionadded:: 2.14 :param data: the data for the new item .. method:: foreach(func: ~typing.Callable[[~typing.Any, ~typing.Any], None], user_data: ~typing.Any = None) -> None Calls ``func`` for each item in the sequence passing ``user_data`` to the function. ``func`` must not modify the sequence itself. .. versionadded:: 2.14 :param func: the function to call for each item in ``seq`` :param user_data: user data passed to ``func`` .. classmethod:: foreach_range(end: ~gi.repository.GLib.SequenceIter, func: ~typing.Callable[[~typing.Any, ~typing.Any], None], user_data: ~typing.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. .. versionadded:: 2.14 :param end: a :obj:`~gi.repository.GLib.SequenceIter` :param func: a :obj:`~gi.repository.GLib.Func` :param user_data: user data passed to ``func`` .. method:: 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``\. .. versionadded:: 2.14 .. classmethod:: get() -> ~typing.Any | None Returns the data that ``iter`` points to. .. versionadded:: 2.14 .. method:: get_begin_iter() -> ~gi.repository.GLib.SequenceIter Returns the begin iterator for ``seq``\. .. versionadded:: 2.14 .. method:: get_end_iter() -> ~gi.repository.GLib.SequenceIter Returns the end iterator for ``seg`` .. versionadded:: 2.14 .. method:: get_iter_at_pos(pos: int) -> ~gi.repository.GLib.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. .. versionadded:: 2.14 :param pos: a position in ``seq``\, or -1 for the end .. method:: 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. .. versionadded:: 2.14 .. classmethod:: insert_before(data: ~typing.Any = None) -> ~gi.repository.GLib.SequenceIter Inserts a new item just before the item pointed to by ``iter``\. .. versionadded:: 2.14 :param data: the data for the new item .. method:: insert_sorted(data: ~typing.Any, cmp_func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], cmp_data: ~typing.Any = None) -> ~gi.repository.GLib.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 :obj:`~gi.repository.GLib.Sequence`\, it is more efficient to do unsorted insertions and then call :func:`~gi.repository.GLib.Sequence.sort` or :func:`~gi.repository.GLib.Sequence.sort_iter`. .. versionadded:: 2.14 :param data: the data to insert :param cmp_func: the function used to compare items in the sequence :param cmp_data: user data passed to ``cmp_func``\. .. method:: insert_sorted_iter(data: ~typing.Any, iter_cmp: ~typing.Callable[[~gi.repository.GLib.SequenceIter, ~gi.repository.GLib.SequenceIter, ~typing.Any], int], cmp_data: ~typing.Any = None) -> ~gi.repository.GLib.SequenceIter Like :func:`~gi.repository.GLib.Sequence.insert_sorted`, but uses a :obj:`~gi.repository.GLib.SequenceIterCompareFunc` instead of a :obj:`~gi.repository.GLib.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 :obj:`~gi.repository.GLib.Sequence`\, it is more efficient to do unsorted insertions and then call :func:`~gi.repository.GLib.Sequence.sort` or :func:`~gi.repository.GLib.Sequence.sort_iter`. .. versionadded:: 2.14 :param data: data for the new item :param iter_cmp: the function used to compare iterators in the sequence :param cmp_data: user data passed to ``iter_cmp`` .. method:: is_empty() -> bool Returns :const:`True` if the sequence contains zero items. This function is functionally identical to checking the result of :func:`~gi.repository.GLib.Sequence.get_length` being equal to zero. However this function is implemented in O(1) running time. .. versionadded:: 2.48 .. method:: lookup(data: ~typing.Any, cmp_func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], cmp_data: ~typing.Any = None) -> ~gi.repository.GLib.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 :func:`~gi.repository.GLib.SequenceIter.next` and :func:`~gi.repository.GLib.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. .. versionadded:: 2.28 :param data: data to look up :param cmp_func: the function used to compare items in the sequence :param cmp_data: user data passed to ``cmp_func`` .. method:: lookup_iter(data: ~typing.Any, iter_cmp: ~typing.Callable[[~gi.repository.GLib.SequenceIter, ~gi.repository.GLib.SequenceIter, ~typing.Any], int], cmp_data: ~typing.Any = None) -> ~gi.repository.GLib.SequenceIter | None Like :func:`~gi.repository.GLib.Sequence.lookup`, but uses a :obj:`~gi.repository.GLib.SequenceIterCompareFunc` instead of a :obj:`~gi.repository.GLib.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. .. versionadded:: 2.28 :param data: data to look up :param iter_cmp: the function used to compare iterators in the sequence :param cmp_data: user data passed to ``iter_cmp`` .. classmethod:: move(dest: ~gi.repository.GLib.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. .. versionadded:: 2.14 :param dest: a :obj:`~gi.repository.GLib.SequenceIter` pointing to the position to which the item is moved .. classmethod:: move_range(begin: ~gi.repository.GLib.SequenceIter, end: ~gi.repository.GLib.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 :const:`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. .. versionadded:: 2.14 :param begin: a :obj:`~gi.repository.GLib.SequenceIter` :param end: a :obj:`~gi.repository.GLib.SequenceIter` .. method:: prepend(data: ~typing.Any = None) -> ~gi.repository.GLib.SequenceIter Adds a new item to the front of ``seq`` .. versionadded:: 2.14 :param data: the data for the new item .. classmethod:: range_get_midpoint(end: ~gi.repository.GLib.SequenceIter) -> ~gi.repository.GLib.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. .. versionadded:: 2.14 :param end: a :obj:`~gi.repository.GLib.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. .. versionadded:: 2.14 :return: 0 if the file was successfully removed, -1 if an error occurred .. classmethod:: remove_range(end: ~gi.repository.GLib.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. .. versionadded:: 2.14 :param end: a :obj:`~gi.repository.GLib.SequenceIter` .. method:: search(data: ~typing.Any, cmp_func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], cmp_data: ~typing.Any = None) -> ~gi.repository.GLib.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 :func:`~gi.repository.GLib.Sequence.lookup`. This function will fail if the data contained in the sequence is unsorted. .. versionadded:: 2.14 :param data: data for the new item :param cmp_func: the function used to compare items in the sequence :param cmp_data: user data passed to ``cmp_func`` .. method:: search_iter(data: ~typing.Any, iter_cmp: ~typing.Callable[[~gi.repository.GLib.SequenceIter, ~gi.repository.GLib.SequenceIter, ~typing.Any], int], cmp_data: ~typing.Any = None) -> ~gi.repository.GLib.SequenceIter Like :func:`~gi.repository.GLib.Sequence.search`, but uses a :obj:`~gi.repository.GLib.SequenceIterCompareFunc` instead of a :obj:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.Sequence.lookup_iter`. This function will fail if the data contained in the sequence is unsorted. .. versionadded:: 2.14 :param data: data for the new item :param iter_cmp: the function used to compare iterators in the sequence :param cmp_data: user data passed to ``iter_cmp`` .. classmethod:: set(data: ~typing.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. .. versionadded:: 2.14 :param data: new data for the item .. method:: sort(cmp_func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], cmp_data: ~typing.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. .. versionadded:: 2.14 :param cmp_func: the function used to sort the sequence :param cmp_data: user data passed to ``cmp_func`` .. classmethod:: sort_changed(cmp_func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], cmp_data: ~typing.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. .. versionadded:: 2.14 :param cmp_func: the function used to compare items in the sequence :param cmp_data: user data passed to ``cmp_func``\. .. classmethod:: sort_changed_iter(iter_cmp: ~typing.Callable[[~gi.repository.GLib.SequenceIter, ~gi.repository.GLib.SequenceIter, ~typing.Any], int], cmp_data: ~typing.Any = None) -> None Like :func:`~gi.repository.GLib.Sequence.sort_changed`, but uses a :obj:`~gi.repository.GLib.SequenceIterCompareFunc` instead of a :obj:`~gi.repository.GLib.CompareDataFunc` as the compare function. ``iter_cmp`` is called with two iterators pointing into the :obj:`~gi.repository.GLib.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. .. versionadded:: 2.14 :param iter_cmp: the function used to compare iterators in the sequence :param cmp_data: user data passed to ``cmp_func`` .. method:: sort_iter(cmp_func: ~typing.Callable[[~gi.repository.GLib.SequenceIter, ~gi.repository.GLib.SequenceIter, ~typing.Any], int], cmp_data: ~typing.Any = None) -> None Like :func:`~gi.repository.GLib.Sequence.sort`, but uses a :obj:`~gi.repository.GLib.SequenceIterCompareFunc` instead of a :obj:`~gi.repository.GLib.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. .. versionadded:: 2.14 :param cmp_func: the function used to compare iterators in the sequence :param cmp_data: user data passed to ``cmp_func`` .. classmethod:: swap(b: ~gi.repository.GLib.SequenceIter) -> None Swaps the items pointed to by ``a`` and ``b``\. It is allowed for ``a`` and ``b`` to point into difference sequences. .. versionadded:: 2.14 :param b: a :obj:`~gi.repository.GLib.SequenceIter`