diff options
author | Soren Sandmann <sandmann@daimi.au.dk> | 2007-02-03 23:24:50 +0000 |
---|---|---|
committer | Søren Sandmann Pedersen <ssp@src.gnome.org> | 2007-02-03 23:24:50 +0000 |
commit | 674c4df418d2be7aeb55462b3534f985560098c3 (patch) | |
tree | d580b6eb91a5a28f592e8d8d0139a76bba184e0c /docs | |
parent | 20a05714cca0946de995c62d994920ec09f3d0c7 (diff) |
New files implementing GSequence, a list implemented using a binary tree.
2007-02-03 Soren Sandmann <sandmann@daimi.au.dk>
* glib/gsequence.[ch]: New files implementing GSequence, a list
implemented using a binary tree.
* glib/glib.h, glib/glib.symbols: Update for GSequence.
* docs/reference: Add documentation for GSequence
* tests: Add sequence-test.c, a thorough test of all of
the GSequence API.
svn path=/trunk/; revision=5322
Diffstat (limited to 'docs')
-rw-r--r-- | docs/reference/glib/glib-docs.sgml | 2 | ||||
-rw-r--r-- | docs/reference/glib/glib-sections.txt | 54 | ||||
-rw-r--r-- | docs/reference/glib/tmpl/glib-unused.sgml | 9 | ||||
-rw-r--r-- | docs/reference/glib/tmpl/keyfile.sgml | 4 | ||||
-rw-r--r-- | docs/reference/glib/tmpl/sequence.sgml | 433 | ||||
-rw-r--r-- | docs/reference/gobject/tmpl/enumerations_flags.sgml | 12 | ||||
-rw-r--r-- | docs/reference/gobject/tmpl/gparamspec.sgml | 4 | ||||
-rw-r--r-- | docs/reference/gobject/tmpl/gtypemodule.sgml | 12 |
8 files changed, 507 insertions, 23 deletions
diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml index e3e55bdc6..82b6302aa 100644 --- a/docs/reference/glib/glib-docs.sgml +++ b/docs/reference/glib/glib-docs.sgml @@ -36,6 +36,7 @@ <!ENTITY glib-Doubly-Linked-Lists SYSTEM "xml/linked_lists_double.xml"> <!ENTITY glib-Singly-Linked-Lists SYSTEM "xml/linked_lists_single.xml"> <!ENTITY glib-Double-ended-Queues SYSTEM "xml/queue.xml"> +<!ENTITY glib-Sequences SYSTEM "xml/sequence.xml"> <!ENTITY glib-Trash-Stacks SYSTEM "xml/trash_stack.xml"> <!ENTITY glib-Hash-Tables SYSTEM "xml/hash_tables.xml"> <!ENTITY glib-Strings SYSTEM "xml/strings.xml"> @@ -163,6 +164,7 @@ synchronize their operation. &glib-Doubly-Linked-Lists; &glib-Singly-Linked-Lists; &glib-Double-ended-Queues; + &glib-Sequences; &glib-Trash-Stacks; &glib-Hash-Tables; &glib-Strings; diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index cbbb8cda5..cd6d354a3 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -1823,6 +1823,60 @@ g_queue_delete_link </SECTION> <SECTION> +<TITLE>Sequences</TITLE> +<FILE>sequence</FILE> + +GSequence +GSequenceIter +GSequenceIterCompareFunc + +<SUBSECTION> +g_sequence_new +g_sequence_free +g_sequence_get_length +g_sequence_foreach +g_sequence_foreach_range +g_sequence_sort +g_sequence_sort_iter + +<SUBSECTION> +g_sequence_get_begin_iter +g_sequence_get_end_iter +g_sequence_get_iter_at_pos +g_sequence_append +g_sequence_prepend +g_sequence_insert_before +g_sequence_move +g_sequence_swap +g_sequence_insert_sorted +g_sequence_insert_sorted_iter +g_sequence_sort_changed +g_sequence_sort_changed_iter +g_sequence_remove +g_sequence_remove_range +g_sequence_move_range +g_sequence_search +g_sequence_search_iter + +<SUBSECTION> +g_sequence_get +g_sequence_set + +<SUBSECTION> +g_sequence_iter_is_begin +g_sequence_iter_is_end +g_sequence_iter_next +g_sequence_iter_prev +g_sequence_iter_get_position +g_sequence_iter_move +g_sequence_iter_get_sequence + +<SUBSECTION> +g_sequence_iter_compare +g_sequence_range_get_midpoint +</SECTION> + +<SECTION> <TITLE>Trash Stacks</TITLE> <FILE>trash_stack</FILE> GTrashStack diff --git a/docs/reference/glib/tmpl/glib-unused.sgml b/docs/reference/glib/tmpl/glib-unused.sgml index de6993de5..b089e6686 100644 --- a/docs/reference/glib/tmpl/glib-unused.sgml +++ b/docs/reference/glib/tmpl/glib-unused.sgml @@ -203,15 +203,6 @@ error domains. </para> -<!-- ##### MACRO G_HAVE_GNUC_VISIBILITY ##### --> -<para> -This macro is defined as 1 if the the compiler supports ELF visibility -attributes (currently only <command>gcc</command>). -</para> - -Since: 2.6 - - <!-- ##### MACRO G_HOOK_DEFERRED_DESTROY ##### --> <para> diff --git a/docs/reference/glib/tmpl/keyfile.sgml b/docs/reference/glib/tmpl/keyfile.sgml index d63ead05a..a427cf090 100644 --- a/docs/reference/glib/tmpl/keyfile.sgml +++ b/docs/reference/glib/tmpl/keyfile.sgml @@ -504,8 +504,6 @@ Flags which influence the parsing. @key_file: @group_name: @key: -@list: -@length: <!-- ##### FUNCTION g_key_file_set_locale_string_list ##### --> @@ -517,8 +515,6 @@ Flags which influence the parsing. @group_name: @key: @locale: -@list: -@length: <!-- ##### FUNCTION g_key_file_set_boolean_list ##### --> diff --git a/docs/reference/glib/tmpl/sequence.sgml b/docs/reference/glib/tmpl/sequence.sgml new file mode 100644 index 000000000..325ab7813 --- /dev/null +++ b/docs/reference/glib/tmpl/sequence.sgml @@ -0,0 +1,433 @@ +<!-- ##### 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: + + diff --git a/docs/reference/gobject/tmpl/enumerations_flags.sgml b/docs/reference/gobject/tmpl/enumerations_flags.sgml index 2b72931f2..1293d2fd8 100644 --- a/docs/reference/gobject/tmpl/enumerations_flags.sgml +++ b/docs/reference/gobject/tmpl/enumerations_flags.sgml @@ -232,11 +232,13 @@ than to write one yourself using g_enum_register_static(). </para> @name: A nul-terminated string used as the name of the new type. +@_static_values: +@Returns: The new type identifier. +<!-- # Unused Parameters # --> @const_static_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. -@Returns: The new type identifier. <!-- ##### FUNCTION g_flags_register_static ##### --> @@ -250,10 +252,12 @@ than to write one yourself using g_flags_register_static(). </para> @name: A nul-terminated string used as the name of the new type. +@_static_values: +@Returns: The new type identifier. +<!-- # Unused Parameters # --> @const_static_values: An array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. -@Returns: The new type identifier. <!-- ##### FUNCTION g_enum_complete_type_info ##### --> @@ -282,6 +286,8 @@ my_enum_complete_type_info (GTypePlugin *plugin, @g_enum_type: the type identifier of the type being completed @info: the #GTypeInfo struct to be filled in +@_values: +<!-- # Unused Parameters # --> @const_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. @@ -296,6 +302,8 @@ g_enumeration_complete_type_info() above. @g_flags_type: the type identifier of the type being completed @info: the #GTypeInfo struct to be filled in +@_values: +<!-- # Unused Parameters # --> @const_values: An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml index eb90ffda1..ceb5803f9 100644 --- a/docs/reference/gobject/tmpl/gparamspec.sgml +++ b/docs/reference/gobject/tmpl/gparamspec.sgml @@ -149,10 +149,6 @@ can be configured. parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 -@G_PARAM_STATIC_NICK: the string used as nick when constructing the - parameter is guaranteed to remain valid and - unmodified for the lifetime of the parameter. - Since 2.8 @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. diff --git a/docs/reference/gobject/tmpl/gtypemodule.sgml b/docs/reference/gobject/tmpl/gtypemodule.sgml index 71ce8f1a0..3b2e9ee75 100644 --- a/docs/reference/gobject/tmpl/gtypemodule.sgml +++ b/docs/reference/gobject/tmpl/gtypemodule.sgml @@ -164,11 +164,13 @@ not be unloaded. @module: a #GTypeModule @name: name for the type +@_static_values: +@Returns: the new or existing type ID +@Since: 2.6 +<!-- # Unused Parameters # --> @const_static_values: an array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. -@Returns: the new or existing type ID -@Since: 2.6 <!-- ##### FUNCTION g_type_module_register_flags ##### --> @@ -185,11 +187,13 @@ not be unloaded. @module: a #GTypeModule @name: name for the type +@_static_values: +@Returns: the new or existing type ID +@Since: 2.6 +<!-- # Unused Parameters # --> @const_static_values: an array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. -@Returns: the new or existing type ID -@Since: 2.6 <!-- ##### MACRO G_DEFINE_DYNAMIC_TYPE ##### --> |