docs: Move the array SECTIONs

Move the content to the new data-structures.md file.

Helps: #3037

docs/reference/glib/data-structures.md

@@ -0,0 +1,151 @@
+Title: Data Structures
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 Allison Lortie
+SPDX-FileCopyrightText: 2011 Collabora, Ltd.
+SPDX-FileCopyrightText: 2014 Matthias Clasen
+SPDX-FileCopyrightText: 2019 Emmanuel Fleury
+SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC
+
+# Data Structures
+
+GLib includes a number of basic data sructures, such as linked lists, hash tables,
+arrays, queues, etc.
+
+## Arrays
+
+GLib arrays ([struct@GLib.Array]) are similar to standard C arrays, except that they grow
+automatically as elements are added.
+
+Array elements can be of any size (though all elements of one array are the same size),
+and the array can be automatically cleared to '0's and zero-terminated.
+
+To create a new array use [func@GLib.Array.new].
+
+To add elements to an array with a cost of O(n) at worst, use
+[func@GLib.array_append_val],
+[func@GLib.Array.append_vals],
+[func@GLib.array_prepend_val],
+[func@GLib.Array.prepend_vals],
+[func@GLib.array_insert_val] and
+[func@GLib.Array.insert_vals].
+
+To access an element of an array in O(1) (to read it or to write it),
+use [func@GLib.array_index].
+
+To set the size of an array, use [func@GLib.Array.set_size].
+
+To free an array, use [func@GLib.Array.unref] or [func@GLib.Array.free].
+
+All the sort functions are internally calling a quick-sort (or similar)
+function with an average cost of O(n log(n)) and a worst case cost of O(n^2).
+
+Here is an example that stores integers in a [struct@GLib.Array]:
+
+```c
+GArray *array;
+int i;
+
+// We create a new array to store int values.
+// We don't want it zero-terminated or cleared to 0's.
+array = g_array_new (FALSE, FALSE, sizeof (int));
+
+for (i = 0; i < 10000; i++)
+  {
+    g_array_append_val (array, i);
+  }
+
+for (i = 0; i < 10000; i++)
+  {
+    if (g_array_index (array, int, i) != i)
+      g_print ("ERROR: got %d instead of %d\n",
+               g_array_index (array, int, i), i);
+  }
+
+g_array_free (array, TRUE);
+```
+
+## Pointer Arrays
+
+Pointer Arrays ([struct@GLib.PtrArray]) are similar to Arrays but are used
+only for storing pointers.
+
+If you remove elements from the array, elements at the end of the
+array are moved into the space previously occupied by the removed
+element. This means that you should not rely on the index of particular
+elements remaining the same. You should also be careful when deleting
+elements while iterating over the array.
+
+To create a pointer array, use [func@GLib.PtrArray.new].
+
+To add elements to a pointer array, use [func@GLib.PtrArray.add].
+
+To remove elements from a pointer array, use
+[func@GLib.PtrArray.remove],
+[func@GLib.PtrArray.remove_index] or
+[func@GLib.PtrArray.remove_index_fast].
+
+To access an element of a pointer array, use [func@GLib.ptr_array_index].
+
+To set the size of a pointer array, use [func@GLib.PtrArray.set_size].
+
+To free a pointer array, use [func@GLib.PtrArray.unref] or [func@GLib.PtrArray.free].
+
+An example using a [struct@GLib.PtrArray]:
+
+```c
+GPtrArray *array;
+char *string1 = "one";
+char *string2 = "two";
+char *string3 = "three";
+
+array = g_ptr_array_new ();
+g_ptr_array_add (array, (gpointer) string1);
+g_ptr_array_add (array, (gpointer) string2);
+g_ptr_array_add (array, (gpointer) string3);
+
+if (g_ptr_array_index (array, 0) != (gpointer) string1)
+  g_print ("ERROR: got %p instead of %p\n",
+           g_ptr_array_index (array, 0), string1);
+
+g_ptr_array_free (array, TRUE);
+```
+
+## Byte Arrays
+
+[struct@GLib.ByteArray] is a mutable array of bytes based on [struct@GLib.Array],
+to provide arrays of bytes which grow automatically as elements are added.
+
+To create a new `GByteArray` use [func@GLib.ByteArray.new].
+
+To add elements to a `GByteArray`, use
+[func@GLib.ByteArray.append] and [func@GLib.ByteArray.prepend].
+
+To set the size of a `GByteArray`, use [func@GLib.ByteArray.set_size].
+
+To free a `GByteArray`, use [func@GLib.ByteArray.unref] or [func@GLib.ByteArray.free].
+
+An example for using a `GByteArray`:
+
+```c
+GByteArray *array;
+int i;
+
+array = g_byte_array_new ();
+for (i = 0; i < 10000; i++)
+  {
+    g_byte_array_append (array, (guint8*) "abcd", 4);
+  }
+
+for (i = 0; i < 10000; i++)
+  {
+    g_assert (array->data[4*i] == 'a');
+    g_assert (array->data[4*i+1] == 'b');
+    g_assert (array->data[4*i+2] == 'c');
+    g_assert (array->data[4*i+3] == 'd');
+  }
+
+g_byte_array_free (array, TRUE);
+```
+
+See [struct@GLib.Bytes] if you are interested in an immutable object representing a
+sequence of bytes.

docs/reference/glib/glib.toml.in

