arrays_pointer.xml [plain text]
<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 <glib.h>
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);
<link linkend="void">void</link> <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_);
<link linkend="void">void</link> <link linkend="g-ptr-array-remove-range">g_ptr_array_remove_range</link> (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="guint">guint</link> index_,
<link linkend="guint">guint</link> length);
<link linkend="void">void</link> <link linkend="g-ptr-array-sort">g_ptr_array_sort</link> (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="GCompareFunc">GCompareFunc</link> compare_func);
<link linkend="void">void</link> <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);
<link linkend="void">void</link> <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);
<link linkend="void">void</link> <link linkend="g-ptr-array-foreach">g_ptr_array_foreach</link> (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="GFunc">GFunc</link> func,
<link linkend="gpointer">gpointer</link> user_data);
</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"><function>g_ptr_array_new()</function></link>.
</para>
<para>
To add elements to a pointer array, use <link linkend="g-ptr-array-add"><function>g_ptr_array_add()</function></link>.
</para>
<para>
To remove elements from a pointer array, use <link linkend="g-ptr-array-remove"><function>g_ptr_array_remove()</function></link>,
<link linkend="g-ptr-array-remove-index"><function>g_ptr_array_remove_index()</function></link> or <link linkend="g-ptr-array-remove-index-fast"><function>g_ptr_array_remove_index_fast()</function></link>.
</para>
<para>
To access an element of a pointer array, use <link linkend="g-ptr-array-index"><function>g_ptr_array_index()</function></link>.
</para>
<para>
To set the size of a pointer array, use <link linkend="g-ptr-array-set-size"><function>g_ptr_array_set_size()</function></link>.
</para>
<para>
To free a pointer array, use <link linkend="g-ptr-array-free"><function>g_ptr_array_free()</function></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 %p instead of %p\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>
<indexterm><primary>GPtrArray</primary></indexterm><programlisting>struct GPtrArray {
gpointer *pdata;
guint len;
};
</programlisting>
<para>
Contains the public fields of a pointer array.
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="gpointer">gpointer</link> *<structfield>pdata</structfield></term>
<listitem><simpara>points to the array of pointers, which may be moved when the array grows.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="guint">guint</link> <structfield>len</structfield></term>
<listitem><simpara>number of pointers in the array.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-new"/>g_ptr_array_new ()</title>
<indexterm><primary>g_ptr_array_new</primary></indexterm><programlisting><link linkend="GPtrArray">GPtrArray</link>* g_ptr_array_new (void);</programlisting>
<para>
Creates a new <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the new <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-sized-new"/>g_ptr_array_sized_new ()</title>
<indexterm><primary>g_ptr_array_sized_new</primary></indexterm><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"><type>GPtrArray</type></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><variablelist role="params">
<varlistentry><term><parameter>reserved_size</parameter> :</term>
<listitem><simpara>number of pointers preallocated.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the new <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-add"/>g_ptr_array_add ()</title>
<indexterm><primary>g_ptr_array_add</primary></indexterm><programlisting><link linkend="void">void</link> 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><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>the pointer to add.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-remove"/>g_ptr_array_remove ()</title>
<indexterm><primary>g_ptr_array_remove</primary></indexterm><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><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>the pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if the pointer is removed. <literal>FALSE</literal> if the pointer is not found
in the array.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-remove-index"/>g_ptr_array_remove_index ()</title>
<indexterm><primary>g_ptr_array_remove_index</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_ptr_array_remove_index (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="guint">guint</link> index_);</programlisting>
<para>
Removes the pointer at the given index from the pointer array.
The following elements are moved down one place.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter> :</term>
<listitem><simpara>the index of the pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the pointer which was removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-remove-fast"/>g_ptr_array_remove_fast ()</title>
<indexterm><primary>g_ptr_array_remove_fast</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_ptr_array_remove_fast (<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 last element in the array is used to fill in the space, so this function
does not preserve the order of the array. But it is faster than
<link linkend="g-ptr-array-remove"><function>g_ptr_array_remove()</function></link>.
</para>
<para>
It returns <literal>TRUE</literal> if the pointer was removed, or <literal>FALSE</literal> if the pointer
was not found.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara>the pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if the pointer was found in the array.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-remove-index-fast"/>g_ptr_array_remove_index_fast ()</title>
<indexterm><primary>g_ptr_array_remove_index_fast</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_ptr_array_remove_index_fast (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="guint">guint</link> index_);</programlisting>
<para>
Removes the pointer at the given index from the pointer array.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the array. But it is faster than
<link linkend="g-ptr-array-remove-index"><function>g_ptr_array_remove_index()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter> :</term>
<listitem><simpara>the index of the pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the pointer which was removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-remove-range"/>g_ptr_array_remove_range ()</title>
<indexterm role="2.4"><primary>g_ptr_array_remove_range</primary></indexterm><programlisting><link linkend="void">void</link> g_ptr_array_remove_range (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="guint">guint</link> index_,
<link linkend="guint">guint</link> length);</programlisting>
<para>
Removes the given number of bytes starting at the given index from a
<link linkend="GPtrArray"><type>GPtrArray</type></link>. The following elements are moved to close the gap.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <parameter>GPtrArray</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter> :</term>
<listitem><simpara>the index of the first pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter> :</term>
<listitem><simpara>the number of pointers to remove.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-sort"/>g_ptr_array_sort ()</title>
<indexterm><primary>g_ptr_array_sort</primary></indexterm><programlisting><link linkend="void">void</link> g_ptr_array_sort (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="GCompareFunc">GCompareFunc</link> compare_func);</programlisting>
<para>
Sorts the array, using <parameter>compare_func</parameter> which should be a <link linkend="qsort"><function>qsort()</function></link>-style comparison
function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
first arg is greater than second arg).
</para>
<note><para>
The comparison function for <link linkend="g-ptr-array-sort"><function>g_ptr_array_sort()</function></link> doesn't take the pointers from the array as arguments,
it takes pointers to the pointers in the array.
</para></note><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter> :</term>
<listitem><simpara>comparison function.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-sort-with-data"/>g_ptr_array_sort_with_data ()</title>
<indexterm><primary>g_ptr_array_sort_with_data</primary></indexterm><programlisting><link linkend="void">void</link> g_ptr_array_sort_with_data (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Like <link linkend="g-ptr-array-sort"><function>g_ptr_array_sort()</function></link>, but the comparison function has a user data argument.
</para>
<note><para>
The comparison function for <link linkend="g-ptr-array-sort-with-data"><function>g_ptr_array_sort_with_data()</function></link> doesn't take the pointers from the array as arguments,
it takes pointers to the pointers in the array.
</para></note><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter> :</term>
<listitem><simpara>comparison function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara>data to pass to <parameter>compare_func</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-set-size"/>g_ptr_array_set_size ()</title>
<indexterm><primary>g_ptr_array_set_size</primary></indexterm><programlisting><link linkend="void">void</link> g_ptr_array_set_size (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="gint">gint</link> length);</programlisting>
<para>
Sets the size of the array, expanding it if necessary.
New elements are set to <literal>NULL</literal>.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter> :</term>
<listitem><simpara>the new length of the pointer array.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-index"/>g_ptr_array_index()</title>
<indexterm><primary>g_ptr_array_index</primary></indexterm><programlisting>#define g_ptr_array_index(array,index_)</programlisting>
<para>
Returns the pointer at the given index of the pointer array.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter> :</term>
<listitem><simpara>the index of the pointer to return.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the pointer at the given index.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-free"/>g_ptr_array_free ()</title>
<indexterm><primary>g_ptr_array_free</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>* g_ptr_array_free (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="gboolean">gboolean</link> free_seg);</programlisting>
<para>
Frees all of the memory allocated for the pointer array.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>free_seg</parameter> :</term>
<listitem><simpara>if <literal>TRUE</literal> the actual element data is freed as well.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-ptr-array-foreach"/>g_ptr_array_foreach ()</title>
<indexterm role="2.4"><primary>g_ptr_array_foreach</primary></indexterm><programlisting><link linkend="void">void</link> g_ptr_array_foreach (<link linkend="GPtrArray">GPtrArray</link> *array,
<link linkend="GFunc">GFunc</link> func,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Calls a function for each element of a <link linkend="GPtrArray"><type>GPtrArray</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter> :</term>
<listitem><simpara> a <link linkend="GPtrArray"><type>GPtrArray</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter> :</term>
<listitem><simpara> the function to call for each array element
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara> user data to pass to the function
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4
</para></refsect2>
</refsect1>
</refentry>