mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-10 03:16:17 +01:00
Migrating docs.
* docs/reference/gobject/tmpl/value_arrays.sgml: * gobject/gvaluearray.c: * gobject/gvaluearray.h: Migrating docs. svn path=/trunk/; revision=7085
This commit is contained in:
Stefan Kost
parent
fa7a7b3e0d
commit
80326e2433
@ -1,3 +1,10 @@
|
||||
2008-06-22 Stefan Kost <ensonic@users.sf.net>
|
||||
|
||||
* docs/reference/gobject/tmpl/value_arrays.sgml:
|
||||
* gobject/gvaluearray.c:
|
||||
* gobject/gvaluearray.h:
|
||||
Migrating docs.
|
||||
|
||||
2008-06-22 Stefan Kost <ensonic@users.sf.net>
|
||||
|
||||
* gobject/gsignal.c:
|
||||
|
||||
@ -1,140 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
Value arrays
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
A container structure to maintain an array of generic values
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
#GValue, #GParamSpecValueArray, g_param_spec_value_array()
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### STRUCT GValueArray ##### -->
|
||||
<para>
|
||||
A #GValueArray contains an array of #GValue elements.
|
||||
</para>
|
||||
|
||||
@n_values: number of values contained in the array
|
||||
@values: array of values
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_get_nth ##### -->
|
||||
<para>
|
||||
Return a pointer to the value at @index_ containd in @value_array.
|
||||
</para>
|
||||
|
||||
@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
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_new ##### -->
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
@n_prealloced: number of values to preallocate space for
|
||||
@Returns: a newly allocated #GValueArray with 0 values
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_copy ##### -->
|
||||
<para>
|
||||
Construct an exact copy of a #GValueArray by duplicating all its
|
||||
contents.
|
||||
</para>
|
||||
|
||||
@value_array: #GValueArray to copy
|
||||
@Returns: Newly allocated copy of #GValueArray
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_free ##### -->
|
||||
<para>
|
||||
Free a #GValueArray including its contents.
|
||||
</para>
|
||||
|
||||
@value_array: #GValueArray to free
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_append ##### -->
|
||||
<para>
|
||||
Insert a copy of @value as last element of @value_array.
|
||||
</para>
|
||||
|
||||
@value_array: #GValueArray to add an element to
|
||||
@value: #GValue to copy into #GValueArray
|
||||
@Returns: the #GValueArray passed in as @value_array
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_prepend ##### -->
|
||||
<para>
|
||||
Insert a copy of @value as first element of @value_array.
|
||||
</para>
|
||||
|
||||
@value_array: #GValueArray to add an element to
|
||||
@value: #GValue to copy into #GValueArray
|
||||
@Returns: the #GValueArray passed in as @value_array
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_insert ##### -->
|
||||
<para>
|
||||
Insert a copy of @value at specified position into @value_array.
|
||||
</para>
|
||||
|
||||
@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
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_remove ##### -->
|
||||
<para>
|
||||
Remove the value at position @index_ from @value_array.
|
||||
</para>
|
||||
|
||||
@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
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_sort ##### -->
|
||||
<para>
|
||||
Sort @value_array using @compare_func to compare the elements accoring to
|
||||
the semantics of #GCompareFunc.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The current implementation uses Quick-Sort as sorting algorithm.
|
||||
</para>
|
||||
|
||||
@value_array: #GValueArray to sort
|
||||
@compare_func: function to compare elements
|
||||
@Returns: the #GValueArray passed in as @value_array
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_value_array_sort_with_data ##### -->
|
||||
<para>
|
||||
Sort @value_array using @compare_func to compare the elements accoring
|
||||
to the semantics of #GCompareDataFunc.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The current implementation uses Quick-Sort as sorting algorithm.
|
||||
</para>
|
||||
|
||||
@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
|
||||
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user