sequence.sgml

this is a glib for c language

<!-- ##### 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: