<refentry id="gobject-Value-arrays"> <refmeta> <refentrytitle>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><title>Synopsis</title> <synopsis> #include <glib-object.h> struct <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> <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 <literal>G_TYPE_VALUE_ARRAY</literal>. </para> </refsect1> <refsect1> <title>Details</title> <refsect2> <title><anchor id="GValueArray"/>struct GValueArray</title> <indexterm><primary>GValueArray</primary></indexterm><programlisting>struct GValueArray { guint n_values; GValue *values; }; </programlisting> <para> A <link linkend="GValueArray"><type>GValueArray</type></link> contains an array of <link linkend="GValue"><type>GValue</type></link> elements. </para><variablelist role="struct"> <varlistentry> <term><link linkend="guint">guint</link> <structfield>n_values</structfield></term> <listitem><simpara> number of values contained in the array </simpara></listitem> </varlistentry> <varlistentry> <term><link linkend="GValue">GValue</link> *<structfield>values</structfield></term> <listitem><simpara> array of values </simpara></listitem> </varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-get-nth"/>g_value_array_get_nth ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>value_array</parameter> :</term> <listitem><simpara><link linkend="GValueArray"><type>GValueArray</type></link> to get a value from </simpara></listitem></varlistentry> <varlistentry><term><parameter>index_</parameter> :</term> <listitem><simpara> index of the value of interest </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> pointer to a value at <parameter>index_</parameter> in <parameter>value_array</parameter> </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-new"/>g_value_array_new ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>n_prealloced</parameter> :</term> <listitem><simpara>number of values to preallocate space for </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated <link linkend="GValueArray"><type>GValueArray</type></link> with 0 values </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-copy"/>g_value_array_copy ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>value_array</parameter> :</term> <listitem><simpara><link linkend="GValueArray"><type>GValueArray</type></link> to copy </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Newly allocated copy of <link linkend="GValueArray"><type>GValueArray</type></link> </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-free"/>g_value_array_free ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>value_array</parameter> :</term> <listitem><simpara> </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-append"/>g_value_array_append ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>value_array</parameter> :</term> <listitem><simpara><link linkend="GValueArray"><type>GValueArray</type></link> to add an element to </simpara></listitem></varlistentry> <varlistentry><term><parameter>value</parameter> :</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> :</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter> </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-prepend"/>g_value_array_prepend ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>value_array</parameter> :</term> <listitem><simpara><link linkend="GValueArray"><type>GValueArray</type></link> to add an element to </simpara></listitem></varlistentry> <varlistentry><term><parameter>value</parameter> :</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> :</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter> </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-insert"/>g_value_array_insert ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>value_array</parameter> :</term> <listitem><simpara><link linkend="GValueArray"><type>GValueArray</type></link> to add an element to </simpara></listitem></varlistentry> <varlistentry><term><parameter>index_</parameter> :</term> <listitem><simpara> insertion position, must be <= value_array->n_values </simpara></listitem></varlistentry> <varlistentry><term><parameter>value</parameter> :</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> :</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter> </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-remove"/>g_value_array_remove ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>value_array</parameter> :</term> <listitem><simpara><link linkend="GValueArray"><type>GValueArray</type></link> to remove an element from </simpara></listitem></varlistentry> <varlistentry><term><parameter>index_</parameter> :</term> <listitem><simpara> position of value to remove, must be < value_array->n_values </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter> </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-sort"/>g_value_array_sort ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>value_array</parameter> :</term> <listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to sort </simpara></listitem></varlistentry> <varlistentry><term><parameter>compare_func</parameter> :</term> <listitem><simpara>function to compare elements </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="GValueArray"><type>GValueArray</type></link> passed in as <parameter>value_array</parameter> </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-value-array-sort-with-data"/>g_value_array_sort_with_data ()</title> <indexterm><primary>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><variablelist role="params"> <varlistentry><term><parameter>value_array</parameter> :</term> <listitem><simpara> <link linkend="GValueArray"><type>GValueArray</type></link> to sort </simpara></listitem></varlistentry> <varlistentry><term><parameter>compare_func</parameter> :</term> <listitem><simpara> function to compare elements </simpara></listitem></varlistentry> <varlistentry><term><parameter>user_data</parameter> :</term> <listitem><simpara> extra data argument provided for <parameter>compare_func</parameter> </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</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> <title>See Also</title> <para> <link linkend="GValue"><type>GValue</type></link>, <link linkend="GParamSpecValueArray"><type>GParamSpecValueArray</type></link>, <link linkend="g-param-spec-value-array"><function>g_param_spec_value_array()</function></link> </para> </refsect1> </refentry>