X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=glib%2Fgsequence.c;h=76e24e73bd02b65901b4f4017d7e10c4a62e5127;hb=13e15733f38a40c6ef6a1baede91cce81c86ebaa;hp=5631be31c9808d81c16c3dcd8670eb3afe64156f;hpb=1b033919845cef366842373da9f1cfb56f522d01;p=platform%2Fupstream%2Fglib.git diff --git a/glib/gsequence.c b/glib/gsequence.c index 5631be3..76e24e7 100644 --- a/glib/gsequence.c +++ b/glib/gsequence.c @@ -13,9 +13,7 @@ * 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. + * License along with this library; if not, see . */ #include "config.h" @@ -24,6 +22,7 @@ #include "gmem.h" #include "gtestutils.h" +#include "gslice.h" /** * SECTION:sequence * @title: Sequences @@ -31,18 +30,16 @@ * * 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 Type Conversion Macros, - * or simply pointers to any type of data. - * - * A #GSequence is accessed through iterators, - * represented by a #GSequenceIter. An iterator represents a position - * between two elements of the sequence. For example, the - * begin iterator represents the gap immediately - * before the first element of the sequence, and the - * end iterator represents the gap immediately + * 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 [Type Conversion Macros][glib-Type-Conversion-Macros], or simply + * pointers to any type of data. + * + * A #GSequence is accessed through "iterators", represented by a + * #GSequenceIter. An iterator represents a position between two + * elements of the sequence. For example, the "begin" iterator + * represents the gap immediately before the first element of the + * sequence, and the "end" iterator represents the gap immediately * after the last element. In an empty sequence, the begin and end * iterators are the same. * @@ -55,7 +52,7 @@ * * 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 point to that element. + * The iterator is said to "point" to that element. * * Iterators are stable across most operations on a #GSequence. For * example an iterator pointing to some element of a sequence will @@ -64,28 +61,28 @@ * 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. - **/ + * + * Returns: zero if the iterators are equal, a negative value if @a + * comes before @b, and a positive value if @b comes before @a. + */ typedef struct _GSequenceNode GSequenceNode; @@ -93,8 +90,8 @@ typedef struct _GSequenceNode GSequenceNode; * GSequence: * * The #GSequence struct is an opaque data type representing a - * Sequence data type. - **/ + * [sequence][glib-Sequences] data type. + */ struct _GSequence { GSequenceNode * end_node; @@ -238,13 +235,13 @@ iter_compare (GSequenceIter *node1, /** * g_sequence_new: - * @data_destroy: a #GDestroyNotify function, or %NULL + * @data_destroy: (allow-none): a #GDestroyNotify function, or %NULL * * Creates a new GSequence. The @data_destroy function, if non-%NULL will * be called on all items when the sequence is destroyed and on items that * are removed from the sequence. * - * Return value: a new #GSequence + * Returns: a new #GSequence * * Since: 2.14 **/ @@ -268,11 +265,11 @@ g_sequence_new (GDestroyNotify data_destroy) * @seq: a #GSequence * * Frees the memory allocated for @seq. If @seq has a data destroy - * function associated with it, that function is called on all items in - * @seq. + * function associated with it, that function is called on all items + * in @seq. * * Since: 2.14 - **/ + */ void g_sequence_free (GSequence *seq) { @@ -296,7 +293,7 @@ g_sequence_free (GSequence *seq) * @user_data to the function. * * Since: 2.14 - **/ + */ void g_sequence_foreach_range (GSequenceIter *begin, GSequenceIter *end, @@ -337,7 +334,7 @@ g_sequence_foreach_range (GSequenceIter *begin, * to the function. * * Since: 2.14 - **/ + */ void g_sequence_foreach (GSequence *seq, GFunc func, @@ -360,16 +357,16 @@ g_sequence_foreach (GSequence *seq, * * Finds an iterator somewhere in the range (@begin, @end). This * iterator will be close to the middle of the range, but is not - * guaranteed to be exactly in the middle. + * guaranteed to be exactly in the middle. * - * The @begin and @end iterators must both point to the same sequence and - * @begin must come before or be equal to @end in the sequence. + * The @begin and @end iterators must both point to the same sequence + * and @begin must come before or be equal to @end in the sequence. * - * Return value: A #GSequenceIter pointing somewhere in the - * (@begin, @end) range. + * Returns: a #GSequenceIter pointing somewhere in the + * (@begin, @end) range * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_range_get_midpoint (GSequenceIter *begin, GSequenceIter *end) @@ -400,11 +397,11 @@ g_sequence_range_get_midpoint (GSequenceIter *begin, * * The @a and @b iterators must point into the same sequence. * - * Return value: A negative number if @a comes before @b, 0 if they are - * equal, and a positive number if @a comes after @b. + * Returns: a negative number if @a comes before @b, 0 if they are + * equal, and a positive number if @a comes after @b * * Since: 2.14 - **/ + */ gint g_sequence_iter_compare (GSequenceIter *a, GSequenceIter *b) @@ -436,10 +433,10 @@ g_sequence_iter_compare (GSequenceIter *a, * * Adds a new item to the end of @seq. * - * Return value: an iterator pointing to the new item + * Returns: an iterator pointing to the new item * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_append (GSequence *seq, gpointer data) @@ -463,10 +460,10 @@ g_sequence_append (GSequence *seq, * * Adds a new item to the front of @seq * - * Return value: an iterator pointing to the new item + * Returns: an iterator pointing to the new item * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_prepend (GSequence *seq, gpointer data) @@ -492,10 +489,10 @@ g_sequence_prepend (GSequence *seq, * * Inserts a new item just before the item pointed to by @iter. * - * Return value: an iterator pointing to the new item + * Returns: an iterator pointing to the new item * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_insert_before (GSequenceIter *iter, gpointer data) @@ -520,11 +517,11 @@ g_sequence_insert_before (GSequenceIter *iter, * Removes the item pointed to by @iter. It is an error to pass the * end iterator to this function. * - * If the sequnce has a data destroy function associated with it, this + * If the sequence has a data destroy function associated with it, this * function is called on the data for the removed item. * * Since: 2.14 - **/ + */ void g_sequence_remove (GSequenceIter *iter) { @@ -552,7 +549,7 @@ g_sequence_remove (GSequenceIter *iter) * function is called on the data for the removed items. * * Since: 2.14 - **/ + */ void g_sequence_remove_range (GSequenceIter *begin, GSequenceIter *end) @@ -581,7 +578,7 @@ g_sequence_remove_range (GSequenceIter *begin, * the (@begin, @end) range, the range does not move. * * Since: 2.14 - **/ + */ void g_sequence_move_range (GSequenceIter *dest, GSequenceIter *begin, @@ -660,7 +657,7 @@ g_sequence_move_range (GSequenceIter *dest, * if the second comes before the first. * * Since: 2.14 - **/ + */ void g_sequence_sort (GSequence *seq, GCompareDataFunc cmp_func, @@ -693,10 +690,10 @@ g_sequence_sort (GSequence *seq, * if the first item comes before the second, and a positive value * if the second item comes before the first. * - * Return value: a #GSequenceIter pointing to the new item. + * Returns: a #GSequenceIter pointing to the new item. * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_insert_sorted (GSequence *seq, gpointer data, @@ -733,7 +730,7 @@ g_sequence_insert_sorted (GSequence *seq, * the second item comes before the first. * * Since: 2.14 - **/ + */ void g_sequence_sort_changed (GSequenceIter *iter, GCompareDataFunc cmp_func, @@ -756,7 +753,7 @@ g_sequence_sort_changed (GSequenceIter *iter, * @seq: a #GSequence * @data: data for the new item * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func. + * @cmp_data: user data passed to @cmp_func * * Returns an iterator pointing to the position where @data would * be inserted according to @cmp_func and @cmp_data. @@ -769,11 +766,17 @@ g_sequence_sort_changed (GSequenceIter *iter, * If you are simply searching for an existing element of the sequence, * consider using g_sequence_lookup(). * - * Return value: an #GSequenceIter pointing to the position where @data - * would have been inserted according to @cmp_func and @cmp_data. + * This function will fail if the data contained in the sequence is + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. + * + * Returns: an #GSequenceIter pointing to the position where @data + * would have been inserted according to @cmp_func and @cmp_data * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_search (GSequence *seq, gpointer data, @@ -797,7 +800,7 @@ g_sequence_search (GSequence *seq, * @seq: a #GSequence * @data: data to lookup * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func. + * @cmp_data: user data passed to @cmp_func * * Returns an iterator pointing to the position of the first item found * equal to @data according to @cmp_func and @cmp_data. If more than one @@ -810,16 +813,23 @@ g_sequence_search (GSequence *seq, * the first item comes before the second, and a positive value if * the second item comes before the first. * - * Return value: an #GSequenceIter pointing to the position of the - * first item found equal to @data according to @cmp_func and @cmp_data. + * This function will fail if the data contained in the sequence is + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. + * + * Returns: an #GSequenceIter pointing to the position of the + * first item found equal to @data according to @cmp_func and + * @cmp_data, or %NULL if no such item exists * * Since: 2.28 - **/ + */ GSequenceIter * -g_sequence_lookup (GSequence *seq, - gpointer data, - GCompareDataFunc cmp_func, - gpointer cmp_data) +g_sequence_lookup (GSequence *seq, + gpointer data, + GCompareDataFunc cmp_func, + gpointer cmp_data) { SortInfo info; @@ -848,7 +858,7 @@ g_sequence_lookup (GSequence *seq, * iterator comes before the first. * * Since: 2.14 - **/ + */ void g_sequence_sort_iter (GSequence *seq, GSequenceIterCompareFunc cmp_func, @@ -903,7 +913,7 @@ g_sequence_sort_iter (GSequence *seq, * iterator comes before the first. * * Since: 2.14 - **/ + */ void g_sequence_sort_changed_iter (GSequenceIter *iter, GSequenceIterCompareFunc iter_cmp, @@ -970,10 +980,10 @@ g_sequence_sort_changed_iter (GSequenceIter *iter, * first iterator comes before the second, and a positive value * if the second iterator comes before the first. * - * Return value: a #GSequenceIter pointing to the new item + * Returns: a #GSequenceIter pointing to the new item * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_insert_sorted_iter (GSequence *seq, gpointer data, @@ -1035,12 +1045,18 @@ g_sequence_insert_sorted_iter (GSequence *seq, * If you are simply searching for an existing element of the sequence, * consider using g_sequence_lookup_iter(). * - * Return value: a #GSequenceIter pointing to the position in @seq + * This function will fail if the data contained in the sequence is + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. + * + * Returns: a #GSequenceIter pointing to the position in @seq * where @data would have been inserted according to @iter_cmp - * and @cmp_data. + * and @cmp_data * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_search_iter (GSequence *seq, gpointer data, @@ -1087,17 +1103,23 @@ g_sequence_search_iter (GSequence *seq, * if the first iterator comes before the second, and a positive * value if the second iterator comes before the first. * - * Return value: an #GSequenceIter pointing to the position of + * This function will fail if the data contained in the sequence is + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. + * + * Returns: an #GSequenceIter pointing to the position of * the first item found equal to @data according to @cmp_func - * and @cmp_data. + * and @cmp_data, or %NULL if no such item exists * * Since: 2.28 - **/ + */ GSequenceIter * -g_sequence_lookup_iter (GSequence *seq, - gpointer data, - GSequenceIterCompareFunc iter_cmp, - gpointer cmp_data) +g_sequence_lookup_iter (GSequence *seq, + gpointer data, + GSequenceIterCompareFunc iter_cmp, + gpointer cmp_data) { GSequenceNode *node; GSequenceNode *dummy; @@ -1130,10 +1152,10 @@ g_sequence_lookup_iter (GSequence *seq, * * Returns the #GSequence that @iter points into. * - * Return value: the #GSequence that @iter points into. + * Returns: the #GSequence that @iter points into * * Since: 2.14 - **/ + */ GSequence * g_sequence_iter_get_sequence (GSequenceIter *iter) { @@ -1155,10 +1177,10 @@ g_sequence_iter_get_sequence (GSequenceIter *iter) * * Returns the data that @iter points to. * - * Return value: the data that @iter points to + * Returns: the data that @iter points to * * Since: 2.14 - **/ + */ gpointer g_sequence_get (GSequenceIter *iter) { @@ -1178,7 +1200,7 @@ g_sequence_get (GSequenceIter *iter) * function is called on the existing data that @iter pointed to. * * Since: 2.14 - **/ + */ void g_sequence_set (GSequenceIter *iter, gpointer data) @@ -1211,10 +1233,10 @@ g_sequence_set (GSequenceIter *iter, * * Returns the length of @seq * - * Return value: the length of @seq + * Returns: the length of @seq * * Since: 2.14 - **/ + */ gint g_sequence_get_length (GSequence *seq) { @@ -1227,10 +1249,10 @@ g_sequence_get_length (GSequence *seq) * * Returns the end iterator for @seg * - * Return value: the end iterator for @seq + * Returns: the end iterator for @seq * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_get_end_iter (GSequence *seq) { @@ -1245,10 +1267,10 @@ g_sequence_get_end_iter (GSequence *seq) * * Returns the begin iterator for @seq. * - * Return value: the begin iterator for @seq. + * Returns: the begin iterator for @seq. * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_get_begin_iter (GSequence *seq) { @@ -1275,15 +1297,15 @@ clamp_position (GSequence *seq, /** * g_sequence_get_iter_at_pos: * @seq: a #GSequence - * @pos: a position in @seq, or -1 for the end. + * @pos: a position in @seq, or -1 for the end * * Returns the iterator at position @pos. If @pos is negative or larger * than the number of items in @seq, the end iterator is returned. * - * Return value: The #GSequenceIter at position @pos + * Returns: The #GSequenceIter at position @pos * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_get_iter_at_pos (GSequence *seq, gint pos) @@ -1299,7 +1321,7 @@ g_sequence_get_iter_at_pos (GSequence *seq, * g_sequence_move: * @src: a #GSequenceIter pointing to the item to move * @dest: a #GSequenceIter pointing to the position to which - * the item is moved. + * the item is moved * * Moves the item pointed to by @src to the position indicated by @dest. * After calling this function @dest will point to the position immediately @@ -1331,10 +1353,10 @@ g_sequence_move (GSequenceIter *src, * * Returns whether @iter is the end iterator * - * Return value: Whether @iter is the end iterator. + * Returns: Whether @iter is the end iterator * * Since: 2.14 - **/ + */ gboolean g_sequence_iter_is_end (GSequenceIter *iter) { @@ -1349,10 +1371,10 @@ g_sequence_iter_is_end (GSequenceIter *iter) * * Returns whether @iter is the begin iterator * - * Return value: whether @iter is the begin iterator + * Returns: whether @iter is the begin iterator * * Since: 2.14 - **/ + */ gboolean g_sequence_iter_is_begin (GSequenceIter *iter) { @@ -1367,10 +1389,10 @@ g_sequence_iter_is_begin (GSequenceIter *iter) * * Returns the position of @iter * - * Return value: the position of @iter + * Returns: the position of @iter * * Since: 2.14 - **/ + */ gint g_sequence_iter_get_position (GSequenceIter *iter) { @@ -1383,13 +1405,13 @@ g_sequence_iter_get_position (GSequenceIter *iter) * g_sequence_iter_next: * @iter: a #GSequenceIter * - * Returns an iterator pointing to the next position after @iter. If - * @iter is the end iterator, the end iterator is returned. + * Returns an iterator pointing to the next position after @iter. + * If @iter is the end iterator, the end iterator is returned. * - * Return value: a #GSequenceIter pointing to the next position after @iter. + * Returns: a #GSequenceIter pointing to the next position after @iter * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_iter_next (GSequenceIter *iter) { @@ -1402,14 +1424,14 @@ g_sequence_iter_next (GSequenceIter *iter) * g_sequence_iter_prev: * @iter: a #GSequenceIter * - * Returns an iterator pointing to the previous position before @iter. If - * @iter is the begin iterator, the begin iterator is returned. + * Returns an iterator pointing to the previous position before @iter. + * If @iter is the begin iterator, the begin iterator is returned. * - * Return value: a #GSequenceIter pointing to the previous position before - * @iter. + * Returns: a #GSequenceIter pointing to the previous position + * before @iter * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_iter_prev (GSequenceIter *iter) { @@ -1422,17 +1444,17 @@ g_sequence_iter_prev (GSequenceIter *iter) * g_sequence_iter_move: * @iter: a #GSequenceIter * @delta: A positive or negative number indicating how many positions away - * from @iter the returned #GSequenceIter will be. + * from @iter the returned #GSequenceIter will be * * Returns the #GSequenceIter which is @delta positions away from @iter. * If @iter is closer than -@delta positions to the beginning of the sequence, * the begin iterator is returned. If @iter is closer than @delta positions * to the end of the sequence, the end iterator is returned. * - * Return value: a #GSequenceIter which is @delta positions away from @iter. + * Returns: a #GSequenceIter which is @delta positions away from @iter * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_iter_move (GSequenceIter *iter, gint delta) @@ -1463,7 +1485,7 @@ g_sequence_iter_move (GSequenceIter *iter, * to point into difference sequences. * * Since: 2.14 - **/ + */ void g_sequence_swap (GSequenceIter *a, GSequenceIter *b)