luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-11-04 01:58:54 +01: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 allocators.sgml
arrays.sgml
arrays_byte.sgml
arrays_pointer.sgml
base64.sgml base64.sgml
caches.sgml caches.sgml
checksum.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:

629
glib/garray.c
View File

@@ -42,11 +42,64 @@
#include "galias.h" #include "galias.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, use g_array_append_val(),
* g_array_append_vals(), g_array_prepend_val(), and
* g_array_prepend_vals().
*
* To access an element of an array, use g_array_index().
*
* To set the size of an array, use g_array_set_size().
*
* To free an array, use g_array_free().
*
* <example>
* <title>Using a #GArray to store #gint 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>
**/
#define MIN_ARRAY_SIZE 16 #define MIN_ARRAY_SIZE 16
typedef struct _GRealArray GRealArray; typedef struct _GRealArray GRealArray;
/**
* GArray:
* @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.
*
* Contains the public fields of an <link
* linkend="glib-arrays">Array</link>.
**/
struct _GRealArray struct _GRealArray
{ {
guint8 *data; guint8 *data;
@@ -58,6 +111,27 @@ struct _GRealArray
volatile gint ref_count; volatile gint ref_count;
}; };
/**
* g_array_index:
* @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.
*
* 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 #GArray</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>
**/
#define g_array_elt_len(array,i) ((array)->elt_size * (i)) #define g_array_elt_len(array,i) ((array)->elt_size * (i))
#define g_array_elt_pos(array,i) ((array)->data + g_array_elt_len((array),(i))) #define g_array_elt_pos(array,i) ((array)->data + g_array_elt_len((array),(i)))
#define g_array_elt_zero(array, pos, len) \ #define g_array_elt_zero(array, pos, len) \
@@ -71,6 +145,17 @@ static guint g_nearest_pow (gint num) G_GNUC_CONST;
static void g_array_maybe_expand (GRealArray *array, static void g_array_maybe_expand (GRealArray *array,
gint len); gint len);
/**
* g_array_new:
* @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.
*
* Creates a new #GArray with a reference count of 1.
**/
GArray* GArray*
g_array_new (gboolean zero_terminated, g_array_new (gboolean zero_terminated,
gboolean clear, gboolean clear,
@@ -79,6 +164,21 @@ g_array_new (gboolean zero_terminated,
return (GArray*) g_array_sized_new (zero_terminated, clear, elt_size, 0); return (GArray*) g_array_sized_new (zero_terminated, clear, elt_size, 0);
} }
/**
* g_array_sized_new:
* @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.
*
* 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.
**/
GArray* g_array_sized_new (gboolean zero_terminated, GArray* g_array_sized_new (gboolean zero_terminated,
gboolean clear, gboolean clear,
guint elt_size, guint elt_size,
@@ -160,6 +260,24 @@ g_array_get_element_size (GArray *array)
return rarray->elt_size; return rarray->elt_size;
} }
/**
* g_array_free:
* @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().
*
* 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.
*
* <note><para>If array elements contain dynamically-allocated memory,
* they should be freed separately.</para></note>
**/
gchar* gchar*
g_array_free (GArray *farray, g_array_free (GArray *farray,
gboolean free_segment) gboolean free_segment)
@@ -197,6 +315,28 @@ g_array_free (GArray *farray,
return segment; return segment;
} }
/**
* g_array_append_vals:
* @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.
*
* Adds @len elements onto the end of the array.
**/
/**
* g_array_append_val:
* @a: a #GArray.
* @v: the value to append to the #GArray.
* @Returns: the #GArray.
*
* Adds the value on to the end of the array. The array will grow in
* size automatically if necessary.
*
* <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>
**/
GArray* GArray*
g_array_append_vals (GArray *farray, g_array_append_vals (GArray *farray,
gconstpointer data, gconstpointer data,
@@ -216,6 +356,37 @@ g_array_append_vals (GArray *farray,
return farray; return farray;
} }
/**
* g_array_prepend_vals:
* @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.
*
* Adds @len elements onto the start of the array.
*
* 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.
**/
/**
* g_array_prepend_val:
* @a: a #GArray.
* @v: the value to prepend to the #GArray.
* @Returns: the #GArray.
*
* Adds the value on to the start of the array. The array will grow in
* size automatically if necessary.
*
* 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.
*
* <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>
**/
GArray* GArray*
g_array_prepend_vals (GArray *farray, g_array_prepend_vals (GArray *farray,
gconstpointer data, gconstpointer data,
@@ -237,6 +408,29 @@ g_array_prepend_vals (GArray *farray,
return farray; return farray;
} }
/**
* g_array_insert_vals:
* @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.
*
* Inserts @len elements into a #GArray at the given index.
**/
/**
* g_array_insert_val:
* @a: a #GArray.
* @i: the index to place the element at.
* @v: the value to insert into the array.
* @Returns: the #GArray.
*
* Inserts an element into an array at the given index.
*
* <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>
**/
GArray* GArray*
g_array_insert_vals (GArray *farray, g_array_insert_vals (GArray *farray,
guint index_, guint index_,
@@ -260,6 +454,15 @@ g_array_insert_vals (GArray *farray,
return farray; return farray;
} }
/**
* g_array_set_size:
* @array: a #GArray.
* @length: the new size of the #GArray.
* @Returns: the #GArray.
*
* 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.
**/
GArray* GArray*
g_array_set_size (GArray *farray, g_array_set_size (GArray *farray,
guint length) guint length)
@@ -282,6 +485,15 @@ g_array_set_size (GArray *farray,
return farray; return farray;
} }
/**
* g_array_remove_index:
* @array: a #GArray.
* @index_: the index of the element to remove.
* @Returns: the #GArray.
*
* Removes the element at the given index from a #GArray. The following
* elements are moved down one place.
**/
GArray* GArray*
g_array_remove_index (GArray *farray, g_array_remove_index (GArray *farray,
guint index_) guint index_)
@@ -307,6 +519,17 @@ g_array_remove_index (GArray *farray,
return farray; return farray;
} }
/**
* g_array_remove_index_fast:
* @array: a @GArray.
* @index_: the index of the element to remove.
* @Returns: the #GArray.
*
* 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().
**/
GArray* GArray*
g_array_remove_index_fast (GArray *farray, g_array_remove_index_fast (GArray *farray,
guint index_) guint index_)
@@ -332,6 +555,18 @@ g_array_remove_index_fast (GArray *farray,
return farray; return farray;
} }
/**
* g_array_remove_range:
* @array: a @GArray.
* @index_: the index of the first element to remove.
* @length: the number of elements to remove.
* @Returns: the #GArray.
*
* Removes the given number of elements starting at the given index
* from a #GArray. The following elements are moved to close the gap.
*
* Since: 2.4
**/
GArray* GArray*
g_array_remove_range (GArray *farray, g_array_remove_range (GArray *farray,
guint index_, guint index_,
@@ -357,6 +592,19 @@ g_array_remove_range (GArray *farray,
return farray; return farray;
} }
/**
* g_array_sort:
* @array: a #GArray.
* @compare_func: comparison function.
*
* 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).
*
* If two array elements compare equal, their order in the sorted array
* is undefined.
**/
void void
g_array_sort (GArray *farray, g_array_sort (GArray *farray,
GCompareFunc compare_func) GCompareFunc compare_func)
@@ -371,6 +619,15 @@ g_array_sort (GArray *farray,
compare_func); compare_func);
} }
/**
* g_array_sort_with_data:
* @array: a #GArray.
* @compare_func: comparison function.
* @user_data: data to pass to @compare_func.
*
* Like g_array_sort(), but the comparison function receives an extra
* user data argument.
**/
void void
g_array_sort_with_data (GArray *farray, g_array_sort_with_data (GArray *farray,
GCompareDataFunc compare_func, GCompareDataFunc compare_func,
@@ -424,9 +681,64 @@ g_array_maybe_expand (GRealArray *array,
/* Pointer Array /* Pointer 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.
*
* <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>
*
* 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().
*
* <example>
* <title>Using a #GPtrArray</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>
**/
typedef struct _GRealPtrArray GRealPtrArray; typedef struct _GRealPtrArray GRealPtrArray;
/**
* GPtrArray:
* @pdata: points to the array of pointers, which may be moved when the
* array grows.
* @len: number of pointers in the array.
*
* Contains the public fields of a pointer array.
**/
struct _GRealPtrArray struct _GRealPtrArray
{ {
gpointer *pdata; gpointer *pdata;
@@ -436,15 +748,40 @@ struct _GRealPtrArray
GDestroyNotify element_free_func; GDestroyNotify element_free_func;
}; };
/**
* g_ptr_array_index:
* @array: a #GPtrArray.
* @index_: the index of the pointer to return.
* @Returns: the pointer at the given index.
*
* Returns the pointer at the given index of the pointer array.
**/
static void g_ptr_array_maybe_expand (GRealPtrArray *array, static void g_ptr_array_maybe_expand (GRealPtrArray *array,
gint len); gint len);
/**
* g_ptr_array_new:
* @Returns: the new #GPtrArray.
*
* Creates a new #GPtrArray with a reference count of 1.
**/
GPtrArray* GPtrArray*
g_ptr_array_new (void) g_ptr_array_new (void)
{ {
return g_ptr_array_sized_new (0); return g_ptr_array_sized_new (0);
} }
/**
* g_ptr_array_sized_new:
* @reserved_size: number of pointers preallocated.
* @Returns: the new #GPtrArray.
*
* 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.
**/
GPtrArray* GPtrArray*
g_ptr_array_sized_new (guint reserved_size) g_ptr_array_sized_new (guint reserved_size)
{ {
@@ -544,6 +881,24 @@ g_ptr_array_unref (GPtrArray *array)
g_ptr_array_free (array, TRUE); g_ptr_array_free (array, TRUE);
} }
/**
* g_ptr_array_free:
* @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().
*
* 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.
*
* <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>
**/
gpointer* gpointer*
g_ptr_array_free (GPtrArray *farray, g_ptr_array_free (GPtrArray *farray,
gboolean free_segment) gboolean free_segment)
@@ -599,6 +954,16 @@ g_ptr_array_maybe_expand (GRealPtrArray *array,
} }
} }
/**
* g_ptr_array_set_size:
* @array: a #GPtrArray.
* @length: the new length of the pointer array.
*
* 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.
**/
void void
g_ptr_array_set_size (GPtrArray *farray, g_ptr_array_set_size (GPtrArray *farray,
gint length) gint length)
@@ -626,6 +991,17 @@ g_ptr_array_set_size (GPtrArray *farray,
array->len = length; array->len = length;
} }
/**
* g_ptr_array_remove_index:
* @array: a #GPtrArray.
* @index_: the index of the pointer to remove.
* @Returns: the pointer which was removed.
*
* 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.
**/
gpointer gpointer
g_ptr_array_remove_index (GPtrArray *farray, g_ptr_array_remove_index (GPtrArray *farray,
guint index_) guint index_)
@@ -654,6 +1030,18 @@ g_ptr_array_remove_index (GPtrArray *farray,
return result; return result;
} }
/**
* g_ptr_array_remove_index_fast:
* @array: a #GPtrArray.
* @index_: the index of the pointer to remove.
* @Returns: the pointer which was removed.
*
* 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.
**/
gpointer gpointer
g_ptr_array_remove_index_fast (GPtrArray *farray, g_ptr_array_remove_index_fast (GPtrArray *farray,
guint index_) guint index_)
@@ -682,6 +1070,19 @@ g_ptr_array_remove_index_fast (GPtrArray *farray,
return result; return result;
} }
/**
* g_ptr_array_remove_range:
* @array: a @GPtrArray.
* @index_: the index of the first pointer to remove.
* @length: the number of pointers to remove.
*
* 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.
*
* Since: 2.4
**/
void void
g_ptr_array_remove_range (GPtrArray *farray, g_ptr_array_remove_range (GPtrArray *farray,
guint index_, guint index_,
@@ -716,6 +1117,21 @@ g_ptr_array_remove_range (GPtrArray *farray,
} }
} }
/**
* g_ptr_array_remove:
* @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.
*
* 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.
*
* It returns %TRUE if the pointer was removed, or %FALSE if the
* pointer was not found.
**/
gboolean gboolean
g_ptr_array_remove (GPtrArray *farray, g_ptr_array_remove (GPtrArray *farray,
gpointer data) gpointer data)
@@ -737,6 +1153,21 @@ g_ptr_array_remove (GPtrArray *farray,
return FALSE; return FALSE;
} }
/**
* g_ptr_array_remove_fast:
* @array: a #GPtrArray.
* @data: the pointer to remove.
* @Returns: %TRUE if the pointer was found in the array.
*
* 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.
*
* It returns %TRUE if the pointer was removed, or %FALSE if the
* pointer was not found.
**/
gboolean gboolean
g_ptr_array_remove_fast (GPtrArray *farray, g_ptr_array_remove_fast (GPtrArray *farray,
gpointer data) gpointer data)
@@ -758,6 +1189,14 @@ g_ptr_array_remove_fast (GPtrArray *farray,
return FALSE; return FALSE;
} }
/**
* g_ptr_array_add:
* @array: a #GPtrArray.
* @data: the pointer to add.
*
* Adds a pointer to the end of the pointer array. The array will grow
* in size automatically if necessary.
**/
void void
g_ptr_array_add (GPtrArray *farray, g_ptr_array_add (GPtrArray *farray,
gpointer data) gpointer data)
@@ -771,6 +1210,23 @@ g_ptr_array_add (GPtrArray *farray,
array->pdata[array->len++] = data; array->pdata[array->len++] = data;
} }
/**
* g_ptr_array_sort:
* @array: a #GPtrArray.
* @compare_func: comparison function.
*
* 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).
*
* If two array elements compare equal, their order in the sorted array
* is undefined.
*
* <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>
**/
void void
g_ptr_array_sort (GPtrArray *array, g_ptr_array_sort (GPtrArray *array,
GCompareFunc compare_func) GCompareFunc compare_func)
@@ -783,6 +1239,19 @@ g_ptr_array_sort (GPtrArray *array,
compare_func); compare_func);
} }
/**
* g_ptr_array_sort_with_data:
* @array: a #GPtrArray.
* @compare_func: comparison function.
* @user_data: data to pass to @compare_func.
*
* Like g_ptr_array_sort(), but the comparison function has an extra
* user data argument.
*
* <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>
**/
void void
g_ptr_array_sort_with_data (GPtrArray *array, g_ptr_array_sort_with_data (GPtrArray *array,
GCompareDataFunc compare_func, GCompareDataFunc compare_func,
@@ -822,17 +1291,95 @@ g_ptr_array_foreach (GPtrArray *array,
/* Byte arrays /* Byte arrays
*/ */
/**
* SECTION: arrays_byte
* @title: Byte Arrays
* @short_description: arrays of bytes, which grow automatically as
* elements are added
*
* #GByteArray is 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().
*
* <example>
* <title>Using a #GByteArray</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>
**/
/**
* GByteArray:
* @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.
*
* The <structname>GByteArray</structname> struct allows access to the
* public fields of a <structname>GByteArray</structname>.
**/
/**
* g_byte_array_new:
* @Returns: the new #GByteArray.
*
* Creates a new #GByteArray with a reference count of 1.
**/
GByteArray* g_byte_array_new (void) GByteArray* g_byte_array_new (void)
{ {
return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, 0); return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, 0);
} }
/**
* g_byte_array_sized_new:
* @reserved_size: number of bytes preallocated.
* @Returns: the new #GByteArray.
*
* 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.
**/
GByteArray* g_byte_array_sized_new (guint reserved_size) GByteArray* g_byte_array_sized_new (guint reserved_size)
{ {
return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, reserved_size); return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, reserved_size);
} }
/**
* g_byte_array_free:
* @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().
*
* 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.
**/
guint8* g_byte_array_free (GByteArray *array, guint8* g_byte_array_free (GByteArray *array,
gboolean free_segment) gboolean free_segment)
{ {
@@ -873,6 +1420,16 @@ g_byte_array_unref (GByteArray *array)
g_array_unref ((GArray *) array); g_array_unref ((GArray *) array);
} }
/**
* g_byte_array_append:
* @array: a #GByteArray.
* @data: the byte data to be added.
* @len: the number of bytes to add.
* @Returns: the #GByteArray.
*
* Adds the given bytes to the end of the #GByteArray. The array will
* grow in size automatically if necessary.
**/
GByteArray* g_byte_array_append (GByteArray *array, GByteArray* g_byte_array_append (GByteArray *array,
const guint8 *data, const guint8 *data,
guint len) guint len)
@@ -882,6 +1439,16 @@ GByteArray* g_byte_array_append (GByteArray *array,
return array; return array;
} }
/**
* g_byte_array_prepend:
* @array: a #GByteArray.
* @data: the byte data to be added.
* @len: the number of bytes to add.
* @Returns: the #GByteArray.
*
* Adds the given data to the start of the #GByteArray. The array will
* grow in size automatically if necessary.
**/
GByteArray* g_byte_array_prepend (GByteArray *array, GByteArray* g_byte_array_prepend (GByteArray *array,
const guint8 *data, const guint8 *data,
guint len) guint len)
@@ -891,6 +1458,14 @@ GByteArray* g_byte_array_prepend (GByteArray *array,
return array; return array;
} }
/**
* g_byte_array_set_size:
* @array: a #GByteArray.
* @length: the new size of the #GByteArray.
* @Returns: the #GByteArray.
*
* Sets the size of the #GByteArray, expanding it if necessary.
**/
GByteArray* g_byte_array_set_size (GByteArray *array, GByteArray* g_byte_array_set_size (GByteArray *array,
guint length) guint length)
{ {
@@ -899,6 +1474,15 @@ GByteArray* g_byte_array_set_size (GByteArray *array,
return array; return array;
} }
/**
* g_byte_array_remove_index:
* @array: a #GByteArray.
* @index_: the index of the byte to remove.
* @Returns: the #GByteArray.
*
* Removes the byte at the given index from a #GByteArray. The
* following bytes are moved down one place.
**/
GByteArray* g_byte_array_remove_index (GByteArray *array, GByteArray* g_byte_array_remove_index (GByteArray *array,
guint index_) guint index_)
{ {
@@ -907,6 +1491,17 @@ GByteArray* g_byte_array_remove_index (GByteArray *array,
return array; return array;
} }
/**
* g_byte_array_remove_index_fast:
* @array: a #GByteArray.
* @index_: the index of the byte to remove.
* @Returns: the #GByteArray.
*
* 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().
**/
GByteArray* g_byte_array_remove_index_fast (GByteArray *array, GByteArray* g_byte_array_remove_index_fast (GByteArray *array,
guint index_) guint index_)
{ {
@@ -915,6 +1510,18 @@ GByteArray* g_byte_array_remove_index_fast (GByteArray *array,
return array; return array;
} }
/**
* g_byte_array_remove_range:
* @array: a @GByteArray.
* @index_: the index of the first byte to remove.
* @length: the number of bytes to remove.
* @Returns: the #GByteArray.
*
* Removes the given number of bytes starting at the given index from a
* #GByteArray. The following elements are moved to close the gap.
*
* Since: 2.4
**/
GByteArray* GByteArray*
g_byte_array_remove_range (GByteArray *array, g_byte_array_remove_range (GByteArray *array,
guint index_, guint index_,
@@ -927,6 +1534,19 @@ g_byte_array_remove_range (GByteArray *array,
return (GByteArray *)g_array_remove_range ((GArray*) array, index_, length); return (GByteArray *)g_array_remove_range ((GArray*) array, index_, length);
} }
/**
* g_byte_array_sort:
* @array: a #GByteArray.
* @compare_func: comparison function.
*
* 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).
*
* If two array elements compare equal, their order in the sorted array
* is undefined.
**/
void void
g_byte_array_sort (GByteArray *array, g_byte_array_sort (GByteArray *array,
GCompareFunc compare_func) GCompareFunc compare_func)
@@ -934,6 +1554,15 @@ g_byte_array_sort (GByteArray *array,
g_array_sort ((GArray *) array, compare_func); g_array_sort ((GArray *) array, compare_func);
} }
/**
* g_byte_array_sort_with_data:
* @array: a #GByteArray.
* @compare_func: comparison function.
* @user_data: data to pass to @compare_func.
*
* Like g_byte_array_sort(), but the comparison function takes an extra
* user data argument.
**/
void void
g_byte_array_sort_with_data (GByteArray *array, g_byte_array_sort_with_data (GByteArray *array,
GCompareDataFunc compare_func, GCompareDataFunc compare_func,