From 8164220213da820d04ffef7479aa092c6e97f469 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 24 Sep 2023 23:14:34 -0400 Subject: [PATCH] docs: Move the sequence SECTION Add the contents to the data-structures.md file. Helps: #3037 --- docs/reference/glib/data-structures.md | 33 ++++++++++++++++++ glib/gsequence.c | 48 -------------------------- 2 files changed, 33 insertions(+), 48 deletions(-) diff --git a/docs/reference/glib/data-structures.md b/docs/reference/glib/data-structures.md index 995b2777c..f9a5da0e2 100644 --- a/docs/reference/glib/data-structures.md +++ b/docs/reference/glib/data-structures.md @@ -4,6 +4,7 @@ SPDX-FileCopyrightText: 2010 Allison Lortie SPDX-FileCopyrightText: 2011 Collabora, Ltd. SPDX-FileCopyrightText: 2012 Olivier Sessink SPDX-FileCopyrightText: 2010, 2011, 2014 Matthias Clasen +SPDX-FileCopyrightText: 2018 Sébastien Wilmet SPDX-FileCopyrightText: 2019 Emmanuel Fleury SPDX-FileCopyrightText: 2017, 2018, 2019 Endless Mobile, Inc. SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC @@ -422,3 +423,35 @@ To traverse a tree, calling a function for each node visited in the traversal, u [method@GLib.Node.traverse] or [method@GLib.Node.children_foreach]. To remove a node or subtree from a tree use [method@GLib.Node.unlink] or [method@GLib.Node.destroy]. + +## Scalable Lists + +The [struct@GLib.Sequence] data structure has the API of a list, but is implemented internally with +a balanced binary tree. This means that most of the operations (access, search, insertion, deletion, +...) on `GSequence` are O(log(n)) in average and O(n) in worst case for time complexity. But, note that +maintaining a balanced sorted list of n elements is done in time O(n log(n)). The data contained +in each element can be either integer values, by using of the +[Type Conversion Macros](conversion-macros.md), or simply pointers to any type of data. + +A `GSequence` is accessed through "iterators", represented by a [struct@GLib.SequenceIter]. 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. + +Some methods on `GSequence` operate on ranges of items. For example [func@GLib.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. + +The function [func@GLib.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. + +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 [func@GLib.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 [method@GLib.Sequence.insert_sorted] or [method@GLib.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 +[method@GLib.Sequence.sort] or [method@GLib.Sequence.sort_iter] after doing unsorted insertions. diff --git a/glib/gsequence.c b/glib/gsequence.c index ead827d46..06f1cbe91 100644 --- a/glib/gsequence.c +++ b/glib/gsequence.c @@ -25,54 +25,6 @@ #include "gmem.h" #include "gtestutils.h" #include "gslice.h" -/** - * SECTION:sequence - * @title: Sequences - * @short_description: scalable lists - * - * The #GSequence data structure has the API of a list, but is - * implemented internally with a balanced binary tree. This means that - * most of the operations (access, search, insertion, deletion, ...) on - * #GSequence are O(log(n)) in average and O(n) in worst case for time - * complexity. But, note that maintaining a balanced sorted list of n - * elements is done 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. - * - * 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. - * - * 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. - * - * 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. - * - * 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. - */ /** * GSequenceIter: