docs/reference/glib/html/glib-Pointer-Arrays.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Pointer Arrays</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-data-types.html" title="GLib Data Types">
   9 <link rel="prev" href="glib-Arrays.html" title="Arrays">
  10 <link rel="next" href="glib-Byte-Arrays.html" title="Byte Arrays">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-Arrays.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-Byte-Arrays.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-Pointer-Arrays.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Pointer-Arrays.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-Pointer-Arrays"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-Pointer-Arrays.top_of_page"></a>Pointer Arrays</span></h2>
  34 <p>Pointer Arrays — arrays of pointers to any type of data, which
  35                     grow automatically as new elements are added</p>
  36 </td>
  37 <td valign="top" align="right"></td>
  38 </tr></table></div>
  39 <div class="refsynopsisdiv">
  40 <a name="glib-Pointer-Arrays.synopsis"></a><h2>Synopsis</h2>
  41 <pre class="synopsis">
  42 #include &lt;glib.h&gt;
  43
  44 struct              <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray">GPtrArray</a>;
  45 <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-new" title="g_ptr_array_new ()">g_ptr_array_new</a>                     (<em class="parameter"><code><span class="type">void</span></code></em>);
  46 <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sized-new" title="g_ptr_array_sized_new ()">g_ptr_array_sized_new</a>               (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> reserved_size</code></em>);
  47 <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-new-with-free-func" title="g_ptr_array_new_with_free_func ()">g_ptr_array_new_with_free_func</a>      (<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> element_free_func</code></em>);
  48 <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-new-full" title="g_ptr_array_new_full ()">g_ptr_array_new_full</a>                (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> reserved_size</code></em>,
  49                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> element_free_func</code></em>);
  50 <span class="returnvalue">void</span>                <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-set-free-func" title="g_ptr_array_set_free_func ()">g_ptr_array_set_free_func</a>           (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  51                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> element_free_func</code></em>);
  52 <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-ref" title="g_ptr_array_ref ()">g_ptr_array_ref</a>                     (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>);
  53 <span class="returnvalue">void</span>                <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-unref" title="g_ptr_array_unref ()">g_ptr_array_unref</a>                   (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>);
  54 <span class="returnvalue">void</span>                <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-add" title="g_ptr_array_add ()">g_ptr_array_add</a>                     (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  55                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);
  56 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove" title="g_ptr_array_remove ()">g_ptr_array_remove</a>                  (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  57                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);
  58 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index" title="g_ptr_array_remove_index ()">g_ptr_array_remove_index</a>            (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  59                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);
  60 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-fast" title="g_ptr_array_remove_fast ()">g_ptr_array_remove_fast</a>             (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  61                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);
  62 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index-fast" title="g_ptr_array_remove_index_fast ()">g_ptr_array_remove_index_fast</a>       (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  63                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);
  64 <span class="returnvalue">void</span>                <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-range" title="g_ptr_array_remove_range ()">g_ptr_array_remove_range</a>            (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  65                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>,
  66                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> length</code></em>);
  67 <span class="returnvalue">void</span>                <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort" title="g_ptr_array_sort ()">g_ptr_array_sort</a>                    (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  68                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareFunc" title="GCompareFunc ()"><span class="type">GCompareFunc</span></a> compare_func</code></em>);
  69 <span class="returnvalue">void</span>                <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort-with-data" title="g_ptr_array_sort_with_data ()">g_ptr_array_sort_with_data</a>          (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  70                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> compare_func</code></em>,
  71                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  72 <span class="returnvalue">void</span>                <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-set-size" title="g_ptr_array_set_size ()">g_ptr_array_set_size</a>                (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  73                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> length</code></em>);
  74 #define             <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-index" title="g_ptr_array_index()">g_ptr_array_index</a>                   (array,
  75                                                          index_)
  76 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> *          <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()">g_ptr_array_free</a>                    (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  77                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> free_seg</code></em>);
  78 <span class="returnvalue">void</span>                <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-foreach" title="g_ptr_array_foreach ()">g_ptr_array_foreach</a>                 (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
  79                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GFunc" title="GFunc ()"><span class="type">GFunc</span></a> func</code></em>,
  80                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  81 </pre>
  82 </div>
  83 <div class="refsect1">
  84 <a name="glib-Pointer-Arrays.description"></a><h2>Description</h2>
  85 <p>
  86 Pointer Arrays are similar to Arrays but are used only for storing
  87 pointers.
  88 </p>
  89 <p>
  90 </p>
  91 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
  92 <h3 class="title">Note</h3>
  93 <p>If you remove elements from the array, elements at the
  94 end of the array are moved into the space previously occupied by the
  95 removed element. This means that you should not rely on the index of
  96 particular elements remaining the same. You should also be careful
  97 when deleting elements while iterating over the array.</p>
  98 </div>
  99 <p>
 100 </p>
 101 <p>
 102 To create a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-new" title="g_ptr_array_new ()"><code class="function">g_ptr_array_new()</code></a>.
 103 </p>
 104 <p>
 105 To add elements to a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-add" title="g_ptr_array_add ()"><code class="function">g_ptr_array_add()</code></a>.
 106 </p>
 107 <p>
 108 To remove elements from a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove" title="g_ptr_array_remove ()"><code class="function">g_ptr_array_remove()</code></a>,
 109 <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index" title="g_ptr_array_remove_index ()"><code class="function">g_ptr_array_remove_index()</code></a> or <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index-fast" title="g_ptr_array_remove_index_fast ()"><code class="function">g_ptr_array_remove_index_fast()</code></a>.
 110 </p>
 111 <p>
 112 To access an element of a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-index" title="g_ptr_array_index()"><code class="function">g_ptr_array_index()</code></a>.
 113 </p>
 114 <p>
 115 To set the size of a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-set-size" title="g_ptr_array_set_size ()"><code class="function">g_ptr_array_set_size()</code></a>.
 116 </p>
 117 <p>
 118 To free a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a>.
 119 </p>
 120 <p>
 121 </p>
 122 <div class="example">
 123 <a name="idp23185184"></a><p class="title"><b>Example 16. Using a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></b></p>
 124 <div class="example-contents"><pre class="programlisting">
 125   GPtrArray *gparray;
 126   gchar *string1 = "one", *string2 = "two", *string3 = "three";
 127
 128   gparray = g_ptr_array_new ();
 129   g_ptr_array_add (gparray, (gpointer) string1);
 130   g_ptr_array_add (gparray, (gpointer) string2);
 131   g_ptr_array_add (gparray, (gpointer) string3);
 132
 133   if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
 134     g_print ("ERROR: got %p instead of %p\n",
 135              g_ptr_array_index (gparray, 0), string1);
 136
 137   g_ptr_array_free (gparray, TRUE);
 138  </pre></div>
 139 </div>
 140 <p><br class="example-break">
 141 </p>
 142 </div>
 143 <div class="refsect1">
 144 <a name="glib-Pointer-Arrays.details"></a><h2>Details</h2>
 145 <div class="refsect2">
 146 <a name="GPtrArray"></a><h3>struct GPtrArray</h3>
 147 <pre class="programlisting">struct GPtrArray {
 148   gpointer *pdata;
 149   guint     len;
 150 };
 151 </pre>
 152 <p>
 153 Contains the public fields of a pointer array.
 154 </p>
 155 <div class="variablelist"><table border="0">
 156 <col align="left" valign="top">
 157 <tbody>
 158 <tr>
 159 <td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> *<em class="structfield"><code><a name="GPtrArray.pdata"></a>pdata</code></em>;</span></p></td>
 160 <td>points to the array of pointers, which may be moved when the
 161 array grows.</td>
 162 </tr>
 163 <tr>
 164 <td><p><span class="term"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> <em class="structfield"><code><a name="GPtrArray.len"></a>len</code></em>;</span></p></td>
 165 <td>number of pointers in the array.</td>
 166 </tr>
 167 </tbody>
 168 </table></div>
 169 </div>
 170 <hr>
 171 <div class="refsect2">
 172 <a name="g-ptr-array-new"></a><h3>g_ptr_array_new ()</h3>
 173 <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         g_ptr_array_new                     (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 174 <p>
 175 Creates a new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> with a reference count of 1.
 176 </p>
 177 <div class="variablelist"><table border="0">
 178 <col align="left" valign="top">
 179 <tbody><tr>
 180 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 181 <td>the new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 182 </tr></tbody>
 183 </table></div>
 184 </div>
 185 <hr>
 186 <div class="refsect2">
 187 <a name="g-ptr-array-sized-new"></a><h3>g_ptr_array_sized_new ()</h3>
 188 <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         g_ptr_array_sized_new               (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> reserved_size</code></em>);</pre>
 189 <p>
 190 Creates a new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> with <em class="parameter"><code>reserved_size</code></em> pointers preallocated
 191 and a reference count of 1. This avoids frequent reallocation, if
 192 you are going to add many pointers to the array. Note however that
 193 the size of the array is still 0.
 194 </p>
 195 <div class="variablelist"><table border="0">
 196 <col align="left" valign="top">
 197 <tbody>
 198 <tr>
 199 <td><p><span class="term"><em class="parameter"><code>reserved_size</code></em> :</span></p></td>
 200 <td>number of pointers preallocated.</td>
 201 </tr>
 202 <tr>
 203 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 204 <td>the new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 205 </tr>
 206 </tbody>
 207 </table></div>
 208 </div>
 209 <hr>
 210 <div class="refsect2">
 211 <a name="g-ptr-array-new-with-free-func"></a><h3>g_ptr_array_new_with_free_func ()</h3>
 212 <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         g_ptr_array_new_with_free_func      (<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> element_free_func</code></em>);</pre>
 213 <p>
 214 Creates a new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> with a reference count of 1 and use <em class="parameter"><code>element_free_func</code></em>
 215 for freeing each element when the array is destroyed either via
 216 <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-unref" title="g_ptr_array_unref ()"><code class="function">g_ptr_array_unref()</code></a>, when <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a> is called with <em class="parameter"><code>free_segment</code></em>
 217 set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or when removing elements.
 218 </p>
 219 <div class="variablelist"><table border="0">
 220 <col align="left" valign="top">
 221 <tbody>
 222 <tr>
 223 <td><p><span class="term"><em class="parameter"><code>element_free_func</code></em> :</span></p></td>
 224 <td>A function to free elements with destroy <em class="parameter"><code>array</code></em> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 225 </td>
 226 </tr>
 227 <tr>
 228 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 229 <td>A new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 230 </tr>
 231 </tbody>
 232 </table></div>
 233 <p class="since">Since 2.22</p>
 234 </div>
 235 <hr>
 236 <div class="refsect2">
 237 <a name="g-ptr-array-new-full"></a><h3>g_ptr_array_new_full ()</h3>
 238 <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         g_ptr_array_new_full                (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> reserved_size</code></em>,
 239                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> element_free_func</code></em>);</pre>
 240 <p>
 241 Creates a new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> with <em class="parameter"><code>reserved_size</code></em> pointers preallocated
 242 and a reference count of 1. This avoids frequent reallocation, if
 243 you are going to add many pointers to the array. Note however that
 244 the size of the array is still 0. It also set <em class="parameter"><code>element_free_func</code></em>
 245 for freeing each element when the array is destroyed either via
 246 <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-unref" title="g_ptr_array_unref ()"><code class="function">g_ptr_array_unref()</code></a>, when <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a> is called with <em class="parameter"><code>free_segment</code></em>
 247 set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or when removing elements.
 248 </p>
 249 <div class="variablelist"><table border="0">
 250 <col align="left" valign="top">
 251 <tbody>
 252 <tr>
 253 <td><p><span class="term"><em class="parameter"><code>reserved_size</code></em> :</span></p></td>
 254 <td>number of pointers preallocated.</td>
 255 </tr>
 256 <tr>
 257 <td><p><span class="term"><em class="parameter"><code>element_free_func</code></em> :</span></p></td>
 258 <td>A function to free elements with destroy <em class="parameter"><code>array</code></em> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 259 </td>
 260 </tr>
 261 <tr>
 262 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 263 <td>A new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 264 </tr>
 265 </tbody>
 266 </table></div>
 267 <p class="since">Since 2.30</p>
 268 </div>
 269 <hr>
 270 <div class="refsect2">
 271 <a name="g-ptr-array-set-free-func"></a><h3>g_ptr_array_set_free_func ()</h3>
 272 <pre class="programlisting"><span class="returnvalue">void</span>                g_ptr_array_set_free_func           (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 273                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> element_free_func</code></em>);</pre>
 274 <p>
 275 Sets a function for freeing each element when <em class="parameter"><code>array</code></em> is destroyed
 276 either via <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-unref" title="g_ptr_array_unref ()"><code class="function">g_ptr_array_unref()</code></a>, when <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a> is called
 277 with <em class="parameter"><code>free_segment</code></em> set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or when removing elements.
 278 </p>
 279 <div class="variablelist"><table border="0">
 280 <col align="left" valign="top">
 281 <tbody>
 282 <tr>
 283 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 284 <td>A <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 285 </tr>
 286 <tr>
 287 <td><p><span class="term"><em class="parameter"><code>element_free_func</code></em> :</span></p></td>
 288 <td>A function to free elements with destroy <em class="parameter"><code>array</code></em> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 289 </td>
 290 </tr>
 291 </tbody>
 292 </table></div>
 293 <p class="since">Since 2.22</p>
 294 </div>
 295 <hr>
 296 <div class="refsect2">
 297 <a name="g-ptr-array-ref"></a><h3>g_ptr_array_ref ()</h3>
 298 <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> *         g_ptr_array_ref                     (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>);</pre>
 299 <p>
 300 Atomically increments the reference count of <em class="parameter"><code>array</code></em> by one. This
 301 function is MT-safe and may be called from any thread.
 302 </p>
 303 <div class="variablelist"><table border="0">
 304 <col align="left" valign="top">
 305 <tbody>
 306 <tr>
 307 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 308 <td>A <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 309 </tr>
 310 <tr>
 311 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 312 <td>The passed in <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 313 </tr>
 314 </tbody>
 315 </table></div>
 316 <p class="since">Since 2.22</p>
 317 </div>
 318 <hr>
 319 <div class="refsect2">
 320 <a name="g-ptr-array-unref"></a><h3>g_ptr_array_unref ()</h3>
 321 <pre class="programlisting"><span class="returnvalue">void</span>                g_ptr_array_unref                   (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>);</pre>
 322 <p>
 323 Atomically decrements the reference count of <em class="parameter"><code>array</code></em> by one. If the
 324 reference count drops to 0, the effect is the same as calling
 325 <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a> with <em class="parameter"><code>free_segment</code></em> set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>. This function
 326 is MT-safe and may be called from any thread.
 327 </p>
 328 <div class="variablelist"><table border="0">
 329 <col align="left" valign="top">
 330 <tbody><tr>
 331 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 332 <td>A <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 333 </tr></tbody>
 334 </table></div>
 335 <p class="since">Since 2.22</p>
 336 </div>
 337 <hr>
 338 <div class="refsect2">
 339 <a name="g-ptr-array-add"></a><h3>g_ptr_array_add ()</h3>
 340 <pre class="programlisting"><span class="returnvalue">void</span>                g_ptr_array_add                     (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 341                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 342 <p>
 343 Adds a pointer to the end of the pointer array. The array will grow
 344 in size automatically if necessary.
 345 </p>
 346 <div class="variablelist"><table border="0">
 347 <col align="left" valign="top">
 348 <tbody>
 349 <tr>
 350 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 351 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 352 </tr>
 353 <tr>
 354 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 355 <td>the pointer to add.</td>
 356 </tr>
 357 </tbody>
 358 </table></div>
 359 </div>
 360 <hr>
 361 <div class="refsect2">
 362 <a name="g-ptr-array-remove"></a><h3>g_ptr_array_remove ()</h3>
 363 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ptr_array_remove                  (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 364                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 365 <p>
 366 Removes the first occurrence of the given pointer from the pointer
 367 array. The following elements are moved down one place. If <em class="parameter"><code>array</code></em>
 368 has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the
 369 removed element.
 370 </p>
 371 <p>
 372 It returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the pointer was removed, or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if the
 373 pointer was not found.
 374 </p>
 375 <div class="variablelist"><table border="0">
 376 <col align="left" valign="top">
 377 <tbody>
 378 <tr>
 379 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 380 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 381 </tr>
 382 <tr>
 383 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 384 <td>the pointer to remove.</td>
 385 </tr>
 386 <tr>
 387 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 388 <td>
 389 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the pointer is removed. <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if the pointer is
 390 not found in the array.</td>
 391 </tr>
 392 </tbody>
 393 </table></div>
 394 </div>
 395 <hr>
 396 <div class="refsect2">
 397 <a name="g-ptr-array-remove-index"></a><h3>g_ptr_array_remove_index ()</h3>
 398 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_ptr_array_remove_index            (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 399                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);</pre>
 400 <p>
 401 Removes the pointer at the given index from the pointer array. The
 402 following elements are moved down one place. If <em class="parameter"><code>array</code></em> has a
 403 non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed
 404 element.
 405 </p>
 406 <div class="variablelist"><table border="0">
 407 <col align="left" valign="top">
 408 <tbody>
 409 <tr>
 410 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 411 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 412 </tr>
 413 <tr>
 414 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 415 <td>the index of the pointer to remove.</td>
 416 </tr>
 417 <tr>
 418 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 419 <td>the pointer which was removed.</td>
 420 </tr>
 421 </tbody>
 422 </table></div>
 423 </div>
 424 <hr>
 425 <div class="refsect2">
 426 <a name="g-ptr-array-remove-fast"></a><h3>g_ptr_array_remove_fast ()</h3>
 427 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_ptr_array_remove_fast             (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 428                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 429 <p>
 430 Removes the first occurrence of the given pointer from the pointer
 431 array. The last element in the array is used to fill in the space,
 432 so this function does not preserve the order of the array. But it is
 433 faster than <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove" title="g_ptr_array_remove ()"><code class="function">g_ptr_array_remove()</code></a>. If <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 434 <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed element.
 435 </p>
 436 <p>
 437 It returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the pointer was removed, or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if the
 438 pointer was not found.
 439 </p>
 440 <div class="variablelist"><table border="0">
 441 <col align="left" valign="top">
 442 <tbody>
 443 <tr>
 444 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 445 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 446 </tr>
 447 <tr>
 448 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 449 <td>the pointer to remove.</td>
 450 </tr>
 451 <tr>
 452 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 453 <td>
 454 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the pointer was found in the array.</td>
 455 </tr>
 456 </tbody>
 457 </table></div>
 458 </div>
 459 <hr>
 460 <div class="refsect2">
 461 <a name="g-ptr-array-remove-index-fast"></a><h3>g_ptr_array_remove_index_fast ()</h3>
 462 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_ptr_array_remove_index_fast       (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 463                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);</pre>
 464 <p>
 465 Removes the pointer at the given index from the pointer array. The
 466 last element in the array is used to fill in the space, so this
 467 function does not preserve the order of the array. But it is faster
 468 than <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index" title="g_ptr_array_remove_index ()"><code class="function">g_ptr_array_remove_index()</code></a>. If <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 469 <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed element.
 470 </p>
 471 <div class="variablelist"><table border="0">
 472 <col align="left" valign="top">
 473 <tbody>
 474 <tr>
 475 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 476 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 477 </tr>
 478 <tr>
 479 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 480 <td>the index of the pointer to remove.</td>
 481 </tr>
 482 <tr>
 483 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 484 <td>the pointer which was removed.</td>
 485 </tr>
 486 </tbody>
 487 </table></div>
 488 </div>
 489 <hr>
 490 <div class="refsect2">
 491 <a name="g-ptr-array-remove-range"></a><h3>g_ptr_array_remove_range ()</h3>
 492 <pre class="programlisting"><span class="returnvalue">void</span>                g_ptr_array_remove_range            (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 493                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>,
 494                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> length</code></em>);</pre>
 495 <p>
 496 Removes the given number of pointers starting at the given index
 497 from a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.  The following elements are moved to close the
 498 gap. If <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called
 499 for the removed elements.
 500 </p>
 501 <div class="variablelist"><table border="0">
 502 <col align="left" valign="top">
 503 <tbody>
 504 <tr>
 505 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 506 <td>a <em class="parameter"><code>GPtrArray</code></em>.</td>
 507 </tr>
 508 <tr>
 509 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 510 <td>the index of the first pointer to remove.</td>
 511 </tr>
 512 <tr>
 513 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
 514 <td>the number of pointers to remove.</td>
 515 </tr>
 516 </tbody>
 517 </table></div>
 518 <p class="since">Since 2.4</p>
 519 </div>
 520 <hr>
 521 <div class="refsect2">
 522 <a name="g-ptr-array-sort"></a><h3>g_ptr_array_sort ()</h3>
 523 <pre class="programlisting"><span class="returnvalue">void</span>                g_ptr_array_sort                    (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 524                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareFunc" title="GCompareFunc ()"><span class="type">GCompareFunc</span></a> compare_func</code></em>);</pre>
 525 <p>
 526 Sorts the array, using <em class="parameter"><code>compare_func</code></em> which should be a <code class="function">qsort()</code>-style
 527 comparison function (returns less than zero for first arg is less
 528 than second arg, zero for equal, greater than zero if irst arg is
 529 greater than second arg).
 530 </p>
 531 <p>
 532 </p>
 533 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 534 <h3 class="title">Note</h3>
 535 <p>The comparison function for <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort" title="g_ptr_array_sort ()"><code class="function">g_ptr_array_sort()</code></a> doesn't
 536 take the pointers from the array as arguments, it takes pointers to
 537 the pointers in the array.</p>
 538 </div>
 539 <p>
 540 </p>
 541 <p>
 542 This is guaranteed to be a stable sort since version 2.32.
 543 </p>
 544 <div class="variablelist"><table border="0">
 545 <col align="left" valign="top">
 546 <tbody>
 547 <tr>
 548 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 549 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 550 </tr>
 551 <tr>
 552 <td><p><span class="term"><em class="parameter"><code>compare_func</code></em> :</span></p></td>
 553 <td>comparison function.</td>
 554 </tr>
 555 </tbody>
 556 </table></div>
 557 </div>
 558 <hr>
 559 <div class="refsect2">
 560 <a name="g-ptr-array-sort-with-data"></a><h3>g_ptr_array_sort_with_data ()</h3>
 561 <pre class="programlisting"><span class="returnvalue">void</span>                g_ptr_array_sort_with_data          (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 562                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> compare_func</code></em>,
 563                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 564 <p>
 565 Like <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort" title="g_ptr_array_sort ()"><code class="function">g_ptr_array_sort()</code></a>, but the comparison function has an extra
 566 user data argument.
 567 </p>
 568 <p>
 569 </p>
 570 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 571 <h3 class="title">Note</h3>
 572 <p>The comparison function for <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort-with-data" title="g_ptr_array_sort_with_data ()"><code class="function">g_ptr_array_sort_with_data()</code></a>
 573 doesn't take the pointers from the array as arguments, it takes
 574 pointers to the pointers in the array.</p>
 575 </div>
 576 <p>
 577 </p>
 578 <p>
 579 This is guaranteed to be a stable sort since version 2.32.
 580 </p>
 581 <div class="variablelist"><table border="0">
 582 <col align="left" valign="top">
 583 <tbody>
 584 <tr>
 585 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 586 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 587 </tr>
 588 <tr>
 589 <td><p><span class="term"><em class="parameter"><code>compare_func</code></em> :</span></p></td>
 590 <td>comparison function.</td>
 591 </tr>
 592 <tr>
 593 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 594 <td>data to pass to <em class="parameter"><code>compare_func</code></em>.</td>
 595 </tr>
 596 </tbody>
 597 </table></div>
 598 </div>
 599 <hr>
 600 <div class="refsect2">
 601 <a name="g-ptr-array-set-size"></a><h3>g_ptr_array_set_size ()</h3>
 602 <pre class="programlisting"><span class="returnvalue">void</span>                g_ptr_array_set_size                (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 603                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> length</code></em>);</pre>
 604 <p>
 605 Sets the size of the array. When making the array larger,
 606 newly-added elements will be set to <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. When making it smaller,
 607 if <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function then it will be
 608 called for the removed elements.
 609 </p>
 610 <div class="variablelist"><table border="0">
 611 <col align="left" valign="top">
 612 <tbody>
 613 <tr>
 614 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 615 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 616 </tr>
 617 <tr>
 618 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
 619 <td>the new length of the pointer array.</td>
 620 </tr>
 621 </tbody>
 622 </table></div>
 623 </div>
 624 <hr>
 625 <div class="refsect2">
 626 <a name="g-ptr-array-index"></a><h3>g_ptr_array_index()</h3>
 627 <pre class="programlisting">#define             g_ptr_array_index(array,index_)</pre>
 628 <p>
 629 Returns the pointer at the given index of the pointer array.
 630 </p>
 631 <div class="variablelist"><table border="0">
 632 <col align="left" valign="top">
 633 <tbody>
 634 <tr>
 635 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 636 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 637 </tr>
 638 <tr>
 639 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 640 <td>the index of the pointer to return.</td>
 641 </tr>
 642 <tr>
 643 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 644 <td>the pointer at the given index.</td>
 645 </tr>
 646 </tbody>
 647 </table></div>
 648 </div>
 649 <hr>
 650 <div class="refsect2">
 651 <a name="g-ptr-array-free"></a><h3>g_ptr_array_free ()</h3>
 652 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> *          g_ptr_array_free                    (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 653                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> free_seg</code></em>);</pre>
 654 <p>
 655 Frees the memory allocated for the <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>. If <em class="parameter"><code>free_seg</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>
 656 it frees the memory block holding the elements as well. Pass <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>
 657 if you want to free the <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> wrapper but preserve the
 658 underlying array for use elsewhere. If the reference count of <em class="parameter"><code>array</code></em>
 659 is greater than one, the <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> wrapper is preserved but the
 660 size of <em class="parameter"><code>array</code></em> will be set to zero.
 661 </p>
 662 <p>
 663 </p>
 664 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 665 <h3 class="title">Note</h3>
 666 <p>If array contents point to dynamically-allocated
 667 memory, they should be freed separately if <em class="parameter"><code>free_seg</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> and no
 668 <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function has been set for <em class="parameter"><code>array</code></em>.</p>
 669 </div>
 670 <p>
 671 </p>
 672 <div class="variablelist"><table border="0">
 673 <col align="left" valign="top">
 674 <tbody>
 675 <tr>
 676 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 677 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 678 </tr>
 679 <tr>
 680 <td><p><span class="term"><em class="parameter"><code>free_seg</code></em> :</span></p></td>
 681 <td>if <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> the actual pointer array is freed as well.</td>
 682 </tr>
 683 <tr>
 684 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 685 <td>the pointer array if <em class="parameter"><code>free_seg</code></em> is <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>, otherwise <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 686 The pointer array should be freed using <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.</td>
 687 </tr>
 688 </tbody>
 689 </table></div>
 690 </div>
 691 <hr>
 692 <div class="refsect2">
 693 <a name="g-ptr-array-foreach"></a><h3>g_ptr_array_foreach ()</h3>
 694 <pre class="programlisting"><span class="returnvalue">void</span>                g_ptr_array_foreach                 (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>,
 695                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GFunc" title="GFunc ()"><span class="type">GFunc</span></a> func</code></em>,
 696                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 697 <p>
 698 Calls a function for each element of a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.
 699 </p>
 700 <div class="variablelist"><table border="0">
 701 <col align="left" valign="top">
 702 <tbody>
 703 <tr>
 704 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 705 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>
 706 </td>
 707 </tr>
 708 <tr>
 709 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 710 <td>the function to call for each array element</td>
 711 </tr>
 712 <tr>
 713 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 714 <td>user data to pass to the function</td>
 715 </tr>
 716 </tbody>
 717 </table></div>
 718 <p class="since">Since 2.4</p>
 719 </div>
 720 </div>
 721 </div>
 722 <div class="footer">
 723 <hr>
 724           Generated by GTK-Doc V1.18</div>
 725 </body>
 726 </html>