value_arrays.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<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 <link linkend="GValueArray">GValueArray</link> is a container structure to maintain an array of <link linkend="GValue">GValue</link> elements.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gobject.h&gt;


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);
void        <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">GValueArray</link> is for it to be used as an object property
that holds an array of values. A <link linkend="GValueArray">GValueArray</link> wraps an array of <link linkend="GValue">GValue</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>
<programlisting>struct GValueArray
{
  guint   n_values;
  GValue *values;

  /*&lt; private &gt;*/
  guint   n_prealloced;
};
</programlisting>
<para>
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="guint">guint</link> <structfield>n_values</structfield></entry>
<entry>    number of values contained in the array
</entry>
</row>
<row>
<entry><link linkend="GValue">GValue</link> *<structfield>values</structfield></entry>
<entry>      array of values

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-value-array-get-nth">g_value_array_get_nth ()</title>
<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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>value_array</parameter>&nbsp;:</entry>
<entry><link linkend="GValueArray">GValueArray</link> to get a value from
</entry></row>
<row><entry align="right"><parameter>index</parameter>&nbsp;:</entry>
<entry>      index of the value of interest
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>    pointer to a value at <parameter>index</parameter> in <parameter>value_array</parameter>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-value-array-new">g_value_array_new ()</title>
<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">GValueArray</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><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>n_prealloced</parameter>&nbsp;:</entry>
<entry>number of values to preallocate space for
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>     a newly allocated <link linkend="GValueArray">GValueArray</link> with 0 values


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-value-array-copy">g_value_array_copy ()</title>
<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">GValueArray</link> by duplicating all its
contents.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>value_array</parameter>&nbsp;:</entry>
<entry><link linkend="GValueArray">GValueArray</link> to copy
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>    Newly allocated copy of <link linkend="GValueArray">GValueArray</link>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-value-array-free">g_value_array_free ()</title>
<programlisting>void        g_value_array_free              (<link linkend="GValueArray">GValueArray</link> *value_array);</programlisting>
<para>
Free a <link linkend="GValueArray">GValueArray</link> including its contents.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>value_array</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-value-array-append">g_value_array_append ()</title>