From 80326e24332a9519ddf64c01cdecdee2dbda7501 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Sun, 22 Jun 2008 09:45:13 +0000 Subject: [PATCH] Migrating docs. * docs/reference/gobject/tmpl/value_arrays.sgml: * gobject/gvaluearray.c: * gobject/gvaluearray.h: Migrating docs. svn path=/trunk/; revision=7085 --- ChangeLog | 7 + docs/reference/gobject/tmpl/value_arrays.sgml | 140 ------------------ gobject/gvaluearray.c | 108 +++++++++++++- gobject/gvaluearray.h | 7 + 4 files changed, 121 insertions(+), 141 deletions(-) delete mode 100644 docs/reference/gobject/tmpl/value_arrays.sgml diff --git a/ChangeLog b/ChangeLog index 284b05f4d..76d83eb2b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2008-06-22 Stefan Kost + + * docs/reference/gobject/tmpl/value_arrays.sgml: + * gobject/gvaluearray.c: + * gobject/gvaluearray.h: + Migrating docs. + 2008-06-22 Stefan Kost * gobject/gsignal.c: diff --git a/docs/reference/gobject/tmpl/value_arrays.sgml b/docs/reference/gobject/tmpl/value_arrays.sgml deleted file mode 100644 index 36a560cce..000000000 --- a/docs/reference/gobject/tmpl/value_arrays.sgml +++ /dev/null @@ -1,140 +0,0 @@ - -Value arrays - - -A container structure to maintain an array of generic values - - - -The prime purpose of a #GValueArray is for it to be used as an object property -that holds an array of values. A #GValueArray wraps an array of #GValue elements -in order for it to be used as a boxed type through %G_TYPE_VALUE_ARRAY. - - - - -#GValue, #GParamSpecValueArray, g_param_spec_value_array() - - - - - - - -A #GValueArray contains an array of #GValue elements. - - -@n_values: number of values contained in the array -@values: array of values - - - -Return a pointer to the value at @index_ containd in @value_array. - - -@value_array: #GValueArray to get a value from -@index_: index of the value of interest -@Returns: pointer to a value at @index_ in @value_array - - - - -Allocate and initialize a new #GValueArray, optionally preserve space -for @n_prealloced elements. New arrays always contain 0 elements, -regardless of the value of @n_prealloced. - - -@n_prealloced: number of values to preallocate space for -@Returns: a newly allocated #GValueArray with 0 values - - - - -Construct an exact copy of a #GValueArray by duplicating all its -contents. - - -@value_array: #GValueArray to copy -@Returns: Newly allocated copy of #GValueArray - - - - -Free a #GValueArray including its contents. - - -@value_array: #GValueArray to free - - - - -Insert a copy of @value as last element of @value_array. - - -@value_array: #GValueArray to add an element to -@value: #GValue to copy into #GValueArray -@Returns: the #GValueArray passed in as @value_array - - - - -Insert a copy of @value as first element of @value_array. - - -@value_array: #GValueArray to add an element to -@value: #GValue to copy into #GValueArray -@Returns: the #GValueArray passed in as @value_array - - - - -Insert a copy of @value at specified position into @value_array. - - -@value_array: #GValueArray to add an element to -@index_: insertion position, must be <= value_array->n_values -@value: #GValue to copy into #GValueArray -@Returns: the #GValueArray passed in as @value_array - - - - -Remove the value at position @index_ from @value_array. - - -@value_array: #GValueArray to remove an element from -@index_: position of value to remove, must be < value_array->n_values -@Returns: the #GValueArray passed in as @value_array - - - - -Sort @value_array using @compare_func to compare the elements accoring to -the semantics of #GCompareFunc. - - - -The current implementation uses Quick-Sort as sorting algorithm. - - -@value_array: #GValueArray to sort -@compare_func: function to compare elements -@Returns: the #GValueArray passed in as @value_array - - - - -Sort @value_array using @compare_func to compare the elements accoring -to the semantics of #GCompareDataFunc. - - - -The current implementation uses Quick-Sort as sorting algorithm. - - -@value_array: #GValueArray to sort -@compare_func: function to compare elements -@user_data: extra data argument provided for @compare_func -@Returns: the #GValueArray passed in as @value_array - - diff --git a/gobject/gvaluearray.c b/gobject/gvaluearray.c index 308687b79..d0c963fbb 100644 --- a/gobject/gvaluearray.c +++ b/gobject/gvaluearray.c @@ -16,7 +16,16 @@ * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307, USA. */ - +/** + * SECTION:value_arrays + * @Short_description: A container structure to maintain an array of generic values + * @See_also:#GValue, #GParamSpecValueArray, g_param_spec_value_array() + * @Title: Value arrays + * + * The prime purpose of a #GValueArray is for it to be used as an object property + * that holds an array of values. A #GValueArray wraps an array of #GValue elements + * in order for it to be used as a boxed type through %G_TYPE_VALUE_ARRAY. + */ /* * MT safe */ @@ -36,6 +45,15 @@ /* --- functions --- */ +/** + * g_value_array_get_nth: + * @value_array: #GValueArray to get a value from + * @index_: index of the value of interest + * + * Return a pointer to the value at @index_ containd in @value_array. + * + * Returns: pointer to a value at @index_ in @value_array + */ GValue* g_value_array_get_nth (GValueArray *value_array, guint index) @@ -79,6 +97,16 @@ value_array_shrink (GValueArray *value_array) #endif } +/** + * g_value_array_new: + * @n_prealloced: number of values to preallocate space for + * + * Allocate and initialize a new #GValueArray, optionally preserve space + * for @n_prealloced elements. New arrays always contain 0 elements, + * regardless of the value of @n_prealloced. + * + * Returns: a newly allocated #GValueArray with 0 values + */ GValueArray* g_value_array_new (guint n_prealloced) { @@ -93,6 +121,12 @@ g_value_array_new (guint n_prealloced) return value_array; } +/** + * g_value_array_free: + * @value_array: #GValueArray to free + * + * Free a #GValueArray including its contents. + */ void g_value_array_free (GValueArray *value_array) { @@ -111,6 +145,15 @@ g_value_array_free (GValueArray *value_array) g_slice_free (GValueArray, value_array); } +/** + * g_value_array_copy: + * @value_array: #GValueArray to copy + * + * Construct an exact copy of a #GValueArray by duplicating all its + * contents. + * + * Returns: Newly allocated copy of #GValueArray + */ GValueArray* g_value_array_copy (const GValueArray *value_array) { @@ -135,6 +178,15 @@ g_value_array_copy (const GValueArray *value_array) return new_array; } +/** + * g_value_array_prepend: + * @value_array: #GValueArray to add an element to + * @value: #GValue to copy into #GValueArray + * + * Insert a copy of @value as first element of @value_array. + * + * Returns: the #GValueArray passed in as @value_array + */ GValueArray* g_value_array_prepend (GValueArray *value_array, const GValue *value) @@ -144,6 +196,15 @@ g_value_array_prepend (GValueArray *value_array, return g_value_array_insert (value_array, 0, value); } +/** + * g_value_array_append: + * @value_array: #GValueArray to add an element to + * @value: #GValue to copy into #GValueArray + * + * Insert a copy of @value as last element of @value_array. + * + * Returns: the #GValueArray passed in as @value_array + */ GValueArray* g_value_array_append (GValueArray *value_array, const GValue *value) @@ -153,6 +214,16 @@ g_value_array_append (GValueArray *value_array, return g_value_array_insert (value_array, value_array->n_values, value); } +/** + * g_value_array_insert: + * @value_array: #GValueArray to add an element to + * @index_: insertion position, must be <= value_array->n_values + * @value: #GValue to copy into #GValueArray + * + * Insert a copy of @value at specified position into @value_array. + * + * Returns: the #GValueArray passed in as @value_array + */ GValueArray* g_value_array_insert (GValueArray *value_array, guint index, @@ -179,6 +250,15 @@ g_value_array_insert (GValueArray *value_array, return value_array; } +/** + * g_value_array_remove: + * @value_array: #GValueArray to remove an element from + * @index_: position of value to remove, must be < value_array->n_values + * + * Remove the value at position @index_ from @value_array. + * + * Returns: the #GValueArray passed in as @value_array + */ GValueArray* g_value_array_remove (GValueArray *value_array, guint index) @@ -199,6 +279,18 @@ g_value_array_remove (GValueArray *value_array, return value_array; } +/** + * g_value_array_sort: + * @value_array: #GValueArray to sort + * @compare_func: function to compare elements + * + * Sort @value_array using @compare_func to compare the elements accoring to + * the semantics of #GCompareFunc. + * + * The current implementation uses Quick-Sort as sorting algorithm. + * + * Returns: the #GValueArray passed in as @value_array + */ GValueArray* g_value_array_sort (GValueArray *value_array, GCompareFunc compare_func) @@ -213,6 +305,20 @@ g_value_array_sort (GValueArray *value_array, return value_array; } +/** + * g_value_array_sort_with_data: + * @value_array: #GValueArray to sort + * @compare_func: function to compare elements + * @user_data: extra data argument provided for @compare_func + * + * Sort @value_array using @compare_func to compare the elements accoring + * to the semantics of #GCompareDataFunc. + * + * + * The current implementation uses Quick-Sort as sorting algorithm. + * + * Returns: the #GValueArray passed in as @value_array + */ GValueArray* g_value_array_sort_with_data (GValueArray *value_array, GCompareDataFunc compare_func, diff --git a/gobject/gvaluearray.h b/gobject/gvaluearray.h index d6897148f..524dc9fe9 100644 --- a/gobject/gvaluearray.h +++ b/gobject/gvaluearray.h @@ -33,6 +33,13 @@ G_BEGIN_DECLS /* --- typedefs & structs --- */ typedef struct _GValueArray GValueArray; +/** + * GValueArray: + * @n_values: number of values contained in the array + * @values: array of values + * + * A #GValueArray contains an array of #GValue elements. + */ struct _GValueArray { guint n_values;