luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-09-27 17:52:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

Migrating docs.

Browse Source 
* 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
2008-06-22 09:45:13 +00:00
parent fa7a7b3e0d
commit 80326e2433
4 changed files with 121 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
ChangeLog
View File

@@ -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> 2008-06-22 Stefan Kost <ensonic@users.sf.net>
* gobject/gsignal.c: * gobject/gsignal.c:

140
docs/reference/gobject/tmpl/value_arrays.sgml
View File

@@ -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 &lt;= value_array-&gt;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 &lt; 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

108
gobject/gvaluearray.c
View File

@@ -16,7 +16,16 @@
* Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA. * 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 * MT safe
*/ */
@@ -36,6 +45,15 @@
/* --- functions --- */ /* --- 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* GValue*
g_value_array_get_nth (GValueArray *value_array, g_value_array_get_nth (GValueArray *value_array,
guint index) guint index)
@@ -79,6 +97,16 @@ value_array_shrink (GValueArray *value_array)
#endif #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* GValueArray*
g_value_array_new (guint n_prealloced) g_value_array_new (guint n_prealloced)
{ {
@@ -93,6 +121,12 @@ g_value_array_new (guint n_prealloced)
return value_array; return value_array;
} }
/**
* g_value_array_free:
* @value_array: #GValueArray to free
*
* Free a #GValueArray including its contents.
*/
void void
g_value_array_free (GValueArray *value_array) 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_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* GValueArray*
g_value_array_copy (const GValueArray *value_array) g_value_array_copy (const GValueArray *value_array)
{ {
@@ -135,6 +178,15 @@ g_value_array_copy (const GValueArray *value_array)
return new_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* GValueArray*
g_value_array_prepend (GValueArray *value_array, g_value_array_prepend (GValueArray *value_array,
const GValue *value) const GValue *value)
@@ -144,6 +196,15 @@ g_value_array_prepend (GValueArray *value_array,
return g_value_array_insert (value_array, 0, value); 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* GValueArray*
g_value_array_append (GValueArray *value_array, g_value_array_append (GValueArray *value_array,
const GValue *value) 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); 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 &lt;= value_array-&gt;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* GValueArray*
g_value_array_insert (GValueArray *value_array, g_value_array_insert (GValueArray *value_array,
guint index, guint index,
@@ -179,6 +250,15 @@ g_value_array_insert (GValueArray *value_array,
return 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 &lt; value_array->n_values
*
* Remove the value at position @index_ from @value_array.
*
* Returns: the #GValueArray passed in as @value_array
*/
GValueArray* GValueArray*
g_value_array_remove (GValueArray *value_array, g_value_array_remove (GValueArray *value_array,
guint index) guint index)
@@ -199,6 +279,18 @@ g_value_array_remove (GValueArray *value_array,
return 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* GValueArray*
g_value_array_sort (GValueArray *value_array, g_value_array_sort (GValueArray *value_array,
GCompareFunc compare_func) GCompareFunc compare_func)
@@ -213,6 +305,20 @@ g_value_array_sort (GValueArray *value_array,
return 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* GValueArray*
g_value_array_sort_with_data (GValueArray *value_array, g_value_array_sort_with_data (GValueArray *value_array,
GCompareDataFunc compare_func, GCompareDataFunc compare_func,

7
gobject/gvaluearray.h
View File

@@ -33,6 +33,13 @@ G_BEGIN_DECLS
/* --- typedefs & structs --- */ /* --- typedefs & structs --- */
typedef struct _GValueArray GValueArray; 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 struct _GValueArray
{ {
guint n_values; guint n_values;