GSequence: add note about lookup requiring sorting

g_sequence_lookup() only works on sorted sequences, but it's quite easy
to create unsorted sequences.  Add a note to the documentation that the
sequence must be sorted in order for g_sequence_lookup() to work.

https://bugzilla.gnome.org/show_bug.cgi?id=670969

diff --git a/glib/gsequence.c b/glib/gsequence.c
index c17357a..165fb38 100644 (file)
--- a/glib/gsequence.c
+++ b/glib/gsequence.c
@@ -770,6 +770,14 @@ g_sequence_sort_changed (GSequenceIter    *iter,
  * If you are simply searching for an existing element of the sequence,
  * consider using g_sequence_lookup().
  *
+ * <note><para>
+ * 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.
+ * </para></note>
+ *
  * Return value: an #GSequenceIter pointing to the position where @data
  * would have been inserted according to @cmp_func and @cmp_data.
  *
@@ -811,6 +819,14 @@ g_sequence_search (GSequence        *seq,
  * the first item comes before the second, and a positive value if
  * the second item comes before the first.
  *
+ * <note><para>
+ * 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.
+ * </para></note>
+ *
  * Return value: an #GSequenceIter pointing to the position of the
  *     first item found equal to @data according to @cmp_func and @cmp_data.
  *
@@ -1036,6 +1052,14 @@ 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().
  *
+ * <note><para>
+ * 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.
+ * </para></note>
+ *
  * Return value: a #GSequenceIter pointing to the position in @seq
  *     where @data would have been inserted according to @iter_cmp
  *     and @cmp_data.
@@ -1088,6 +1112,14 @@ 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.
  *
+ * <note><para>
+ * 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.
+ * </para></note>
+ *
  * Return value: an #GSequenceIter pointing to the position of
  *     the first item found equal to @data according to @cmp_func
  *     and @cmp_data.