From ed1bc3228bfd2c134e40a8e042e7de657aee0316 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 24 Sep 2023 22:09:02 -0400 Subject: [PATCH] docs: Move list SECTIONs Move the content to the data-structures.md file. Helps: #3037 --- docs/reference/glib/data-structures.md | 113 +++++++++++++++++++++++++ glib/glist.c | 84 ------------------ glib/gslist.c | 51 ----------- 3 files changed, 113 insertions(+), 135 deletions(-) diff --git a/docs/reference/glib/data-structures.md b/docs/reference/glib/data-structures.md index adfdd6d0e..fc008ba94 100644 --- a/docs/reference/glib/data-structures.md +++ b/docs/reference/glib/data-structures.md @@ -2,6 +2,7 @@ Title: Data Structures SPDX-License-Identifier: LGPL-2.1-or-later SPDX-FileCopyrightText: 2010 Allison Lortie SPDX-FileCopyrightText: 2011 Collabora, Ltd. +SPDX-FileCopyrightText: 2012 Olivier Sessink SPDX-FileCopyrightText: 2014 Matthias Clasen SPDX-FileCopyrightText: 2019 Emmanuel Fleury SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC @@ -149,3 +150,115 @@ g_byte_array_free (array, TRUE); See [struct@GLib.Bytes] if you are interested in an immutable object representing a sequence of bytes. + +## Singly-linked Lists + +The [struct@GLib.SList] structure and its associated functions provide a standard +singly-linked list data structure. The benefit of this data structure is to provide +insertion/deletion operations in O(1) complexity where access/search operations are +in O(n). The benefit of `GSList` over [struct@GLib.List] (doubly-linked list) is that +they are lighter in space as they only need to retain one pointer but it double the +cost of the worst case access/search operations. + +Each element in the list contains a piece of data, together with a pointer which links +to the next element in the list. Using this pointer it is possible to move through the +list in one direction only (unlike the [doubly-linked lists](#doubly-linked-lists), +which allow movement in both directions). + +The data contained in each element can be either integer values, by +using one of the [Type Conversion Macros](conversion-macros.html), +or simply pointers to any type of data. + +Note that most of the #GSList functions expect to be passed a pointer to the first element +in the list. The functions which insert elements return the new start of the list, which +may have changed. + +There is no function to create a `GSList`. `NULL` is considered to be the empty list so you +simply set a `GSList*` to `NULL`. + +To add elements, use [func@GLib.SList.append], [func@GLib.SList.prepend], +[func@GLib.SList.insert] and [func@GLib.SList.insert_sorted]. + +To remove elements, use [func@GLib.SList.remove]. + +To find elements in the list use [func@GLib.SList.last], [func@GLib.slist_next], +[func@GLib.SList.nth], [func@GLib.SList.nth_data], [func@GLib.SList.find] and +[func@GLib.SList.find_custom]. + +To find the index of an element use [func@GLib.SList.position] and [func@GLib.SList.index]. + +To call a function for each element in the list use [func@GLib.SList.foreach]. + +To free the entire list, use [func@GLib.SList.free]. + +## Doubly-linked Lists + +The [struct@GLib.List] structure and its associated functions provide a standard +doubly-linked list data structure. The benefit of this data-structure is to provide +insertion/deletion operations in O(1) complexity where access/search operations are in O(n). +The benefit of `GList` over [struct@GLib.SList] (singly-linked list) is that the worst case +on access/search operations is divided by two which comes at a cost in space as we need +to retain two pointers in place of one. + +Each element in the list contains a piece of data, together with pointers which link to the +previous and next elements in the list. Using these pointers it is possible to move through +the list in both directions (unlike the singly-linked [struct@GLib.SList], +which only allows movement through the list in the forward direction). + +The doubly-linked list does not keep track of the number of items and does not keep track of +both the start and end of the list. If you want fast access to both the start and the end of +the list, and/or the number of items in the list, use a [struct@GLib.Queue] instead. + +The data contained in each element can be either integer values, by using one of the +[Type Conversion Macros](conversion-macros.html), or simply pointers to any type of data. + +Note that most of the `GList` functions expect to be passed a pointer to the first element in the list. +The functions which insert elements return the new start of the list, which may have changed. + +There is no function to create a `GList`. `NULL` is considered to be a valid, empty list so you simply +set a `GList*` to `NULL` to initialize it. + +To add elements, use [func@GLib.List.append], [func@GLib.List.prepend], +[func@GLib.List.insert] and [func@GLib.List.insert_sorted]. + +To visit all elements in the list, use a loop over the list: + +```c +GList *l; +for (l = list; l != NULL; l = l->next) + { + // do something with l->data + } +``` + +To call a function for each element in the list, use [func@GLib.List.foreach]. + +To loop over the list and modify it (e.g. remove a certain element) a while loop is more appropriate, +for example: + +```c +GList *l = list; +while (l != NULL) + { + GList *next = l->next; + if (should_be_removed (l)) + { + // possibly free l->data + list = g_list_delete_link (list, l); + } + l = next; + } +``` + +To remove elements, use [func@GLib.List.remove]. + +To navigate in a list, use [func@GLib.List.first], [func@GLib.List.last], +[func@GLib.list_next], [func@GLib.list_previous]. + +To find elements in the list use [func@GLib.List.nth], [func@GLib.List.nth_data], +[func@GLib.List.find] and [func@GLib.List.find_custom]. + +To find the index of an element use [func@GLib.List.position] and [func@GLib.List.index]. + +To free the entire list, use [func@GLib.List.free] or [func@GLib.List.free_full]. + diff --git a/glib/glist.c b/glib/glist.c index 754a3ec52..fc826dbd0 100644 --- a/glib/glist.c +++ b/glib/glist.c @@ -36,90 +36,6 @@ #include "gtestutils.h" -/** - * SECTION:linked_lists_double - * @title: Doubly-Linked Lists - * @short_description: linked lists that can be iterated over in both directions - * - * The #GList structure and its associated functions provide a standard - * doubly-linked list data structure. The benefit of this data-structure - * is to provide insertion/deletion operations in O(1) complexity where - * access/search operations are in O(n). The benefit of #GList over - * #GSList (singly linked list) is that the worst case on access/search - * operations is divided by two which comes at a cost in space as we need - * to retain two pointers in place of one. - * - * Each element in the list contains a piece of data, together with - * pointers which link to the previous and next elements in the list. - * Using these pointers it is possible to move through the list in both - * directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], - * which only allows movement through the list in the forward direction). - * - * The double linked list does not keep track of the number of items - * and does not keep track of both the start and end of the list. If - * you want fast access to both the start and the end of the list, - * and/or the number of items in the list, use a - * [GQueue][glib-Double-ended-Queues] instead. - * - * The data contained in each element can be either integer values, by - * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], - * or simply pointers to any type of data. - * - * List elements are allocated from the [slice allocator][glib-Memory-Slices], - * which is more efficient than allocating elements individually. - * - * Note that most of the #GList functions expect to be passed a pointer - * to the first element in the list. The functions which insert - * elements return the new start of the list, which may have changed. - * - * There is no function to create a #GList. %NULL is considered to be - * a valid, empty list so you simply set a #GList* to %NULL to initialize - * it. - * - * To add elements, use g_list_append(), g_list_prepend(), - * g_list_insert() and g_list_insert_sorted(). - * - * To visit all elements in the list, use a loop over the list: - * |[ - * GList *l; - * for (l = list; l != NULL; l = l->next) - * { - * // do something with l->data - * } - * ]| - * - * To call a function for each element in the list, use g_list_foreach(). - * - * To loop over the list and modify it (e.g. remove a certain element) - * a while loop is more appropriate, for example: - * |[ - * GList *l = list; - * while (l != NULL) - * { - * GList *next = l->next; - * if (should_be_removed (l)) - * { - * // possibly free l->data - * list = g_list_delete_link (list, l); - * } - * l = next; - * } - * ]| - * - * To remove elements, use g_list_remove(). - * - * To navigate in a list, use g_list_first(), g_list_last(), - * g_list_next(), g_list_previous(). - * - * To find elements in the list use g_list_nth(), g_list_nth_data(), - * g_list_find() and g_list_find_custom(). - * - * To find the index of an element use g_list_position() and - * g_list_index(). - * - * To free the entire list, use g_list_free() or g_list_free_full(). - */ - /** * GList: * @data: holds the element's data, which can be a pointer to any kind diff --git a/glib/gslist.c b/glib/gslist.c index 7d4051c24..9520662bd 100644 --- a/glib/gslist.c +++ b/glib/gslist.c @@ -35,57 +35,6 @@ #include "gtestutils.h" #include "gslice.h" -/** - * SECTION:linked_lists_single - * @title: Singly-Linked Lists - * @short_description: linked lists that can be iterated in one direction - * - * The #GSList structure and its associated functions provide a - * standard singly-linked list data structure. The benefit of this - * data-structure is to provide insertion/deletion operations in O(1) - * complexity where access/search operations are in O(n). The benefit - * of #GSList over #GList (doubly linked list) is that they are lighter - * in space as they only need to retain one pointer but it double the - * cost of the worst case access/search operations. - * - * Each element in the list contains a piece of data, together with a - * pointer which links to the next element in the list. Using this - * pointer it is possible to move through the list in one direction - * only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], - * which allow movement in both directions). - * - * The data contained in each element can be either integer values, by - * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], - * or simply pointers to any type of data. - * - * List elements are allocated from the [slice allocator][glib-Memory-Slices], - * which is more efficient than allocating elements individually. - * - * Note that most of the #GSList functions expect to be passed a - * pointer to the first element in the list. The functions which insert - * elements return the new start of the list, which may have changed. - * - * There is no function to create a #GSList. %NULL is considered to be - * the empty list so you simply set a #GSList* to %NULL. - * - * To add elements, use g_slist_append(), g_slist_prepend(), - * g_slist_insert() and g_slist_insert_sorted(). - * - * To remove elements, use g_slist_remove(). - * - * To find elements in the list use g_slist_last(), g_slist_next(), - * g_slist_nth(), g_slist_nth_data(), g_slist_find() and - * g_slist_find_custom(). - * - * To find the index of an element use g_slist_position() and - * g_slist_index(). - * - * To call a function for each element in the list use - * g_slist_foreach(). - * - * To free the entire list, use g_slist_free(). - **/ - /** * GSList: * @data: holds the element's data, which can be a pointer to any kind