mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-04-14 11:38:05 +02:00
555b46b039
2005-08-30 Matthias Clasen <mclasen@redhat.com> * glib/tmpl/arrays.sgml: * glib/tmpl/arrays_pointer.sgml: * glib/tmpl/arrays_byte.sgml: Enhance sort() documentation. (#314839, Behdad Esfahbod)
310 lines
8.3 KiB
Plaintext
310 lines
8.3 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Arrays
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
arrays of arbitrary elements which grow automatically as elements are added.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
Arrays are similar to standard C arrays, except that they grow automatically
|
|
as elements are added.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
To create a new array use g_array_new().
|
|
</para>
|
|
<para>
|
|
To add elements to an array, use g_array_append_val(), g_array_append_vals(),
|
|
g_array_prepend_val(), and g_array_prepend_vals().
|
|
</para>
|
|
<para>
|
|
To access an element of an array, use g_array_index().
|
|
</para>
|
|
<para>
|
|
To set the size of an array, use g_array_set_size().
|
|
</para>
|
|
<para>
|
|
To free an array, use g_array_free().
|
|
</para>
|
|
<example>
|
|
<title>Using a <structname>GArray</structname> to store <type>gint</type> values</title>
|
|
<programlisting>
|
|
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);
|
|
</programlisting></example>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### STRUCT GArray ##### -->
|
|
<para>
|
|
Contains the public fields of an <link linkend="glib-arrays">Array</link>.
|
|
</para>
|
|
|
|
@data: a pointer to the element data. The data may be moved as elements are
|
|
added to the #GArray.
|
|
@len: the number of elements in the #GArray.
|
|
|
|
<!-- ##### FUNCTION g_array_new ##### -->
|
|
<para>
|
|
Creates a new #GArray.
|
|
</para>
|
|
|
|
@zero_terminated: %TRUE if the array should have an extra element at the end
|
|
which is set to 0.
|
|
@clear_: %TRUE if #GArray elements should be automatically cleared to 0
|
|
when they are allocated.
|
|
@element_size: the size of each element in bytes.
|
|
@Returns: the new #GArray.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_sized_new ##### -->
|
|
<para>
|
|
Creates a new #GArray with @reserved_size elements
|
|
preallocated. This avoids frequent reallocation, if you are going to
|
|
add many elements to the array. Note however that the size of the
|
|
array is still 0.
|
|
</para>
|
|
|
|
@zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared.
|
|
@clear_: %TRUE if all bits in the array should be cleared to 0 on allocation.
|
|
@element_size: size of each element in the array.
|
|
@reserved_size: number of elements preallocated.
|
|
@Returns: the new #GArray.
|
|
|
|
|
|
<!-- ##### MACRO g_array_append_val ##### -->
|
|
<para>
|
|
Adds the value on to the end of the array.
|
|
The array will grow in size automatically if necessary.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
g_array_append_val() is a macro which uses a reference to the value
|
|
parameter @v. This means that you cannot use it with literal values
|
|
such as "27". You must use variables.
|
|
</para>
|
|
</note>
|
|
|
|
@a: a #GArray.
|
|
@v: the value to append to the #GArray.
|
|
@Returns: the #GArray.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_append_vals ##### -->
|
|
<para>
|
|
Adds @len elements onto the end of the array.
|
|
</para>
|
|
|
|
@array: a #GArray.
|
|
@data: a pointer to the elements to append to the end of the array.
|
|
@len: the number of elements to append.
|
|
@Returns: the #GArray.
|
|
|
|
|
|
<!-- ##### MACRO g_array_prepend_val ##### -->
|
|
<para>
|
|
Adds the value on to the start of the array.
|
|
The array will grow in size automatically if necessary.
|
|
</para>
|
|
<para>
|
|
This operation is slower than g_array_append_val() since the existing elements
|
|
in the array have to be moved to make space for the new element.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
g_array_prepend_val() is a macro which uses a reference to the value
|
|
parameter @v. This means that you cannot use it with literal values
|
|
such as "27". You must use variables.
|
|
</para>
|
|
</note>
|
|
|
|
@a: a #GArray.
|
|
@v: the value to prepend to the #GArray.
|
|
@Returns: the #GArray.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_prepend_vals ##### -->
|
|
<para>
|
|
Adds @len elements onto the start of the array.
|
|
</para>
|
|
<para>
|
|
This operation is slower than g_array_append_vals() since the existing elements
|
|
in the array have to be moved to make space for the new elements.
|
|
</para>
|
|
|
|
@array: a #GArray.
|
|
@data: a pointer to the elements to prepend to the start of the array.
|
|
@len: the number of elements to prepend.
|
|
@Returns: the #GArray.
|
|
|
|
|
|
<!-- ##### MACRO g_array_insert_val ##### -->
|
|
<para>
|
|
Inserts an element into an array at the given index.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
g_array_insert_val() is a macro which uses a reference to the value
|
|
parameter @v. This means that you cannot use it with literal values
|
|
such as "27". You must use variables.
|
|
</para>
|
|
</note>
|
|
|
|
@a: a #GArray.
|
|
@i: the index to place the element at.
|
|
@v: the value to insert into the array.
|
|
@Returns: the #GArray.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_insert_vals ##### -->
|
|
<para>
|
|
Inserts @len elements into a #GArray at the given index.
|
|
</para>
|
|
|
|
@array: a #GArray.
|
|
@index_: the index to place the elements at.
|
|
@data: a pointer to the elements to insert.
|
|
@len: the number of elements to insert.
|
|
@Returns: the #GArray.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_remove_index ##### -->
|
|
<para>
|
|
Removes the element at the given index from a #GArray.
|
|
The following elements are moved down one place.
|
|
</para>
|
|
|
|
@array: a #GArray.
|
|
@index_: the index of the element to remove.
|
|
@Returns: the #GArray.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_remove_index_fast ##### -->
|
|
<para>
|
|
Removes the element at the given index from a #GArray.
|
|
The last element in the array is used to fill in the space, so this function
|
|
does not preserve the order of the #GArray. But it is faster than
|
|
g_array_remove_index().
|
|
</para>
|
|
|
|
@array: a @GArray.
|
|
@index_: the index of the element to remove.
|
|
@Returns: the #GArray.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_remove_range ##### -->
|
|
<para>
|
|
Removes the given number of elements starting at the given index from a
|
|
#GArray. The following elements are moved to close the gap.
|
|
</para>
|
|
|
|
@array: a @GArray.
|
|
@index_: the index of the first element to remove.
|
|
@length: the number of elements to remove.
|
|
@Returns: the #GArray.
|
|
@Since: 2.4
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_sort ##### -->
|
|
<para>
|
|
Sorts a #GArray using @compare_func which should be a qsort()-style comparison
|
|
function (returns less than zero for first arg is less than second arg,
|
|
zero for equal, greater zero if first arg is greater than second arg).
|
|
</para>
|
|
<para>
|
|
If two array elements compare equal, their order in the sorted array is
|
|
undefined.
|
|
</para>
|
|
|
|
@array: a #GArray.
|
|
@compare_func: comparison function.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_sort_with_data ##### -->
|
|
<para>
|
|
Like g_array_sort(), but the comparison function receives an extra user data
|
|
argument.
|
|
</para>
|
|
|
|
@array: a #GArray.
|
|
@compare_func: comparison function.
|
|
@user_data: data to pass to @compare_func.
|
|
|
|
|
|
<!-- ##### MACRO g_array_index ##### -->
|
|
<para>
|
|
Returns the element of a #GArray at the given index.
|
|
The return value is cast to the given type.
|
|
|
|
<example>
|
|
<title>Getting a pointer to an element in a <structname>GArray</structname></title>
|
|
<programlisting>
|
|
EDayViewEvent *event;
|
|
|
|
/* This gets a pointer to the 3rd element in the array of EDayViewEvent
|
|
structs. */
|
|
event = &g_array_index (events, EDayViewEvent, 3);
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
@a: a #GArray.
|
|
@t: the type of the elements.
|
|
@i: the index of the element to return.
|
|
@Returns: the element of the #GArray at the index given by @i.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_set_size ##### -->
|
|
<para>
|
|
Sets the size of the array, expanding it if necessary.
|
|
If the array was created with @clear_ set to %TRUE, the new elements are set to 0.
|
|
</para>
|
|
|
|
@array: a #GArray.
|
|
@length: the new size of the #GArray.
|
|
@Returns: the #GArray.
|
|
|
|
|
|
<!-- ##### FUNCTION g_array_free ##### -->
|
|
<para>
|
|
Frees the memory allocated for the #GArray.
|
|
If @free_segment is %TRUE it frees the memory block holding the elements
|
|
as well. Pass %FALSE if you want to free the #GArray wrapper but preserve
|
|
the underlying array for use elsewhere.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If array elements contain dynamically-allocated memory, they should be freed
|
|
first.
|
|
</para>
|
|
</note>
|
|
|
|
@array: a #GArray.
|
|
@free_segment: if %TRUE the actual element data is freed as well.
|
|
@Returns: the element data if @free_segment is %FALSE, otherwise %NULL
|
|
|
|
|