| <!-- ##### SECTION Title ##### --> |
| Sequences |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| scalable lists |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| |
| <para> |
| The #GSequence data structure has the API of a list, but is |
| implemented internally with a balanced binary tree. This means that it |
| is possible to maintain a sorted list of n elements in time O(n log |
| n). The data contained in each element can be either integer values, by |
| using of the |
| <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>, |
| or simply pointers to any type of data. |
| </para> |
| |
| <para> |
| A #GSequence is accessed through <firstterm>iterators</firstterm>, |
| represented by a #GSequenceIter. An iterator represents a position |
| between two elements of the sequence. For example, the |
| <firstterm>begin</firstterm> iterator represents the gap immediately |
| before the first element of the sequence, and the |
| <firstterm>end</firstterm> iterator represents the gap immediately |
| after the last element. In an empty sequence, the begin and end |
| iterators are the same. |
| </para> |
| |
| <para> |
| Some methods on #GSequence operate on ranges of items. For example |
| g_sequence_foreach_range() will call a user-specified function on each |
| element with the given range. The range is delimited by the gaps |
| represented by the passed-in iterators, so if you pass in the begin |
| and end iterators, the range in question is the entire sequence. |
| </para> |
| |
| |
| <para> |
| The function g_sequence_get() is used with an iterator to access the |
| element immediately following the gap that the iterator |
| represents. The iterator is said to <firstterm>point</firstterm> to |
| that element. |
| </para> |
| |
| <para> |
| Iterators are stable across most operations on a #GSequence. For |
| example an iterator pointing to some element of a sequence will |
| continue to point to that element even after the sequence is |
| sorted. Even moving an element to another sequence using for example |
| g_sequence_move_range() will not invalidate the iterators pointing to |
| it. The only operation that will invalidate an iterator is when the |
| element it points to is removed from any sequence. |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### STRUCT GSequence ##### --> |
| <para> |
| The <structname>GSequence</structname> struct is an opaque data type |
| representing a <link linkend="glib-Sequences">Sequence</link> data type. |
| </para> |
| |
| |
| <!-- ##### TYPEDEF GSequenceIter ##### --> |
| <para> |
| The <structname>GSequenceIter</structname> struct is an opaque data |
| type representing an iterator pointing into a #GSequence. |
| </para> |
| |
| |
| <!-- ##### USER_FUNCTION GSequenceIterCompareFunc ##### --> |
| <para> |
| A #GSequenceIterCompareFunc is a function used to compare |
| iterators. It must return zero if the iterators compare equal, a |
| negative value if @a comes before @b, and a positive value if @b comes |
| before @a. |
| </para> |
| |
| @a: a #GSequenceIter |
| @b: a #GSequenceIter |
| @data: user data |
| @Returns: zero if the iterators are equal, a negative value if @a |
| comes before @b, and a positive value if @b comes before @a. |
| |
| |
| <!-- ##### FUNCTION g_sequence_new ##### --> |
| <para> |
| |
| </para> |
| |
| @data_destroy: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_free ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| |
| |
| <!-- ##### FUNCTION g_sequence_get_length ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_foreach ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @func: |
| @user_data: |
| |
| |
| <!-- ##### FUNCTION g_sequence_foreach_range ##### --> |
| <para> |
| |
| </para> |
| |
| @begin: |
| @end: |
| @func: |
| @user_data: |
| |
| |
| <!-- ##### FUNCTION g_sequence_sort ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @cmp_func: |
| @cmp_data: |
| |
| |
| <!-- ##### FUNCTION g_sequence_sort_iter ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @cmp_func: |
| @cmp_data: |
| |
| |
| <!-- ##### FUNCTION g_sequence_get_begin_iter ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_get_end_iter ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_get_iter_at_pos ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @pos: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_append ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_prepend ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_insert_before ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_move ##### --> |
| <para> |
| |
| </para> |
| |
| @src: |
| @dest: |
| |
| |
| <!-- ##### FUNCTION g_sequence_swap ##### --> |
| <para> |
| |
| </para> |
| |
| @a: |
| @b: |
| |
| |
| <!-- ##### FUNCTION g_sequence_insert_sorted ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @data: |
| @cmp_func: |
| @cmp_data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_insert_sorted_iter ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @data: |
| @iter_cmp: |
| @cmp_data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_sort_changed ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @cmp_func: |
| @cmp_data: |
| |
| |
| <!-- ##### FUNCTION g_sequence_sort_changed_iter ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @iter_cmp: |
| @cmp_data: |
| |
| |
| <!-- ##### FUNCTION g_sequence_remove ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| |
| |
| <!-- ##### FUNCTION g_sequence_remove_range ##### --> |
| <para> |
| |
| </para> |
| |
| @begin: |
| @end: |
| |
| |
| <!-- ##### FUNCTION g_sequence_move_range ##### --> |
| <para> |
| |
| </para> |
| |
| @dest: |
| @begin: |
| @end: |
| |
| |
| <!-- ##### FUNCTION g_sequence_search ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @data: |
| @cmp_func: |
| @cmp_data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_search_iter ##### --> |
| <para> |
| |
| </para> |
| |
| @seq: |
| @data: |
| @iter_cmp: |
| @cmp_data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_get ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_set ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @data: |
| |
| |
| <!-- ##### FUNCTION g_sequence_iter_is_begin ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_iter_is_end ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_iter_next ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_iter_prev ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_iter_get_position ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_iter_move ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @delta: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_iter_get_sequence ##### --> |
| <para> |
| |
| </para> |
| |
| @iter: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_iter_compare ##### --> |
| <para> |
| |
| </para> |
| |
| @a: |
| @b: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_sequence_range_get_midpoint ##### --> |
| <para> |
| |
| </para> |
| |
| @begin: |
| @end: |
| @Returns: |
| |
| |