luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-26 22:16:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch '1154-array-docs' into 'master'

Browse Source 
garray: Clarify documentation in a few places

Closes #1154

See merge request GNOME/glib!1404
This commit is contained in:
Sebastian Dröge 2020-03-17 13:50:06 +00:00
commit 21a6f044b3
1 changed files with 26 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
glib/garray.c
View File

@ -59,14 +59,15 @@
* To create a new array use g_array_new(). * To create a new array use g_array_new().
* *
* To add elements to an array, use g_array_append_val(), * To add elements to an array, use g_array_append_val(),
* g_array_append_vals(), g_array_prepend_val(), and * g_array_append_vals(), g_array_prepend_val(), g_array_prepend_vals(),
* g_array_prepend_vals(). * g_array_insert_val() and g_array_insert_vals().
* *
* To access an element of an array, use g_array_index(). * To access an element of an array (to read it or write it),
* use g_array_index().
* *
* To set the size of an array, use g_array_set_size(). * To set the size of an array, use g_array_set_size().
* *
* To free an array, use g_array_free(). * To free an array, use g_array_unref() or g_array_free().
* *
* Here is an example that stores integers in a #GArray: * Here is an example that stores integers in a #GArray:
* |[<!-- language="C" --> * |[<!-- language="C" -->
@ -117,14 +118,29 @@ struct _GRealArray
* @i: the index of the element to return * @i: the index of the element to return
* *
* Returns the element of a #GArray at the given index. The return * Returns the element of a #GArray at the given index. The return
* value is cast to the given type. * value is cast to the given type. This is the main way to read or write an
* element in a #GArray.
* *
* This example gets a pointer to an element in a #GArray: * Writing an element is typically done by reference, as in the following
* example. This example gets a pointer to an element in a #GArray, and then
* writes to a field in it:
* |[<!-- language="C" --> * |[<!-- language="C" -->
* EDayViewEvent *event; * EDayViewEvent *event;
* // This gets a pointer to the 4th element in the array of * // This gets a pointer to the 4th element in the array of
* // EDayViewEvent structs. * // EDayViewEvent structs.
* event = &g_array_index (events, EDayViewEvent, 3); * event = &g_array_index (events, EDayViewEvent, 3);
* event->start_time = g_get_current_time ();
* ]|
*
* This example reads from and writes to an array of integers:
* |[<!-- language="C" -->
* g_autoptr(GArray) int_array = g_array_new (FALSE, FALSE, sizeof (guint));
* for (guint i = 0; i < 10; i++)
* g_array_append_val (int_array, i);
*
* guint *my_int = &g_array_index (int_array, guint, 1);
* g_print ("Int at index 1 is %u; decrementing it\n", *my_int);
* *my_int = *my_int - 1;
* ]| * ]|
* *
* Returns: the element of the #GArray at the index given by @i * Returns: the element of the #GArray at the index given by @i
@ -563,6 +579,10 @@ g_array_prepend_vals (GArray *farray,
* will be initialised to zero if the array was configured to clear elements; * will be initialised to zero if the array was configured to clear elements;
* otherwise their values will be undefined. * otherwise their values will be undefined.
* *
* If @index_ is less than the array’s current length, new entries will be
* inserted into the array, and the existing entries above @index_ will be moved
* upwards.
*
* @data may be %NULL if (and only if) @len is zero. If @len is zero, this * @data may be %NULL if (and only if) @len is zero. If @len is zero, this
* function is a no-op. * function is a no-op.
* *