luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 03:16:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

GSequence: move docs from tmpl to .c

Browse Source
This commit is contained in:
Ryan Lortie 2010-01-30 22:19:29 -05:00
parent 0ab7bb4b18
commit 3a161ee8f3
3 changed files with 70 additions and 432 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -5,6 +5,7 @@ gvarianttype.sgml
hash_tables.sgml hash_tables.sgml
option.sgml option.sgml
random_numbers.sgml random_numbers.sgml
sequence.sgml
shell.sgml shell.sgml
threads.sgml threads.sgml
timers.sgml timers.sgml

432
docs/reference/glib/tmpl/sequence.sgml
View File

@ -1,432 +0,0 @@
<!-- ##### 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:

69
glib/gsequence.c
View File

@ -23,8 +23,77 @@
#include "glib.h" #include "glib.h"
#include "galias.h" #include "galias.h"
/**
* SECTION: sequence
* @title: Sequences
* @short_description: scalable lists
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
**/
/**
* GSequenceIter:
*
* The #GSequenceIter struct is an opaque data type representing an
* iterator pointing into a #GSequence.
**/
/**
* GSequenceIterCompareFunc:
* @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.
*
* 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.
**/
typedef struct _GSequenceNode GSequenceNode; typedef struct _GSequenceNode GSequenceNode;
/**
* GSequence:
*
* The #GSequence struct is an opaque data type representing a
* <link linkend="glib-Sequences">Sequence</link> data type.
**/
struct _GSequence struct _GSequence
{ {
GSequenceNode * end_node; GSequenceNode * end_node;