@@ -64,6 +64,7 @@ content_files = [
   "threads.md",
   "markup.md",
   "goption.md",
+  "data-structures.md",
 ]
 content_images = [
   "file-name-encodings.png",

docs/reference/glib/meson.build

@@ -162,6 +162,7 @@ expand_content_files = [
   'threads.md',
   'markup.md',
   'goption.md',
+  'data-structures.md',
 ]
 
 glib_gir = meson.current_source_dir() / 'GLib-2.0.gir'

glib/garray.c

@@ -47,53 +47,6 @@
 #include "grefcount.h"
 #include "gutilsprivate.h"
 
-/**
- * SECTION:arrays
- * @title: Arrays
- * @short_description: arrays of arbitrary elements which grow
- *     automatically as elements are added
- *
- * Arrays are similar to standard C arrays, except that they grow
- * automatically as elements are added.
- *
- * Array elements can be of any size (though all elements of one array
- * are the same size), and the array can be automatically cleared to
- * '0's and zero-terminated.
- *
- * To create a new array use g_array_new().
- *
- * To add elements to an array with a cost of O(n) at worst, use
- * g_array_append_val(), g_array_append_vals(), g_array_prepend_val(),
- * g_array_prepend_vals(), g_array_insert_val() and g_array_insert_vals().
- *
- * To access an element of an array in O(1) (to read it or to write it),
- * use g_array_index().
- *
- * To set the size of an array, use g_array_set_size().
- *
- * To free an array, use g_array_unref() or g_array_free().
- *
- * All the sort functions are internally calling a quick-sort (or similar)
- * function with an average cost of O(n log(n)) and a worst case
- * cost of O(n^2).
- *
- * Here is an example that stores integers in a #GArray:
- * |[<!-- language="C" -->
- *   GArray *garray;
- *   gint i;
- *   // We create a new array to store gint values.
- *   // We don't want it zero-terminated or cleared to 0's.
- *   garray = g_array_new (FALSE, FALSE, sizeof (gint));
- *   for (i = 0; i < 10000; i++)
- *     g_array_append_val (garray, i);
- *   for (i = 0; i < 10000; i++)
- *     if (g_array_index (garray, gint, i) != i)
- *       g_print ("ERROR: got %d instead of %d\n",
- *                g_array_index (garray, gint, i), i);
- *   g_array_free (garray, TRUE);
- * ]|
- */
-
 #define MIN_ARRAY_SIZE  16
 
 typedef struct _GRealArray  GRealArray;
@@ -1126,54 +1079,6 @@ g_array_maybe_expand (GRealArray *array,
     }
 }
 
-/**
- * SECTION:arrays_pointer
- * @title: Pointer Arrays
- * @short_description: arrays of pointers to any type of data, which
- *     grow automatically as new elements are added
- *
- * Pointer Arrays are similar to Arrays but are used only for storing
- * pointers.
- *
- * If you remove elements from the array, elements at the end of the
- * array are moved into the space previously occupied by the removed
- * element. This means that you should not rely on the index of particular
- * elements remaining the same. You should also be careful when deleting
- * elements while iterating over the array.
- *
- * To create a pointer array, use g_ptr_array_new().
- *
- * To add elements to a pointer array, use g_ptr_array_add().
- *
- * To remove elements from a pointer array, use g_ptr_array_remove(),
- * g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
- *
- * To access an element of a pointer array, use g_ptr_array_index().
- *
- * To set the size of a pointer array, use g_ptr_array_set_size().
- *
- * To free a pointer array, use g_ptr_array_free().
- *
- * An example using a #GPtrArray:
- * |[<!-- language="C" -->
- *   GPtrArray *array;
- *   gchar *string1 = "one";
- *   gchar *string2 = "two";
- *   gchar *string3 = "three";
- *
- *   array = g_ptr_array_new ();
- *   g_ptr_array_add (array, (gpointer) string1);
- *   g_ptr_array_add (array, (gpointer) string2);
- *   g_ptr_array_add (array, (gpointer) string3);
- *
- *   if (g_ptr_array_index (array, 0) != (gpointer) string1)
- *     g_print ("ERROR: got %p instead of %p\n",
- *              g_ptr_array_index (array, 0), string1);
- *
- *   g_ptr_array_free (array, TRUE);
- * ]|
- */
-
 typedef struct _GRealPtrArray  GRealPtrArray;
 
 /**
@@ -2765,45 +2670,6 @@ g_ptr_array_find_with_equal_func (GPtrArray     *haystack,
   return FALSE;
 }
 
-/**
- * SECTION:arrays_byte
- * @title: Byte Arrays
- * @short_description: arrays of bytes
- *
- * #GByteArray is a mutable array of bytes based on #GArray, to provide arrays
- * of bytes which grow automatically as elements are added.
- *
- * To create a new #GByteArray use g_byte_array_new(). To add elements to a
- * #GByteArray, use g_byte_array_append(), and g_byte_array_prepend().
- *
- * To set the size of a #GByteArray, use g_byte_array_set_size().
- *
- * To free a #GByteArray, use g_byte_array_free().
- *
- * An example for using a #GByteArray:
- * |[<!-- language="C" -->
- *   GByteArray *gbarray;
- *   gint i;
- *
- *   gbarray = g_byte_array_new ();
- *   for (i = 0; i < 10000; i++)
- *     g_byte_array_append (gbarray, (guint8*) "abcd", 4);
- *
- *   for (i = 0; i < 10000; i++)
- *     {
- *       g_assert (gbarray->data[4*i] == 'a');
- *       g_assert (gbarray->data[4*i+1] == 'b');
- *       g_assert (gbarray->data[4*i+2] == 'c');
- *       g_assert (gbarray->data[4*i+3] == 'd');
- *     }
- *
- *   g_byte_array_free (gbarray, TRUE);
- * ]|
- *
- * See #GBytes if you are interested in an immutable object representing a
- * sequence of bytes.
- */
-
 /**
  * GByteArray:
  * @data: a pointer to the element data. The data may be moved as