<refentry id="glib-Pointer-Arrays">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Pointer-Arrays.top_of_page">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 id="glib-Pointer-Arrays.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <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="GPtrArray">GPtrArray</link>*          <link linkend="g-ptr-array-new-with-free-func">g_ptr_array_new_with_free_func</link>      (<link linkend="GDestroyNotify">GDestroyNotify</link> element_free_func);
<link linkend="void">void</link>                <link linkend="g-ptr-array-set-free-func">g_ptr_array_set_free_func</link>           (<link linkend="GPtrArray">GPtrArray</link> *array,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> element_free_func);
<link linkend="GPtrArray">GPtrArray</link>*          <link linkend="g-ptr-array-ref">g_ptr_array_ref</link>                     (<link linkend="GPtrArray">GPtrArray</link> *array);
<link linkend="void">void</link>                <link linkend="g-ptr-array-unref">g_ptr_array_unref</link>                   (<link linkend="GPtrArray">GPtrArray</link> *array);
<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 id="glib-Pointer-Arrays.description" role="desc">
<title role="desc.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 &percnt;p instead of &percnt;p\n",
             g_ptr_array_index (gparray, 0), string1);
  g_ptr_array_free (gparray, TRUE);
</programlisting></example>
</refsect1>

<refsect1 id="glib-Pointer-Arrays.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GPtrArray" role="struct">
<title>GPtrArray</title>
<indexterm zone="GPtrArray"><primary sortas="PtrArray">GPtrArray</primary></indexterm><programlisting>typedef struct {
  gpointer *pdata;
  guint	    len;
} GPtrArray;
</programlisting>
<para>
Contains the public fields of a pointer array.
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="gpointer">gpointer</link>&#160;*<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>&#160;<structfield>len</structfield>;</term>
<listitem><simpara>number of pointers in the array.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-new" role="function">
<title>g_ptr_array_new ()</title>
<indexterm zone="g-ptr-array-new"><primary sortas="ptr_array_new">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> with a reference count of 1.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the new <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-sized-new" role="function">
<title>g_ptr_array_sized_new ()</title>
<indexterm zone="g-ptr-array-sized-new"><primary sortas="ptr_array_sized_new">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 and a reference count of 1. 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>&#160;:</term>
<listitem><simpara>number of pointers preallocated.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the new <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-new-with-free-func" role="function" condition="since:2.22">
<title>g_ptr_array_new_with_free_func ()</title>
<indexterm zone="g-ptr-array-new-with-free-func" role="2.22"><primary sortas="ptr_array_new_with_free_func">g_ptr_array_new_with_free_func</primary></indexterm><programlisting><link linkend="GPtrArray">GPtrArray</link>*          g_ptr_array_new_with_free_func      (<link linkend="GDestroyNotify">GDestroyNotify</link> element_free_func);</programlisting>
<para>
Creates a new <link linkend="GPtrArray"><type>GPtrArray</type></link> with a reference count of 1 and use <parameter>element_free_func</parameter>
for freeing each element when the array is destroyed either via
<link linkend="g-ptr-array-unref"><function>g_ptr_array_unref()</function></link>, when <link linkend="g-ptr-array-free"><function>g_ptr_array_free()</function></link> is called with <parameter>free_segment</parameter>
set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> or when removing elements.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>element_free_func</parameter>&#160;:</term>
<listitem><simpara> A function to free elements with destroy <parameter>array</parameter> or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A new <link linkend="GPtrArray"><type>GPtrArray</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-ptr-array-set-free-func" role="function" condition="since:2.22">
<title>g_ptr_array_set_free_func ()</title>
<indexterm zone="g-ptr-array-set-free-func" role="2.22"><primary sortas="ptr_array_set_free_func">g_ptr_array_set_free_func</primary></indexterm><programlisting><link linkend="void">void</link>                g_ptr_array_set_free_func           (<link linkend="GPtrArray">GPtrArray</link> *array,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> element_free_func);</programlisting>
<para>
Sets a function for freeing each element when <parameter>array</parameter> is destroyed
either via <link linkend="g-ptr-array-unref"><function>g_ptr_array_unref()</function></link>, when <link linkend="g-ptr-array-free"><function>g_ptr_array_free()</function></link> is called
with <parameter>free_segment</parameter> set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> or when removing elements.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>element_free_func</parameter>&#160;:</term>
<listitem><simpara> A function to free elements with destroy <parameter>array</parameter> or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-ptr-array-ref" role="function" condition="since:2.22">
<title>g_ptr_array_ref ()</title>
<indexterm zone="g-ptr-array-ref" role="2.22"><primary sortas="ptr_array_ref">g_ptr_array_ref</primary></indexterm><programlisting><link linkend="GPtrArray">GPtrArray</link>*          g_ptr_array_ref                     (<link linkend="GPtrArray">GPtrArray</link> *array);</programlisting>
<para>
Atomically increments the reference count of <parameter>array</parameter> by one. This
function is MT-safe and may be called from any thread.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The passed in <link linkend="GPtrArray"><type>GPtrArray</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-ptr-array-unref" role="function" condition="since:2.22">
<title>g_ptr_array_unref ()</title>
<indexterm zone="g-ptr-array-unref" role="2.22"><primary sortas="ptr_array_unref">g_ptr_array_unref</primary></indexterm><programlisting><link linkend="void">void</link>                g_ptr_array_unref                   (<link linkend="GPtrArray">GPtrArray</link> *array);</programlisting>
<para>
Atomically decrements the reference count of <parameter>array</parameter> by one. If the
reference count drops to 0, the effect is the same as calling
<link linkend="g-ptr-array-free"><function>g_ptr_array_free()</function></link> with <parameter>free_segment</parameter> set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. This function
is MT-safe and may be called from any thread.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-ptr-array-add" role="function">
<title>g_ptr_array_add ()</title>
<indexterm zone="g-ptr-array-add"><primary sortas="ptr_array_add">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>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the pointer to add.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-remove" role="function">
<title>g_ptr_array_remove ()</title>
<indexterm zone="g-ptr-array-remove"><primary sortas="ptr_array_remove">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.
If <parameter>array</parameter> has a non-<link linkend="NULL--CAPS"><literal>NULL</literal></link> <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> function it is called for
the removed element.
</para>
<para>
It returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the pointer was removed, or <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the pointer
was not found.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if the pointer is removed. <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the pointer is not found
in the array.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-remove-index" role="function">
<title>g_ptr_array_remove_index ()</title>
<indexterm zone="g-ptr-array-remove-index"><primary sortas="ptr_array_remove_index">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.
If <parameter>array</parameter> has a non-<link linkend="NULL--CAPS"><literal>NULL</literal></link> <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> function it is called for
the removed element.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara>the index of the pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the pointer which was removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-remove-fast" role="function">
<title>g_ptr_array_remove_fast ()</title>
<indexterm zone="g-ptr-array-remove-fast"><primary sortas="ptr_array_remove_fast">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>.
If <parameter>array</parameter> has a non-<link linkend="NULL--CAPS"><literal>NULL</literal></link> <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> function it is called for
the removed element.
</para>
<para>
It returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the pointer was removed, or <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the pointer
was not found.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>the pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if the pointer was found in the array.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-remove-index-fast" role="function">
<title>g_ptr_array_remove_index_fast ()</title>
<indexterm zone="g-ptr-array-remove-index-fast"><primary sortas="ptr_array_remove_index_fast">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>.
If <parameter>array</parameter> has a non-<link linkend="NULL--CAPS"><literal>NULL</literal></link> <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> function it is called for
the removed element.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara>the index of the pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the pointer which was removed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-remove-range" role="function" condition="since:2.4">
<title>g_ptr_array_remove_range ()</title>
<indexterm zone="g-ptr-array-remove-range" role="2.4"><primary sortas="ptr_array_remove_range">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 pointers starting at the given index from a
<link linkend="GPtrArray"><type>GPtrArray</type></link>.  The following elements are moved to close the gap.
If <parameter>array</parameter> has a non-<link linkend="NULL--CAPS"><literal>NULL</literal></link> <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> function it is called for
the removed elements.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <parameter>GPtrArray</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara>the index of the first pointer to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>the number of pointers to remove.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-ptr-array-sort" role="function">
<title>g_ptr_array_sort ()</title>
<indexterm zone="g-ptr-array-sort"><primary sortas="ptr_array_sort">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 less than zero for first arg is less than second arg,
zero for equal, greater than zero if irst arg is greater than second arg).
</para>
<para>
If two array elements compare equal, their order in the sorted array is
undefined.
</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>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter>&#160;:</term>
<listitem><simpara>comparison function.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-sort-with-data" role="function">
<title>g_ptr_array_sort_with_data ()</title>
<indexterm zone="g-ptr-array-sort-with-data"><primary sortas="ptr_array_sort_with_data">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 an extra 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>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter>&#160;:</term>
<listitem><simpara>comparison function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>data to pass to <parameter>compare_func</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-set-size" role="function">
<title>g_ptr_array_set_size ()</title>
<indexterm zone="g-ptr-array-set-size"><primary sortas="ptr_array_set_size">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 <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>the new length of the pointer array.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-index" role="macro">
<title>g_ptr_array_index()</title>
<indexterm zone="g-ptr-array-index"><primary sortas="ptr_array_index">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>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara>the index of the pointer to return.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the pointer at the given index.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-free" role="function">
<title>g_ptr_array_free ()</title>
<indexterm zone="g-ptr-array-free"><primary sortas="ptr_array_free">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 the memory allocated for the <link linkend="GPtrArray"><type>GPtrArray</type></link>.
If <parameter>free_seg</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> it frees the memory block holding the elements
as well. Pass <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if you want to free the <link linkend="GPtrArray"><type>GPtrArray</type></link> wrapper but preserve
the underlying array for use elsewhere. If the reference count of <parameter>array</parameter>
is greater than one, the <link linkend="GPtrArray"><type>GPtrArray</type></link> wrapper is preserved but the size of
<parameter>array</parameter> will be set to zero.
</para>
<note>
<para>
If array contents point to dynamically-allocated memory, they should
be freed separately if <parameter>free_seg</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> and no <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link>
function has been set for <parameter>array</parameter>.
</para>
</note><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>free_seg</parameter>&#160;:</term>
<listitem><simpara>if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> the actual pointer array is freed as well.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the pointer array if <parameter>free_seg</parameter> is <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
	The pointer array should be freed using <link linkend="g-free"><function>g_free()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-ptr-array-foreach" role="function" condition="since:2.4">
<title>g_ptr_array_foreach ()</title>
<indexterm zone="g-ptr-array-foreach" role="2.4"><primary sortas="ptr_array_foreach">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>&#160;:</term>
<listitem><simpara> a <link linkend="GPtrArray"><type>GPtrArray</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the function to call for each array element
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> user data to pass to the function
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>

</refsect1>




</refentry>
