<refentry id="gobject-Value-arrays">
<refmeta>
<refentrytitle role="top_of_page" id="gobject-Value-arrays.top_of_page">Value arrays</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GOBJECT Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Value arrays</refname>
<refpurpose>A container structure to maintain an array of
    generic values</refpurpose>
</refnamediv>

<refsynopsisdiv id="gobject-Value-arrays.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib-object.h&gt;

                    <link linkend="GValueArray">GValueArray</link>;
<link linkend="GValue">GValue</link>*             <link linkend="g-value-array-get-nth">g_value_array_get_nth</link>               (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="guint">guint</link> index_);
<link linkend="GValueArray">GValueArray</link>*        <link linkend="g-value-array-new">g_value_array_new</link>                   (<link linkend="guint">guint</link> n_prealloced);
<link linkend="GValueArray">GValueArray</link>*        <link linkend="g-value-array-copy">g_value_array_copy</link>                  (const <link linkend="GValueArray">GValueArray</link> *value_array);
<link linkend="void">void</link>                <link linkend="g-value-array-free">g_value_array_free</link>                  (<link linkend="GValueArray">GValueArray</link> *value_array);
<link linkend="GValueArray">GValueArray</link>*        <link linkend="g-value-array-append">g_value_array_append</link>                (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         const <link linkend="GValue">GValue</link> *value);
<link linkend="GValueArray">GValueArray</link>*        <link linkend="g-value-array-prepend">g_value_array_prepend</link>               (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         const <link linkend="GValue">GValue</link> *value);
<link linkend="GValueArray">GValueArray</link>*        <link linkend="g-value-array-insert">g_value_array_insert</link>                (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="guint">guint</link> index_,
                                                         const <link linkend="GValue">GValue</link> *value);
<link linkend="GValueArray">GValueArray</link>*        <link linkend="g-value-array-remove">g_value_array_remove</link>                (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="guint">guint</link> index_);
<link linkend="GValueArray">GValueArray</link>*        <link linkend="g-value-array-sort">g_value_array_sort</link>                  (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="GCompareFunc">GCompareFunc</link> compare_func);
<link linkend="GValueArray">GValueArray</link>*        <link linkend="g-value-array-sort-with-data">g_value_array_sort_with_data</link>        (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                                         <link linkend="gpointer">gpointer</link> user_data);
</synopsis>
</refsynopsisdiv>









<refsect1 id="gobject-Value-arrays.description" role="desc">
<title role="desc.title">Description</title>
<para>
The prime purpose of a <link linkend="GValueArray"><type>GValueArray</type></link> is for it to be used as an
object property that holds an array of values. A <link linkend="GValueArray"><type>GValueArray</type></link> wraps
an array of <link linkend="GValue"><type>GValue</type></link> elements in order for it to be used as a boxed
type through <link linkend="G-TYPE-VALUE-ARRAY--CAPS"><literal>G_TYPE_VALUE_ARRAY</literal></link>.</para>
<para>
</para>
</refsect1>

