arrays.sgml

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

<refentry id="glib-Arrays">
<refmeta>
<refentrytitle>Arrays</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Arrays</refname><refpurpose>arrays of arbitrary elements which grow automatically as elements are added.</refpurpose>
</refnamediv>

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

#include &lt;glib.h&gt;


struct      <link linkend="GArray">GArray</link>;
<link linkend="GArray">GArray</link>*     <link linkend="g-array-new">g_array_new</link>                     (<link linkend="gboolean">gboolean</link> zero_terminated,
                                             <link linkend="gboolean">gboolean</link> clear,
                                             <link linkend="guint">guint</link> element_size);
<link linkend="GArray">GArray</link>*     <link linkend="g-array-sized-new">g_array_sized_new</link>               (<link linkend="gboolean">gboolean</link> zero_terminated,
                                             <link linkend="gboolean">gboolean</link> clear,
                                             <link linkend="guint">guint</link> element_size,
                                             <link linkend="guint">guint</link> reserved_size);
#define     <link linkend="g-array-append-val">g_array_append_val</link>              (a,v)
<link linkend="GArray">GArray</link>*     <link linkend="g-array-append-vals">g_array_append_vals</link>             (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="gconstpointer">gconstpointer</link> data,
                                             <link linkend="guint">guint</link> len);
#define     <link linkend="g-array-prepend-val">g_array_prepend_val</link>             (a,v)
<link linkend="GArray">GArray</link>*     <link linkend="g-array-prepend-vals">g_array_prepend_vals</link>            (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="gconstpointer">gconstpointer</link> data,
                                             <link linkend="guint">guint</link> len);
#define     <link linkend="g-array-insert-val">g_array_insert_val</link>              (a,i,v)
<link linkend="GArray">GArray</link>*     <link linkend="g-array-insert-vals">g_array_insert_vals</link>             (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="guint">guint</link> index,
                                             <link linkend="gconstpointer">gconstpointer</link> data,
                                             <link linkend="guint">guint</link> len);
<link linkend="GArray">GArray</link>*     <link linkend="g-array-remove-index">g_array_remove_index</link>            (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="guint">guint</link> index);
<link linkend="GArray">GArray</link>*     <link linkend="g-array-remove-index-fast">g_array_remove_index_fast</link>       (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="guint">guint</link> index);
void        <link linkend="g-array-sort">g_array_sort</link>                    (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="GCompareFunc">GCompareFunc</link> compare_func);
void        <link linkend="g-array-sort-with-data">g_array_sort_with_data</link>          (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                             <link linkend="gpointer">gpointer</link> user_data);
#define     <link linkend="g-array-index">g_array_index</link>                   (a,t,i)
<link linkend="GArray">GArray</link>*     <link linkend="g-array-set-size">g_array_set_size</link>                (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="guint">guint</link> length);
<link linkend="gchar">gchar</link>*      <link linkend="g-array-free">g_array_free</link>                    (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="gboolean">gboolean</link> free_segment);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
Arrays are similar to standard C arrays, except that they grow automatically
as elements are added.
</para>
<para>
Array elements can be of any size (though all elements of one array are the
same size), and the array can be automatically cleared to '0's and
zero-terminated.
</para>
<para>
To create a new array use <link linkend="g-array-new">g_array_new</link>().
</para>
<para>
To add elements to an array, use <link linkend="g-array-append-val">g_array_append_val</link>(), <link linkend="g-array-append-vals">g_array_append_vals</link>(),
<link linkend="g-array-prepend-val">g_array_prepend_val</link>(), and <link linkend="g-array-prepend-vals">g_array_prepend_vals</link>().
</para>
<para>
To access an element of an array, use <link linkend="g-array-index">g_array_index</link>().
</para>
<para>
To set the size of an array, use <link linkend="g-array-set-size">g_array_set_size</link>().
</para>
<para>
To free an array, use <link linkend="g-array-free">g_array_free</link>().
</para>
<example>
<title>Using a <structname>GArray</structname> to store gint values.</title>
<programlisting>
  GArray *garray;
  gint i;

  /* We create a new array to store gint values.
     We don't want it zero-terminated or cleared to 0's. */
  garray = g_array_new (FALSE, FALSE, sizeof (gint));
  for (i = 0; i < 10000; i++)
    g_array_append_val (garray, i);

  for (i = 0; i < 10000; i++)
    if (g_array_index (garray, gint, i) != i)
      g_print ("ERROR: got <literal>d</literal> instead of <literal>d</literal>\n",
               g_array_index (garray, gint, i), i);

  g_array_free (garray, TRUE);
