luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-03-26 09:30:04 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: GSequence: better document how to sort large amount of data

Browse Source 
It was documented at strange places: in g_sequence_search*() and
g_sequence_lookup*(), but how to insert and sort data is not done by
those functions.

So instead, add the information to the class description (since it
involves several functions), and add also the information in
g_sequence_insert_sorted() and g_sequence_insert_sorted_iter() as a kind
of warning when using those functions.

Note that before this commit, it was not explained *why* it is better to
call g_sequence_sort() after doing a lot of unsorted insertions. Now it
is documented as "more efficient" (I think it's the only reason that
makes sense, otherwise why was it documented?).

https://bugzilla.gnome.org/show_bug.cgi?id=792455
This commit is contained in:
Sébastien Wilmet 2018-01-05 15:13:44 +01:00
parent c685ce973d
commit 3ee859d5fc
1 changed files with 18 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
glib/gsequence.c
View File

@ -61,6 +61,12 @@
* 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.
*
* To sort the data, either use g_sequence_insert_sorted() or
* g_sequence_insert_sorted_iter() to add data to the #GSequence or, if
* you want to add a large amount of data, it is more efficient to call
* g_sequence_sort() or g_sequence_sort_iter() after doing unsorted
* insertions.
*/
/**
@ -707,6 +713,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.
*
* Note that when adding a large amount of data to a #GSequence,
* it is more efficient to do unsorted insertions and then call
* g_sequence_sort() or g_sequence_sort_iter().
*
* Returns: (transfer none): a #GSequenceIter pointing to the new item.
*
* Since: 2.14
@ -788,10 +798,7 @@ g_sequence_sort_changed (GSequenceIter *iter,
* consider using g_sequence_lookup().
*
* 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.
* unsorted.
*
* Returns: (transfer none): an #GSequenceIter pointing to the position where @data
* would have been inserted according to @cmp_func and @cmp_data
@ -835,10 +842,7 @@ g_sequence_search (GSequence *seq,
* the second item comes before the first.
*
* 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.
* unsorted.
*
* Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of the
* first item found equal to @data according to @cmp_func and
@ -1002,6 +1006,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.
*
* Note that when adding a large amount of data to a #GSequence,
* it is more efficient to do unsorted insertions and then call
* g_sequence_sort() or g_sequence_sort_iter().
*
* Returns: (transfer none): a #GSequenceIter pointing to the new item
*
* Since: 2.14
@ -1068,10 +1076,7 @@ g_sequence_insert_sorted_iter (GSequence *seq,
* consider using g_sequence_lookup_iter().
*
* 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.
* unsorted.
*
* Returns: (transfer none): a #GSequenceIter pointing to the position in @seq
* where @data would have been inserted according to @iter_cmp
@ -1126,10 +1131,7 @@ g_sequence_search_iter (GSequence *seq,
* value if the second iterator comes before the first.
*
* 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.
* unsorted.
*
* Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of
* the first item found equal to @data according to @cmp_func