<refsect1 id="gobject-Value-arrays.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GValueArray" role="struct">
<title>GValueArray</title>
<indexterm zone="GValueArray"><primary sortas="ValueArray">GValueArray</primary></indexterm><programlisting>typedef struct {
  guint   n_values;
  GValue *values;
} GValueArray;
</programlisting>
<para>
A <link linkend="GValueArray"><type>GValueArray</type></link> contains an array of <link linkend="GValue"><type>GValue</type></link> elements.</para>
<para>
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="guint">guint</link>&#160;<structfield>n_values</structfield>;</term>
<listitem><simpara> number of values contained in the array
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GValue">GValue</link>&#160;*<structfield>values</structfield>;</term>
<listitem><simpara> array of values
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-get-nth" role="function">
<title>g_value_array_get_nth ()</title>
<indexterm zone="g-value-array-get-nth"><primary sortas="value_array_get_nth">g_value_array_get_nth</primary></indexterm><programlisting><link linkend="GValue">GValue</link>*             g_value_array_get_nth               (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="guint">guint</link> index_);</programlisting>
<para>
Return a pointer to the value at <parameter>index_</parameter> containd in <parameter>value_array</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to get a value from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara> index of the value of interest
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a value at <parameter>index_</parameter> in <parameter>value_array</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-new" role="function">
<title>g_value_array_new ()</title>
<indexterm zone="g-value-array-new"><primary sortas="value_array_new">g_value_array_new</primary></indexterm><programlisting><link linkend="GValueArray">GValueArray</link>*        g_value_array_new                   (<link linkend="guint">guint</link> n_prealloced);</programlisting>
<para>
Allocate and initialize a new <link linkend="GValueArray"><type>GValueArray</type></link>, optionally preserve space
for <parameter>n_prealloced</parameter> elements. New arrays always contain 0 elements,
regardless of the value of <parameter>n_prealloced</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>n_prealloced</parameter>&#160;:</term>
<listitem><simpara> number of values to preallocate space for
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated <link linkend="GValueArray"><type>GValueArray</type></link> with 0 values
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-copy" role="function">
<title>g_value_array_copy ()</title>
<indexterm zone="g-value-array-copy"><primary sortas="value_array_copy">g_value_array_copy</primary></indexterm><programlisting><link linkend="GValueArray">GValueArray</link>*        g_value_array_copy                  (const <link linkend="GValueArray">GValueArray</link> *value_array);</programlisting>
<para>
Construct an exact copy of a <link linkend="GValueArray"><type>GValueArray</type></link> by duplicating all its
contents.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to copy
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> Newly allocated copy of <link linkend="GValueArray"><type>GValueArray</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-free" role="function">
<title>g_value_array_free ()</title>
<indexterm zone="g-value-array-free"><primary sortas="value_array_free">g_value_array_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_value_array_free                  (<link linkend="GValueArray">GValueArray</link> *value_array);</programlisting>
<para>
Free a <link linkend="GValueArray"><type>GValueArray</type></link> including its contents.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to free
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-append" role="function">
<title>g_value_array_append ()</title>
<indexterm zone="g-value-array-append"><primary sortas="value_array_append">g_value_array_append</primary></indexterm><programlisting><link linkend="GValueArray">GValueArray</link>*        g_value_array_append                (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         const <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Insert a copy of <parameter>value</parameter> as last element of <parameter>value_array</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to add an element to
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValue"><type>GValue</type></link> to copy into <link linkend="GValueArray"><type>GValueArray</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-prepend" role="function">
<title>g_value_array_prepend ()</title>
<indexterm zone="g-value-array-prepend"><primary sortas="value_array_prepend">g_value_array_prepend</primary></indexterm><programlisting><link linkend="GValueArray">GValueArray</link>*        g_value_array_prepend               (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         const <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Insert a copy of <parameter>value</parameter> as first element of <parameter>value_array</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to add an element to
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValue"><type>GValue</type></link> to copy into <link linkend="GValueArray"><type>GValueArray</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-insert" role="function">
<title>g_value_array_insert ()</title>
<indexterm zone="g-value-array-insert"><primary sortas="value_array_insert">g_value_array_insert</primary></indexterm><programlisting><link linkend="GValueArray">GValueArray</link>*        g_value_array_insert                (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="guint">guint</link> index_,
                                                         const <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Insert a copy of <parameter>value</parameter> at specified position into <parameter>value_array</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to add an element to
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara> insertion position, must be &lt;= value_array-&gt;n_values
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValue"><type>GValue</type></link> to copy into <link linkend="GValueArray"><type>GValueArray</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-remove" role="function">
<title>g_value_array_remove ()</title>
<indexterm zone="g-value-array-remove"><primary sortas="value_array_remove">g_value_array_remove</primary></indexterm><programlisting><link linkend="GValueArray">GValueArray</link>*        g_value_array_remove                (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="guint">guint</link> index_);</programlisting>
<para>
Remove the value at position <parameter>index_</parameter> from <parameter>value_array</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to remove an element from
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara> position of value to remove, must be &lt; value_array->n_values
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-sort" role="function">
<title>g_value_array_sort ()</title>
<indexterm zone="g-value-array-sort"><primary sortas="value_array_sort">g_value_array_sort</primary></indexterm><programlisting><link linkend="GValueArray">GValueArray</link>*        g_value_array_sort                  (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="GCompareFunc">GCompareFunc</link> compare_func);</programlisting>
<para>
Sort <parameter>value_array</parameter> using <parameter>compare_func</parameter> to compare the elements accoring to
the semantics of <link linkend="GCompareFunc"><type>GCompareFunc</type></link>.
</para>
<para>
The current implementation uses Quick-Sort as sorting algorithm.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to sort
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter>&#160;:</term>
<listitem><simpara> function to compare elements
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-value-array-sort-with-data" role="function">
<title>g_value_array_sort_with_data ()</title>
<indexterm zone="g-value-array-sort-with-data"><primary sortas="value_array_sort_with_data">g_value_array_sort_with_data</primary></indexterm><programlisting><link linkend="GValueArray">GValueArray</link>*        g_value_array_sort_with_data        (<link linkend="GValueArray">GValueArray</link> *value_array,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Sort <parameter>value_array</parameter> using <parameter>compare_func</parameter> to compare the elements accoring
to the semantics of <link linkend="GCompareDataFunc"><type>GCompareDataFunc</type></link>.
</para>
<para>
The current implementation uses Quick-Sort as sorting algorithm.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>value_array</parameter>&#160;:</term>
<listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to sort
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter>&#160;:</term>
<listitem><simpara> function to compare elements
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> extra data argument provided for <parameter>compare_func</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1 id="gobject-Value-arrays.see-also">
<title>See Also</title>
#GValue, <link linkend="GParamSpecValueArray"><type>GParamSpecValueArray</type></link>, <link linkend="g-param-spec-value-array"><function>g_param_spec_value_array()</function></link>
</refsect1>

</refentry>