</programlisting></example>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GArray">struct GArray</title>
<programlisting>struct GArray
{
  gchar *data;
  guint len;
};
</programlisting>
<para>
Contains the public fields of an <link linkend="glib-arrays">Array</link>.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="gchar">gchar</link> *<structfield>data</structfield></entry>
<entry>a pointer to the element data. The data may be moved as elements are
added to the <link linkend="GArray">GArray</link>.
</entry>
</row>
<row>
<entry><link linkend="guint">guint</link> <structfield>len</structfield></entry>
<entry>the number of elements in the <link linkend="GArray">GArray</link>.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-array-new">g_array_new ()</title>
<programlisting><link linkend="GArray">GArray</link>*     g_array_new                     (<link linkend="gboolean">gboolean</link> zero_terminated,
                                             <link linkend="gboolean">gboolean</link> clear,
                                             <link linkend="guint">guint</link> element_size);</programlisting>
<para>
Creates a new <link linkend="GArray">GArray</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>zero_terminated</parameter>&nbsp;:</entry>
<entry><literal>TRUE</literal> if the array should have an extra element at the end
which is set to 0.
</entry></row>
<row><entry align="right"><parameter>clear</parameter>&nbsp;:</entry>
<entry><literal>TRUE</literal> if <link linkend="GArray">GArray</link> elements should be automatically cleared to 0
when they are allocated.
</entry></row>
<row><entry align="right"><parameter>element_size</parameter>&nbsp;:</entry>
<entry>the size of each element in bytes.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GArray">GArray</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-array-sized-new">g_array_sized_new ()</title>
<programlisting><link linkend="GArray">GArray</link>*     g_array_sized_new               (<link linkend="gboolean">gboolean</link> zero_terminated,
                                             <link linkend="gboolean">gboolean</link> clear,
                                             <link linkend="guint">guint</link> element_size,
                                             <link linkend="guint">guint</link> reserved_size);</programlisting>
<para>
Creates a new <link linkend="GArray">GArray</link> with <parameter>reserved_size</parameter> elements
preallocated. This avoids frequent reallocation, if you are going to
add many elements to the array. Note however that the size of the
array is still 0.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>zero_terminated</parameter>&nbsp;:</entry>
<entry><literal>TRUE</literal> if the array should have an extra element at the end with all bits cleared.
</entry></row>
<row><entry align="right"><parameter>clear</parameter>&nbsp;:</entry>
<entry><literal>TRUE</literal> if all bits in the array should be cleared to 0 on allocation.
</entry></row>
<row><entry align="right"><parameter>element_size</parameter>&nbsp;:</entry>
<entry>size of each element in the array.
</entry></row>
<row><entry align="right"><parameter>reserved_size</parameter>&nbsp;:</entry>
<entry>number of elements preallocated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GArray">GArray</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-array-append-val">g_array_append_val()</title>
<programlisting>#define     g_array_append_val(a,v)</programlisting>
<para>
Adds the value on to the end of the array.
The array will grow in size automatically if necessary.
</para>
<note>
<para>
<link linkend="g-array-append-val">g_array_append_val</link>() is a macro which uses a reference to the value
parameter <parameter>v</parameter>. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>a</parameter>&nbsp;:</entry>
<entry>a <link linkend="GArray">GArray</link>.
</entry></row>
<row><entry align="right"><parameter>v</parameter>&nbsp;:</entry>
<entry>the value to append to the <link linkend="GArray">GArray</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GArray">GArray</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-array-append-vals">g_array_append_vals ()</title>
<programlisting><link linkend="GArray">GArray</link>*     g_array_append_vals             (<link linkend="GArray">GArray</link> *array,
                                             <link linkend="gconstpointer">gconstpointer</link> data,
                                             <link linkend="guint">guint</link> len);</programlisting>
<para>
Adds <parameter>len</parameter> elements onto the end of the array.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>array</parameter>&nbsp;:</entry>
<entry>a <link linkend="GArray">GArray</link>.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>a pointer to the elements to append to the end of the array.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>the number of elements to append.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GArray">GArray</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-array-prepend-val">g_array_prepend_val()</title>
<programlisting>#define     g_array_prepend_val(a,v)</programlisting>
<para>
Adds the value on to the start of the array.
The array will grow in size automatically if necessary.
</para>
<para>
This operation is slower than <link linkend="g-array-append-val">g_array_append_val</link>() since the existing elements
in the array have to be moved to make space for the new element.
</para>
<note>
<para>
<link linkend="g-array-prepend-val">g_array_prepend_val</link>() is a macro which uses a reference to the value
parameter <parameter>v</parameter>. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>a</parameter>&nbsp;:</entry>
<entry>a <link linkend="GArray">GArray</link>.
</entry></row>
<row><entry align="right"><parameter>v</parameter>&nbsp;:</entry>
<entry>the value to prepend to the <link linkend="GArray">GArray</link>.
</entry></row>