Commit 674c4df4 authored by Soren Sandmann's avatar Soren Sandmann Committed by Søren Sandmann Pedersen

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
parent 20a05714
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.
2007-01-30 Matthias Clasen <mclasen@redhat.com>
* glib/glib.symbols:
......
......@@ -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;
......
......@@ -1822,6 +1822,60 @@ g_queue_unlink
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>
......
......@@ -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>
......
......@@ -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 ##### -->
......
<!-- ##### 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:
......@@ -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.
......
......@@ -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.
......
......@@ -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 ##### -->
......
......@@ -108,6 +108,7 @@ libglib_2_0_la_SOURCES = \
grand.c \
gscanner.c \
gscripttable.h \
gsequence.c \
gshell.c \
gslice.c \
gslist.c \
......@@ -186,6 +187,7 @@ glibsubinclude_HEADERS = \
grand.h \
grel.h \
gscanner.h \
gsequence.h \
gshell.h \
gslice.h \
gslist.h \
......
......@@ -63,6 +63,7 @@
#include <glib/grand.h>
#include <glib/grel.h>
#include <glib/gscanner.h>
#include <glib/gsequence.h>
#include <glib/gshell.h>
#include <glib/gslist.h>
#include <glib/gspawn.h>
......
......@@ -924,6 +924,46 @@ g_scanner_warn G_GNUC_PRINTF(2,3)
#endif
#endif
#if IN_HEADER(__G_SEQUENCE_H__)
#if IN_FILE(__G_SEQUENCE_C__)
g_sequence_new
g_sequence_free
g_sequence_get_length
g_sequence_foreach
g_sequence_foreach_range
g_sequence_sort
g_sequence_sort_iter
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
g_sequence_get
g_sequence_set
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
g_sequence_iter_compare
g_sequence_range_get_midpoint
#endif
#endif
#if IN_HEADER(__G_SHELL_H__)
#if IN_FILE(__G_SHELL_C__)
g_shell_error_quark
......
This diff is collapsed.
/* GLIB - Library of useful routines for C programming
* Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007
* Soeren Sandmann (sandmann@daimi.au.dk)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
#include <glib.h>
#ifndef __G_SEQUENCE_H__
#define __G_SEQUENCE_H__
typedef struct _GSequence GSequence;
typedef struct _GSequenceNode GSequenceIter;
typedef gint (* GSequenceIterCompareFunc) (GSequenceIter *a,
GSequenceIter *b,
gpointer data);
/* GSequence */
GSequence * g_sequence_new (GDestroyNotify data_destroy);
void g_sequence_free (GSequence *seq);
gint g_sequence_get_length (GSequence *seq);
void g_sequence_foreach (GSequence *seq,
GFunc func,
gpointer user_data);
void g_sequence_foreach_range (GSequenceIter *begin,
GSequenceIter *end,
GFunc func,
gpointer user_data);
void g_sequence_sort (GSequence *seq,
GCompareDataFunc cmp_func,