luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-07-23 10:27:51 +02:00
Code Issues Packages Projects Releases Wiki Activity

G{Byte,Ptr,}Array: move docs from tmpl to .c

Browse Source
This commit is contained in:
Ryan Lortie
2010-01-31 14:30:08 -05:00
parent 501a2906d3
commit 3443f47ddf
5 changed files with 632 additions and 858 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/reference/glib/tmpl/.gitignore vendored
View File

@@ -1,4 +1,7 @@
allocators.sgml
arrays.sgml
arrays_byte.sgml
arrays_pointer.sgml
base64.sgml
caches.sgml
checksum.sgml

339
docs/reference/glib/tmpl/arrays.sgml
View File

@@ -1,339 +0,0 @@
<!-- ##### 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 &lt; 10000; i++)
g_array_append_val (garray, i);
for (i = 0; i &lt; 10000; i++)
if (g_array_index (garray, gint, i) != i)
g_print ("ERROR: got &percnt;d instead of &percnt;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 not including the possible terminating zero element.
<!-- ##### FUNCTION g_array_new ##### -->
<para>
Creates a new #GArray with a reference count of 1.
</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 and a reference count of 1. 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.
<!-- ##### FUNCTION g_array_ref ##### -->
<para>
</para>
@array:
@Returns:
<!-- ##### FUNCTION g_array_unref ##### -->
<para>
</para>
@array:
<!-- ##### FUNCTION g_array_get_element_size ##### -->
<para>
</para>
@array:
@Returns:
<!-- ##### 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 4th element in the array of EDayViewEvent
structs. */
event = &amp;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 and also each element if @array has a @element_free_func set.
Pass %FALSE if you want to free the #GArray wrapper but preserve
the underlying array for use elsewhere. If the reference count of @array
is greater than one, the #GArray wrapper is preserved but the size of
@array will be set to zero.
</para>
<note>
<para>
If array elements contain dynamically-allocated memory, they should be freed
separately.
</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.
The element data should be freed using g_free().

211
docs/reference/glib/tmpl/arrays_byte.sgml
View File

@@ -1,211 +0,0 @@
<!-- ##### SECTION Title ##### -->
Byte Arrays
<!-- ##### SECTION Short_Description ##### -->
arrays of bytes, which grow automatically as elements are added
<!-- ##### SECTION Long_Description ##### -->
<para>
#GByteArray is based on #GArray, to provide arrays of bytes which grow
automatically as elements are added.
</para>
<para>
To create a new #GByteArray use g_byte_array_new().
</para>
<para>
To add elements to a #GByteArray, use g_byte_array_append(), and
g_byte_array_prepend().
</para>
<para>
To set the size of a #GByteArray, use g_byte_array_set_size().
</para>
<para>
To free a #GByteArray, use g_byte_array_free().
</para>
<example>
<title>Using a <structname>GByteArray</structname></title>
<programlisting>
GByteArray *gbarray;
gint i;
gbarray = g_byte_array_new (<!-- -->);
for (i = 0; i &lt; 10000; i++)
g_byte_array_append (gbarray, (guint8*) "abcd", 4);
for (i = 0; i &lt; 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);
</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GByteArray ##### -->
<para>
The <structname>GByteArray</structname> struct allows access to the public fields of a <structname>GByteArray</structname>.
</para>
@data: a pointer to the element data. The data may be moved as elements are
added to the #GByteArray.
@len: the number of elements in the #GByteArray.
<!-- ##### FUNCTION g_byte_array_new ##### -->
<para>
Creates a new #GByteArray with a reference count of 1.
</para>
@Returns: the new #GByteArray.
<!-- ##### FUNCTION g_byte_array_sized_new ##### -->
<para>
Creates a new #GByteArray with @reserved_size bytes preallocated. This
avoids frequent reallocation, if you are going to add many bytes to
the array. Note however that the size of the array is still 0.
</para>
@reserved_size: number of bytes preallocated.
@Returns: the new #GByteArray.
<!-- ##### FUNCTION g_byte_array_ref ##### -->
<para>
</para>
@array:
@Returns:
<!-- ##### FUNCTION g_byte_array_unref ##### -->
<para>
</para>
@array:
<!-- ##### FUNCTION g_byte_array_append ##### -->
<para>
Adds the given bytes to the end of the #GByteArray.
The array will grow in size automatically if necessary.
</para>
@array: a #GByteArray.
@data: the byte data to be added.
@len: the number of bytes to add.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_prepend ##### -->
<para>
Adds the given data to the start of the #GByteArray.
The array will grow in size automatically if necessary.
</para>
@array: a #GByteArray.
@data: the byte data to be added.
@len: the number of bytes to add.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_index ##### -->
<para>
Removes the byte at the given index from a #GByteArray.
The following bytes are moved down one place.
</para>
@array: a #GByteArray.
@index_: the index of the byte to remove.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_index_fast ##### -->
<para>
Removes the byte at the given index from a #GByteArray.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the #GByteArray. But it is faster than
g_byte_array_remove_index().
</para>
@array: a #GByteArray.
@index_: the index of the byte to remove.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_range ##### -->
<para>
Removes the given number of bytes starting at the given index from a
#GByteArray. The following elements are moved to close the gap.
</para>
@array: a @GByteArray.
@index_: the index of the first byte to remove.
@length: the number of bytes to remove.
@Returns: the #GByteArray.
@Since: 2.4
<!-- ##### FUNCTION g_byte_array_sort ##### -->
<para>
Sorts a byte array, 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 than 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 #GByteArray.
@compare_func: comparison function.
<!-- ##### FUNCTION g_byte_array_sort_with_data ##### -->
<para>
Like g_byte_array_sort(), but the comparison function takes an extra user data
argument.
</para>
@array: a #GByteArray.
@compare_func: comparison function.
@user_data: data to pass to @compare_func.
<!-- ##### FUNCTION g_byte_array_set_size ##### -->
<para>
Sets the size of the #GByteArray, expanding it if necessary.
</para>
@array: a #GByteArray.
@length: the new size of the #GByteArray.
@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_free ##### -->
<para>
Frees the memory allocated by the #GByteArray.
If @free_segment is %TRUE it frees the actual byte data. If the reference
count of @array is greater than one, the #GByteArray wrapper is preserved but
the size of @array will be set to zero.
</para>
@array: a #GByteArray.
@free_segment: if %TRUE the actual byte data is freed as well.
@Returns: the element data if @free_segment is %FALSE, otherwise %NULL.
The element data should be freed using g_free().

308
docs/reference/glib/tmpl/arrays_pointer.sgml
View File

@@ -1,308 +0,0 @@
<!-- ##### SECTION Title ##### -->
Pointer Arrays
<!-- ##### SECTION Short_Description ##### -->
arrays of pointers to any type of data, which grow automatically as new
elements are added
<!-- ##### SECTION Long_Description ##### -->
<para>
Pointer Arrays are similar to Arrays but are used only for storing pointers.
</para>
<note>
<para>
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.
</para>
</note>
<para>
To create a pointer array, use g_ptr_array_new().
</para>
<para>
To add elements to a pointer array, use g_ptr_array_add().
</para>
<para>
To remove elements from a pointer array, use g_ptr_array_remove(),
g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
</para>
<para>
To access an element of a pointer array, use g_ptr_array_index().
</para>
<para>
To set the size of a pointer array, use g_ptr_array_set_size().
</para>
<para>
To free a pointer array, use g_ptr_array_free().
</para>
<example>
<title>Using a <structname>GPtrArray</structname></title>
<programlisting>
GPtrArray *gparray;
gchar *string1 = "one", *string2 = "two", *string3 = "three";
gparray = g_ptr_array_new (<!-- -->);
g_ptr_array_add (gparray, (gpointer) string1);
g_ptr_array_add (gparray, (gpointer) string2);
g_ptr_array_add (gparray, (gpointer) string3);
if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
g_print ("ERROR: got &percnt;p instead of &percnt;p\n",
g_ptr_array_index (gparray, 0), string1);
g_ptr_array_free (gparray, TRUE);
</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GPtrArray ##### -->
<para>
Contains the public fields of a pointer array.
</para>
@pdata: points to the array of pointers, which may be moved when the array grows.
@len: number of pointers in the array.
<!-- ##### FUNCTION g_ptr_array_new ##### -->
<para>
Creates a new #GPtrArray with a reference count of 1.
</para>
@Returns: the new #GPtrArray.
<!-- ##### FUNCTION g_ptr_array_sized_new ##### -->
<para>
Creates a new #GPtrArray with @reserved_size pointers
preallocated and a reference count of 1. This avoids frequent reallocation,
if you are going to add many pointers to the array. Note however that the size
of the array is still 0.
</para>
@reserved_size: number of pointers preallocated.
@Returns: the new #GPtrArray.
<!-- ##### FUNCTION g_ptr_array_new_with_free_func ##### -->
<para>
</para>
@element_free_func:
@Returns:
<!-- ##### FUNCTION g_ptr_array_set_free_func ##### -->
<para>
</para>
@array:
@element_free_func:
<!-- ##### FUNCTION g_ptr_array_ref ##### -->
<para>
</para>
@array:
@Returns:
<!-- ##### FUNCTION g_ptr_array_unref ##### -->
<para>
</para>
@array:
<!-- ##### FUNCTION g_ptr_array_add ##### -->
<para>
Adds a pointer to the end of the pointer array.
The array will grow in size automatically if necessary.
</para>
@array: a #GPtrArray.
@data: the pointer to add.
<!-- ##### FUNCTION g_ptr_array_remove ##### -->
<para>
Removes the first occurrence of the given pointer from the pointer array.
The following elements are moved down one place.
If @array has a non-%NULL #GDestroyNotify function it is called for
the removed element.
</para>
<para>
It returns %TRUE if the pointer was removed, or %FALSE if the pointer
was not found.
</para>
@array: a #GPtrArray.
@data: the pointer to remove.
@Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found
in the array.
<!-- ##### FUNCTION g_ptr_array_remove_index ##### -->
<para>
Removes the pointer at the given index from the pointer array.
The following elements are moved down one place.
If @array has a non-%NULL #GDestroyNotify function it is called for
the removed element.
</para>
@array: a #GPtrArray.
@index_: the index of the pointer to remove.
@Returns: the pointer which was removed.
<!-- ##### FUNCTION g_ptr_array_remove_fast ##### -->
<para>
Removes the first occurrence of the given pointer from the pointer array.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the array. But it is faster than
g_ptr_array_remove().
If @array has a non-%NULL #GDestroyNotify function it is called for
the removed element.
</para>
<para>
It returns %TRUE if the pointer was removed, or %FALSE if the pointer
was not found.
</para>
@array: a #GPtrArray.
@data: the pointer to remove.
@Returns: %TRUE if the pointer was found in the array.
<!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
<para>
Removes the pointer at the given index from the pointer array.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the array. But it is faster than
g_ptr_array_remove_index().
If @array has a non-%NULL #GDestroyNotify function it is called for
the removed element.
</para>
@array: a #GPtrArray.
@index_: the index of the pointer to remove.
@Returns: the pointer which was removed.
<!-- ##### FUNCTION g_ptr_array_remove_range ##### -->
<para>
Removes the given number of pointers starting at the given index from a
#GPtrArray. The following elements are moved to close the gap.
If @array has a non-%NULL #GDestroyNotify function it is called for
the removed elements.
</para>
@array: a @GPtrArray.
@index_: the index of the first pointer to remove.
@length: the number of pointers to remove.
@Since: 2.4
<!-- ##### FUNCTION g_ptr_array_sort ##### -->
<para>
Sorts the array, 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 than zero if irst arg is greater than second arg).
</para>
<para>
If two array elements compare equal, their order in the sorted array is
undefined.
</para>
<note><para>
The comparison function for g_ptr_array_sort() doesn't take the pointers
from the array as arguments, it takes pointers to the pointers in the array.
</para></note>
@array: a #GPtrArray.
@compare_func: comparison function.
<!-- ##### FUNCTION g_ptr_array_sort_with_data ##### -->
<para>
Like g_ptr_array_sort(), but the comparison function has an extra user data
argument.
</para>
<note><para>
The comparison function for g_ptr_array_sort_with_data() doesn't take the
pointers from the array as arguments, it takes pointers to the pointers in
the array.
</para></note>
@array: a #GPtrArray.
@compare_func: comparison function.
@user_data: data to pass to @compare_func.
<!-- ##### FUNCTION g_ptr_array_set_size ##### -->
<para>
Sets the size of the array. When making the array larger, newly-added
elements will be set to %NULL. When making it smaller, if @array has a
non-%NULL #GDestroyNotify function then it will be called for the
removed elements.
</para>
@array: a #GPtrArray.
@length: the new length of the pointer array.
<!-- ##### MACRO g_ptr_array_index ##### -->
<para>
Returns the pointer at the given index of the pointer array.
</para>
@array: a #GPtrArray.
@index_: the index of the pointer to return.
@Returns: the pointer at the given index.
<!-- ##### FUNCTION g_ptr_array_free ##### -->
<para>
Frees the memory allocated for the #GPtrArray.
If @free_seg is %TRUE it frees the memory block holding the elements
as well. Pass %FALSE if you want to free the #GPtrArray wrapper but preserve
the underlying array for use elsewhere. If the reference count of @array
is greater than one, the #GPtrArray wrapper is preserved but the size of
@array will be set to zero.
</para>
<note>
<para>
If array contents point to dynamically-allocated memory, they should
be freed separately if @free_seg is %TRUE and no #GDestroyNotify
function has been set for @array.
</para>
</note>
@array: a #GPtrArray.
@free_seg: if %TRUE the actual pointer array is freed as well.
@Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
The pointer array should be freed using g_free().
<!-- ##### FUNCTION g_ptr_array_foreach ##### -->
<para>
</para>
@array:
@func:
@user_data: