gobject-Value-arrays.html [plain text]
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Value arrays</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="GObject Reference Manual"><link rel="up" href="rn01.html" title="API Reference"><link rel="previous" href="gobject-Closures.html" title="Closures"><link rel="next" href="rn02.html" title="Tools Reference"><link rel="preface" href="pr01.html" title="Introduction"><link rel="reference" href="rn01.html" title="API Reference"><link rel="refentry" href="gobject-Type-Information.html" title="GType"><link rel="refentry" href="GTypePlugin.html" title="GTypePlugin"><link rel="refentry" href="GTypeModule.html" title="GTypeModule"><link rel="refentry" href="gobject-The-Base-Object-Type.html" title="GObject"><link rel="refentry" href="gobject-Enumeration-and-Flag-Types.html" title="Enums and Flags"><link rel="refentry" href="gobject-Boxed-Types.html" title="GBoxed"><link rel="refentry" href="gobject-Generic-values.html" title="Generic Values"><link rel="refentry" href="gobject-Standard-Parameter-and-Value-Types.html" title="Parameters and Values"><link rel="refentry" href="gobject-Varargs-Value-Collection.html" title="Varargs Value Collection"><link rel="refentry" href="gobject-GParamSpec.html" title="GParamSpec"><link rel="refentry" href="gobject-Signals.html" title="Signals"><link rel="refentry" href="gobject-Closures.html" title="Closures"><link rel="refentry" href="gobject-Value-arrays.html" title="Value arrays"><link rel="reference" href="rn02.html" title="Tools Reference"><link rel="refentry" href="glib-mkenums.html" title="glib-mkenums"><link rel="refentry" href="glib-genmarshal.html" title="glib-genmarshal"><link rel="refentry" href="gobject-query.html" title="gobject-query"><link rel="index" href="ix01.html" title="Index"><link rel="section" href="gobject-Value-arrays.html#id2916150" title="Description"><link rel="section" href="gobject-Value-arrays.html#id2916193" title="Details"><link rel="section" href="gobject-Value-arrays.html#id2917528" title="See Also"><meta name="generator" content="GTK-Doc V1.2 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="gobject-Closures.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="rn01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GObject Reference Manual</th><td><a accesskey="n" href="rn02.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="gobject-Value-arrays"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Value arrays</span></h2><p>Value arrays — A container structure to maintain an array of generic values</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
#include <glib-object.h>
struct <a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>;
<a href="gobject-Generic-values.html#GValue">GValue</a>* <a href="gobject-Value-arrays.html#g-value-array-get-nth">g_value_array_get_nth</a> (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Basic-Types.html#guint"
>guint</a> index_);
<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* <a href="gobject-Value-arrays.html#g-value-array-new">g_value_array_new</a> (<a
href="../glib/glib-Basic-Types.html#guint"
>guint</a> n_prealloced);
<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* <a href="gobject-Value-arrays.html#g-value-array-copy">g_value_array_copy</a> (const <a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array);
void <a href="gobject-Value-arrays.html#g-value-array-free">g_value_array_free</a> (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array);
<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* <a href="gobject-Value-arrays.html#g-value-array-append">g_value_array_append</a> (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
const <a href="gobject-Generic-values.html#GValue">GValue</a> *value);
<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* <a href="gobject-Value-arrays.html#g-value-array-prepend">g_value_array_prepend</a> (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
const <a href="gobject-Generic-values.html#GValue">GValue</a> *value);
<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* <a href="gobject-Value-arrays.html#g-value-array-insert">g_value_array_insert</a> (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Basic-Types.html#guint"
>guint</a> index_,
const <a href="gobject-Generic-values.html#GValue">GValue</a> *value);
<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* <a href="gobject-Value-arrays.html#g-value-array-remove">g_value_array_remove</a> (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Basic-Types.html#guint"
>guint</a> index_);
<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* <a href="gobject-Value-arrays.html#g-value-array-sort">g_value_array_sort</a> (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Doubly-Linked-Lists.html#GCompareFunc"
>GCompareFunc</a> compare_func);
<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* <a href="gobject-Value-arrays.html#g-value-array-sort-with-data">g_value_array_sort_with_data</a> (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Doubly-Linked-Lists.html#GCompareDataFunc"
>GCompareDataFunc</a> compare_func,
<a
href="../glib/glib-Basic-Types.html#gpointer"
>gpointer</a> user_data);
</pre></div><div class="refsect1" lang="en"><a name="id2916150"></a><h2>Description</h2><p>
The prime purpose of a <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> is for it to be used as an object property
that holds an array of values. A <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> wraps an array of <a href="gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> elements
in order for it to be used as a boxed type through <tt class="literal">G_TYPE_VALUE_ARRAY</tt>.
</p></div><div class="refsect1" lang="en"><a name="id2916193"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id2916198"></a><h3><a name="GValueArray"></a>struct GValueArray</h3><a class="indexterm" name="id2916209"></a><pre class="programlisting">struct GValueArray {
guint n_values;
GValue *values;
};
</pre><p>
A <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> contains an array of <a href="gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> elements.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><a
href="../glib/glib-Basic-Types.html#guint"
>guint</a> <i class="structfield"><tt>n_values</tt></i></span></td><td> number of values contained in the array
</td></tr><tr><td><span class="term"><a href="gobject-Generic-values.html#GValue">GValue</a> *<i class="structfield"><tt>values</tt></i></span></td><td> array of values
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2916284"></a><h3><a name="g-value-array-get-nth"></a>g_value_array_get_nth ()</h3><a class="indexterm" name="id2916296"></a><pre class="programlisting"><a href="gobject-Generic-values.html#GValue">GValue</a>* g_value_array_get_nth (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Basic-Types.html#guint"
>guint</a> index_);</pre><p>
Return a pointer to the value at <i class="parameter"><tt>index_</tt></i> containd in <i class="parameter"><tt>value_array</tt></i>.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>value_array</tt></i> :</span></td><td><a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> to get a value from
</td></tr><tr><td><span class="term"><i class="parameter"><tt>index_</tt></i> :</span></td><td> index of the value of interest
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> pointer to a value at <i class="parameter"><tt>index_</tt></i> in <i class="parameter"><tt>value_array</tt></i>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2916406"></a><h3><a name="g-value-array-new"></a>g_value_array_new ()</h3><a class="indexterm" name="id2916417"></a><pre class="programlisting"><a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* g_value_array_new (<a
href="../glib/glib-Basic-Types.html#guint"
>guint</a> n_prealloced);</pre><p>
Allocate and initialize a new <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a>, optionally preserve space
for <i class="parameter"><tt>n_prealloced</tt></i> elements. New arrays always contain 0 elements,
regardless of the value of <i class="parameter"><tt>n_prealloced</tt></i>.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>n_prealloced</tt></i> :</span></td><td>number of values to preallocate space for
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> a newly allocated <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> with 0 values
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2916504"></a><h3><a name="g-value-array-copy"></a>g_value_array_copy ()</h3><a class="indexterm" name="id2916516"></a><pre class="programlisting"><a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* g_value_array_copy (const <a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array);</pre><p>
Construct an exact copy of a <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> by duplicating all its
contents.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>value_array</tt></i> :</span></td><td><a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> to copy
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> Newly allocated copy of <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2916596"></a><h3><a name="g-value-array-free"></a>g_value_array_free ()</h3><a class="indexterm" name="id2916608"></a><pre class="programlisting">void g_value_array_free (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array);</pre><p>
Free a <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> including its contents.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>value_array</tt></i> :</span></td><td>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2916662"></a><h3><a name="g-value-array-append"></a>g_value_array_append ()</h3><a class="indexterm" name="id2916673"></a><pre class="programlisting"><a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* g_value_array_append (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
const <a href="gobject-Generic-values.html#GValue">GValue</a> *value);</pre><p>
Insert a copy of <i class="parameter"><tt>value</tt></i> as last element of <i class="parameter"><tt>value_array</tt></i>.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>value_array</tt></i> :</span></td><td><a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> to add an element to
</td></tr><tr><td><span class="term"><i class="parameter"><tt>value</tt></i> :</span></td><td> <a href="gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> to copy into <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a>
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> passed in as <i class="parameter"><tt>value_array</tt></i>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2916800"></a><h3><a name="g-value-array-prepend"></a>g_value_array_prepend ()</h3><a class="indexterm" name="id2916812"></a><pre class="programlisting"><a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* g_value_array_prepend (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
const <a href="gobject-Generic-values.html#GValue">GValue</a> *value);</pre><p>
Insert a copy of <i class="parameter"><tt>value</tt></i> as first element of <i class="parameter"><tt>value_array</tt></i>.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>value_array</tt></i> :</span></td><td><a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> to add an element to
</td></tr><tr><td><span class="term"><i class="parameter"><tt>value</tt></i> :</span></td><td> <a href="gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> to copy into <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a>
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> passed in as <i class="parameter"><tt>value_array</tt></i>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2916938"></a><h3><a name="g-value-array-insert"></a>g_value_array_insert ()</h3><a class="indexterm" name="id2916950"></a><pre class="programlisting"><a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* g_value_array_insert (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Basic-Types.html#guint"
>guint</a> index_,
const <a href="gobject-Generic-values.html#GValue">GValue</a> *value);</pre><p>
Insert a copy of <i class="parameter"><tt>value</tt></i> at specified position into <i class="parameter"><tt>value_array</tt></i>.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>value_array</tt></i> :</span></td><td><a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> to add an element to
</td></tr><tr><td><span class="term"><i class="parameter"><tt>index_</tt></i> :</span></td><td> insertion position, must be <= value_array->n_values
</td></tr><tr><td><span class="term"><i class="parameter"><tt>value</tt></i> :</span></td><td> <a href="gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> to copy into <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a>
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> passed in as <i class="parameter"><tt>value_array</tt></i>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2917099"></a><h3><a name="g-value-array-remove"></a>g_value_array_remove ()</h3><a class="indexterm" name="id2917111"></a><pre class="programlisting"><a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* g_value_array_remove (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Basic-Types.html#guint"
>guint</a> index_);</pre><p>
Remove the value at position <i class="parameter"><tt>index_</tt></i> from <i class="parameter"><tt>value_array</tt></i>.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>value_array</tt></i> :</span></td><td><a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> to remove an element from
</td></tr><tr><td><span class="term"><i class="parameter"><tt>index_</tt></i> :</span></td><td> position of value to remove, must be < value_array->n_values
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> passed in as <i class="parameter"><tt>value_array</tt></i>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2917223"></a><h3><a name="g-value-array-sort"></a>g_value_array_sort ()</h3><a class="indexterm" name="id2917235"></a><pre class="programlisting"><a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* g_value_array_sort (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Doubly-Linked-Lists.html#GCompareFunc"
>GCompareFunc</a> compare_func);</pre><p>
Sort <i class="parameter"><tt>value_array</tt></i> using <i class="parameter"><tt>compare_func</tt></i> to compare the elements accoring to
the semantics of <a
href="../glib/glib-Doubly-Linked-Lists.html#GCompareFunc"
><span class="type">GCompareFunc</span></a>.
</p><p>
The current implementation uses Quick-Sort as sorting algorithm.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>value_array</tt></i> :</span></td><td> <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> to sort
</td></tr><tr><td><span class="term"><i class="parameter"><tt>compare_func</tt></i> :</span></td><td>function to compare elements
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> passed in as <i class="parameter"><tt>value_array</tt></i>
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2917361"></a><h3><a name="g-value-array-sort-with-data"></a>g_value_array_sort_with_data ()</h3><a class="indexterm" name="id2917373"></a><pre class="programlisting"><a href="gobject-Value-arrays.html#GValueArray">GValueArray</a>* g_value_array_sort_with_data (<a href="gobject-Value-arrays.html#GValueArray">GValueArray</a> *value_array,
<a
href="../glib/glib-Doubly-Linked-Lists.html#GCompareDataFunc"
>GCompareDataFunc</a> compare_func,
<a
href="../glib/glib-Basic-Types.html#gpointer"
>gpointer</a> user_data);</pre><p>
Sort <i class="parameter"><tt>value_array</tt></i> using <i class="parameter"><tt>compare_func</tt></i> to compare the elements accoring
to the semantics of <a
href="../glib/glib-Doubly-Linked-Lists.html#GCompareDataFunc"
><span class="type">GCompareDataFunc</span></a>.
</p><p>
The current implementation uses Quick-Sort as sorting algorithm.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>value_array</tt></i> :</span></td><td> <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> to sort
</td></tr><tr><td><span class="term"><i class="parameter"><tt>compare_func</tt></i> :</span></td><td> function to compare elements
</td></tr><tr><td><span class="term"><i class="parameter"><tt>user_data</tt></i> :</span></td><td> extra data argument provided for <i class="parameter"><tt>compare_func</tt></i>
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the <a href="gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> passed in as <i class="parameter"><tt>value_array</tt></i>
</td></tr></tbody></table></div></div></div><div class="refsect1" lang="en"><a name="id2917528"></a><h2>See Also</h2><p>
<a href="gobject-Generic-values.html#GValue"><span class="type">GValue</span></a>, <a href="gobject-Standard-Parameter-and-Value-Types.html#GParamSpecValueArray"><span class="type">GParamSpecValueArray</span></a>, <a href="gobject-Standard-Parameter-and-Value-Types.html#g-param-spec-value-array"><tt class="function">g_param_spec_value_array()</tt></a>
</p></div></div><table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="gobject-Closures.html"><b><< Closures</b></a></td><td align="right"><a accesskey="n" href="rn02.html"><b>Tools Reference >></b></a></td></tr></table></body></html>