arrays_pointer.sgml

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

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

<refnamediv>
<refname>Pointer Arrays</refname><refpurpose>arrays of pointers to any type of data, which grow automatically as new
elements are added.</refpurpose>
</refnamediv>

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

#include &lt;glib.h&gt;


struct      <link linkend="GPtrArray">GPtrArray</link>;
<link linkend="GPtrArray">GPtrArray</link>*  <link linkend="g-ptr-array-new">g_ptr_array_new</link>                 (void);
<link linkend="GPtrArray">GPtrArray</link>*  <link linkend="g-ptr-array-sized-new">g_ptr_array_sized_new</link>           (<link linkend="guint">guint</link> reserved_size);
void        <link linkend="g-ptr-array-add">g_ptr_array_add</link>                 (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ptr-array-remove">g_ptr_array_remove</link>              (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="gpointer">gpointer</link>    <link linkend="g-ptr-array-remove-index">g_ptr_array_remove_index</link>        (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="guint">guint</link> index);
<link linkend="gboolean">gboolean</link>    <link linkend="g-ptr-array-remove-fast">g_ptr_array_remove_fast</link>         (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="gpointer">gpointer</link>    <link linkend="g-ptr-array-remove-index-fast">g_ptr_array_remove_index_fast</link>   (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="guint">guint</link> index);
void        <link linkend="g-ptr-array-sort">g_ptr_array_sort</link>                (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="GCompareFunc">GCompareFunc</link> compare_func);
void        <link linkend="g-ptr-array-sort-with-data">g_ptr_array_sort_with_data</link>      (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                             <link linkend="gpointer">gpointer</link> user_data);
void        <link linkend="g-ptr-array-set-size">g_ptr_array_set_size</link>            (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="gint">gint</link> length);
#define     <link linkend="g-ptr-array-index">g_ptr_array_index</link>               (array,index)
<link linkend="gpointer">gpointer</link>*   <link linkend="g-ptr-array-free">g_ptr_array_free</link>                (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="gboolean">gboolean</link> free_seg);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
Pointer Arrays are similar to Arrays but are used only for storing pointers.
</para>
<note>
<para>
If you remove elements from the array, elements at the end of the array
are moved into the space previously occupied by the removed element.
This means that you should not rely on the index of particular elements
remaining the same. You should also be careful when deleting elements while
iterating over the array.
</para>
</note>
<para>
To create a pointer array, use <link linkend="g-ptr-array-new">g_ptr_array_new</link>().
</para>
<para>
To add elements to a pointer array, use <link linkend="g-ptr-array-add">g_ptr_array_add</link>().
</para>
<para>
To remove elements from a pointer array, use <link linkend="g-ptr-array-remove">g_ptr_array_remove</link>(),
<link linkend="g-ptr-array-remove-index">g_ptr_array_remove_index</link>() or <link linkend="g-ptr-array-remove-index-fast">g_ptr_array_remove_index_fast</link>().
</para>
<para>
To access an element of a pointer array, use <link linkend="g-ptr-array-index">g_ptr_array_index</link>().
</para>
<para>
To set the size of a pointer array, use <link linkend="g-ptr-array-set-size">g_ptr_array_set_size</link>().
</para>
<para>
To free a pointer array, use <link linkend="g-ptr-array-free">g_ptr_array_free</link>().
</para>
<example>
<title>Using a <structname>GPtrArray</structname>.</title>
<programlisting>
  GPtrArray *gparray;
  gchar *string1 = "one", *string2 = "two", *string3 = "three";

  gparray = g_ptr_array_new (<!>);
  g_ptr_array_add (gparray, (gpointer) string1);
  g_ptr_array_add (gparray, (gpointer) string2);
  g_ptr_array_add (gparray, (gpointer) string3);

  if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
    g_print ("ERROR: got <literal>p</literal> instead of <literal>p</literal>\n",
             g_ptr_array_index (gparray, 0), string1);

  g_ptr_array_free (gparray, TRUE);
</programlisting></example>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GPtrArray">struct GPtrArray</title>
<programlisting>struct GPtrArray
{
  gpointer *pdata;
  guint	    len;
};
</programlisting>
<para>
Contains the public fields of a pointer array.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="gpointer">gpointer</link> *<structfield>pdata</structfield></entry>
<entry>points to the array of pointers, which may be moved when the array grows.
</entry>
</row>
<row>
<entry><link linkend="guint">guint</link> <structfield>len</structfield></entry>
<entry>number of pointers in the array.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-new">g_ptr_array_new ()</title>
<programlisting><link linkend="GPtrArray">GPtrArray</link>*  g_ptr_array_new                 (void);</programlisting>
<para>
Creates a new <link linkend="GPtrArray">GPtrArray</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GPtrArray">GPtrArray</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-sized-new">g_ptr_array_sized_new ()</title>
<programlisting><link linkend="GPtrArray">GPtrArray</link>*  g_ptr_array_sized_new           (<link linkend="guint">guint</link> reserved_size);</programlisting>
<para>
Creates a new <link linkend="GPtrArray">GPtrArray</link> with <parameter>reserved_size</parameter> pointers
preallocated. This avoids frequent reallocation, if you are going to
add many pointers 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>reserved_size</parameter>&nbsp;:</entry>
<entry>number of pointers preallocated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GPtrArray">GPtrArray</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-add">g_ptr_array_add ()</title>
<programlisting>void        g_ptr_array_add                 (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Adds a pointer to the end of the pointer array.
The array will grow in size automatically if necessary.
</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="GPtrArray">GPtrArray</link>.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the pointer to add.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-remove">g_ptr_array_remove ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_ptr_array_remove              (<link linkend="GPtrArray">GPtrArray</link> *array,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Removes the first occurrence of the given pointer from the pointer array.
The following elements are moved down one place.
</para>
<para>
It returns <literal>TRUE</literal> if the pointer was removed, or <literal>FALSE</literal> if the pointer
was not found.
</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="GPtrArray">GPtrArray</link>.
</entry></row>