* 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 <http://www.gnu.org/licenses/>.
*/
#include "config.h"
*
* 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.
- *
- * 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
+ * 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.
*
*
* 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.
+ * 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
* 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;
* GSequence:
*
* The #GSequence struct is an opaque data type representing a
- * <link linkend="glib-Sequences">Sequence</link> data type.
- **/
+ * [sequence][glib-Sequences] data type.
+ */
struct _GSequence
{
GSequenceNode * end_node;
/**
* 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
**/
* @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)
{
* @user_data to the function.
*
* Since: 2.14
- **/
+ */
void
g_sequence_foreach_range (GSequenceIter *begin,
GSequenceIter *end,
* to the function.
*
* Since: 2.14
- **/
+ */
void
g_sequence_foreach (GSequence *seq,
GFunc func,
*
* 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 <emphasis>exactly</emphasis> 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)
*
* 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)
*
* 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)
*
* 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)
*
* 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)
* 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)
{
* function is called on the data for the removed items.
*
* Since: 2.14
- **/
+ */
void
g_sequence_remove_range (GSequenceIter *begin,
GSequenceIter *end)
* the (@begin, @end) range, the range does not move.
*
* Since: 2.14
- **/
+ */
void
g_sequence_move_range (GSequenceIter *dest,
GSequenceIter *begin,
* if the second comes before the first.
*
* Since: 2.14
- **/
+ */
void
g_sequence_sort (GSequence *seq,
GCompareDataFunc cmp_func,
* 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,
* the second item comes before the first.
*
* Since: 2.14
- **/
+ */
void
g_sequence_sort_changed (GSequenceIter *iter,
GCompareDataFunc cmp_func,
* @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.
* 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,
* @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
* 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;
* iterator comes before the first.
*
* Since: 2.14
- **/
+ */
void
g_sequence_sort_iter (GSequence *seq,
GSequenceIterCompareFunc cmp_func,
* iterator comes before the first.
*
* Since: 2.14
- **/
+ */
void
g_sequence_sort_changed_iter (GSequenceIter *iter,
GSequenceIterCompareFunc iter_cmp,
* 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,
* 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,
* 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;
*
* 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)
{
*
* 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)
{
* function is called on the existing data that @iter pointed to.
*
* Since: 2.14
- **/
+ */
void
g_sequence_set (GSequenceIter *iter,
gpointer data)
*
* 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)
{
*
* 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)
{
*
* 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)
{
/**
* 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)
* 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
*
* 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)
{
*
* 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)
{
*
* 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)
{
* 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)
{
* 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)
{
* 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)
* to point into difference sequences.
*
* Since: 2.14
- **/
+ */
void
g_sequence_swap (GSequenceIter *a,
GSequenceIter *b)
projects / platform / upstream / glib.git / blobdiff