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="id746037"></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">
 125   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 126     <tbody>
 127       <tr>
 128         <td class="listing_lines" align="right"><pre>1
 129 2
 130 3
 131 4
 132 5
 133 6
 134 7
 135 8
 136 9
 137 10
 138 11
 139 12
 140 13</pre></td>
 141         <td class="listing_code"><pre class="programlisting"><span class="usertype">GPtrArray</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">gparray</span><span class="symbol">;</span>
 142 <span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">string1 </span><span class="symbol">=</span><span class="normal"> </span><span class="string">"one"</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">string2 </span><span class="symbol">=</span><span class="normal"> </span><span class="string">"two"</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">string3 </span><span class="symbol">=</span><span class="normal"> </span><span class="string">"three"</span><span class="symbol">;</span>
 143
 144 <span class="normal">gparray </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-new">g_ptr_array_new</a></span><span class="normal"> </span><span class="symbol">();</span>
 145 <span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-add">g_ptr_array_add</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gparray</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span><span class="symbol">)</span><span class="normal"> string1</span><span class="symbol">);</span>
 146 <span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-add">g_ptr_array_add</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gparray</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span><span class="symbol">)</span><span class="normal"> string2</span><span class="symbol">);</span>
 147 <span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-add">g_ptr_array_add</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gparray</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span><span class="symbol">)</span><span class="normal"> string3</span><span class="symbol">);</span>
 148
 149 <span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-index">g_ptr_array_index</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gparray</span><span class="symbol">,</span><span class="normal"> </span><span class="number">0</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">!=</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a></span><span class="symbol">)</span><span class="normal"> string1</span><span class="symbol">)</span>
 150 <span class="normal">  </span><span class="function"><a href="glib-Warnings-and-Assertions.html#g-print">g_print</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"ERROR: got %p instead of %p</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">,</span>
 151 <span class="normal">           </span><span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-index">g_ptr_array_index</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gparray</span><span class="symbol">,</span><span class="normal"> </span><span class="number">0</span><span class="symbol">),</span><span class="normal"> string1</span><span class="symbol">);</span>
 152
 153 <span class="function"><a href="glib-Pointer-Arrays.html#g-ptr-array-free">g_ptr_array_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gparray</span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#TRUE:CAPS">TRUE</a></span><span class="symbol">);</span></pre></td>
 154       </tr>
 155     </tbody>
 156   </table>
 157 </div>
 158
 159 </div>
 160 <p><br class="example-break">
 161 </p>
 162 </div>
 163 <div class="refsect1">
 164 <a name="glib-Pointer-Arrays.details"></a><h2>Details</h2>
 165 <div class="refsect2">
 166 <a name="GPtrArray"></a><h3>struct GPtrArray</h3>
 167 <pre class="programlisting">struct GPtrArray {
 168   gpointer *pdata;
 169   guint     len;
 170 };
 171 </pre>
 172 <p>
 173 Contains the public fields of a pointer array.
 174 </p>
 175 <div class="variablelist"><table border="0">
 176 <col align="left" valign="top">
 177 <tbody>
 178 <tr>
 179 <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>
 180 <td>points to the array of pointers, which may be moved when the
 181 array grows.</td>
 182 </tr>
 183 <tr>
 184 <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>
 185 <td>number of pointers in the array.</td>
 186 </tr>
 187 </tbody>
 188 </table></div>
 189 </div>
 190 <hr>
 191 <div class="refsect2">
 192 <a name="g-ptr-array-new"></a><h3>g_ptr_array_new ()</h3>
 193 <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>
 194 <p>
 195 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.
 196 </p>
 197 <div class="variablelist"><table border="0">
 198 <col align="left" valign="top">
 199 <tbody><tr>
 200 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 201 <td>the new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 202 </tr></tbody>
 203 </table></div>
 204 </div>
 205 <hr>
 206 <div class="refsect2">
 207 <a name="g-ptr-array-sized-new"></a><h3>g_ptr_array_sized_new ()</h3>
 208 <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>
 209 <p>
 210 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
 211 and a reference count of 1. This avoids frequent reallocation, if
 212 you are going to add many pointers to the array. Note however that
 213 the size of the array is still 0.
 214 </p>
 215 <div class="variablelist"><table border="0">
 216 <col align="left" valign="top">
 217 <tbody>
 218 <tr>
 219 <td><p><span class="term"><em class="parameter"><code>reserved_size</code></em> :</span></p></td>
 220 <td>number of pointers preallocated.</td>
 221 </tr>
 222 <tr>
 223 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 224 <td>the new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 225 </tr>
 226 </tbody>
 227 </table></div>
 228 </div>
 229 <hr>
 230 <div class="refsect2">
 231 <a name="g-ptr-array-new-with-free-func"></a><h3>g_ptr_array_new_with_free_func ()</h3>
 232 <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>
 233 <p>
 234 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>
 235 for freeing each element when the array is destroyed either via
 236 <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>
 237 set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or when removing elements.
 238 </p>
 239 <div class="variablelist"><table border="0">
 240 <col align="left" valign="top">
 241 <tbody>
 242 <tr>
 243 <td><p><span class="term"><em class="parameter"><code>element_free_func</code></em> :</span></p></td>
 244 <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>
 245 </td>
 246 </tr>
 247 <tr>
 248 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 249 <td>A new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 250 </tr>
 251 </tbody>
 252 </table></div>
 253 <p class="since">Since 2.22</p>
 254 </div>
 255 <hr>
 256 <div class="refsect2">
 257 <a name="g-ptr-array-new-full"></a><h3>g_ptr_array_new_full ()</h3>
 258 <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>,
 259                                                          <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>
 260 <p>
 261 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
 262 and a reference count of 1. This avoids frequent reallocation, if
 263 you are going to add many pointers to the array. Note however that
 264 the size of the array is still 0. It also set <em class="parameter"><code>element_free_func</code></em>
 265 for freeing each element when the array is destroyed either via
 266 <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>
 267 set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or when removing elements.
 268 </p>
 269 <div class="variablelist"><table border="0">
 270 <col align="left" valign="top">
 271 <tbody>
 272 <tr>
 273 <td><p><span class="term"><em class="parameter"><code>reserved_size</code></em> :</span></p></td>
 274 <td>number of pointers preallocated.</td>
 275 </tr>
 276 <tr>
 277 <td><p><span class="term"><em class="parameter"><code>element_free_func</code></em> :</span></p></td>
 278 <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>
 279 </td>
 280 </tr>
 281 <tr>
 282 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 283 <td>A new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 284 </tr>
 285 </tbody>
 286 </table></div>
 287 <p class="since">Since 2.30</p>
 288 </div>
 289 <hr>
 290 <div class="refsect2">
 291 <a name="g-ptr-array-set-free-func"></a><h3>g_ptr_array_set_free_func ()</h3>
 292 <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>,
 293                                                          <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>
 294 <p>
 295 Sets a function for freeing each element when <em class="parameter"><code>array</code></em> is destroyed
 296 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
 297 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.
 298 </p>
 299 <div class="variablelist"><table border="0">
 300 <col align="left" valign="top">
 301 <tbody>
 302 <tr>
 303 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 304 <td>A <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 305 </tr>
 306 <tr>
 307 <td><p><span class="term"><em class="parameter"><code>element_free_func</code></em> :</span></p></td>
 308 <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>
 309 </td>
 310 </tr>
 311 </tbody>
 312 </table></div>
 313 <p class="since">Since 2.22</p>
 314 </div>
 315 <hr>
 316 <div class="refsect2">
 317 <a name="g-ptr-array-ref"></a><h3>g_ptr_array_ref ()</h3>
 318 <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>
 319 <p>
 320 Atomically increments the reference count of <em class="parameter"><code>array</code></em> by one. This
 321 function is MT-safe and may be called from any thread.
 322 </p>
 323 <div class="variablelist"><table border="0">
 324 <col align="left" valign="top">
 325 <tbody>
 326 <tr>
 327 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 328 <td>A <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 329 </tr>
 330 <tr>
 331 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 332 <td>The passed in <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 333 </tr>
 334 </tbody>
 335 </table></div>
 336 <p class="since">Since 2.22</p>
 337 </div>
 338 <hr>
 339 <div class="refsect2">
 340 <a name="g-ptr-array-unref"></a><h3>g_ptr_array_unref ()</h3>
 341 <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>
 342 <p>
 343 Atomically decrements the reference count of <em class="parameter"><code>array</code></em> by one. If the
 344 reference count drops to 0, the effect is the same as calling
 345 <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
 346 is MT-safe and may be called from any thread.
 347 </p>
 348 <div class="variablelist"><table border="0">
 349 <col align="left" valign="top">
 350 <tbody><tr>
 351 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 352 <td>A <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 353 </tr></tbody>
 354 </table></div>
 355 <p class="since">Since 2.22</p>
 356 </div>
 357 <hr>
 358 <div class="refsect2">
 359 <a name="g-ptr-array-add"></a><h3>g_ptr_array_add ()</h3>
 360 <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>,
 361                                                          <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>
 362 <p>
 363 Adds a pointer to the end of the pointer array. The array will grow
 364 in size automatically if necessary.
 365 </p>
 366 <div class="variablelist"><table border="0">
 367 <col align="left" valign="top">
 368 <tbody>
 369 <tr>
 370 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 371 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 372 </tr>
 373 <tr>
 374 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 375 <td>the pointer to add.</td>
 376 </tr>
 377 </tbody>
 378 </table></div>
 379 </div>
 380 <hr>
 381 <div class="refsect2">
 382 <a name="g-ptr-array-remove"></a><h3>g_ptr_array_remove ()</h3>
 383 <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>,
 384                                                          <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>
 385 <p>
 386 Removes the first occurrence of the given pointer from the pointer
 387 array. The following elements are moved down one place. If <em class="parameter"><code>array</code></em>
 388 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
 389 removed element.
 390 </p>
 391 <p>
 392 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
 393 pointer was not found.
 394 </p>
 395 <div class="variablelist"><table border="0">
 396 <col align="left" valign="top">
 397 <tbody>
 398 <tr>
 399 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 400 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 401 </tr>
 402 <tr>
 403 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 404 <td>the pointer to remove.</td>
 405 </tr>
 406 <tr>
 407 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 408 <td>
 409 <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
 410 not found in the array.</td>
 411 </tr>
 412 </tbody>
 413 </table></div>
 414 </div>
 415 <hr>
 416 <div class="refsect2">
 417 <a name="g-ptr-array-remove-index"></a><h3>g_ptr_array_remove_index ()</h3>
 418 <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>,
 419                                                          <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>
 420 <p>
 421 Removes the pointer at the given index from the pointer array. The
 422 following elements are moved down one place. If <em class="parameter"><code>array</code></em> has a
 423 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
 424 element.
 425 </p>
 426 <div class="variablelist"><table border="0">
 427 <col align="left" valign="top">
 428 <tbody>
 429 <tr>
 430 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 431 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 432 </tr>
 433 <tr>
 434 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 435 <td>the index of the pointer to remove.</td>
 436 </tr>
 437 <tr>
 438 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 439 <td>the pointer which was removed.</td>
 440 </tr>
 441 </tbody>
 442 </table></div>
 443 </div>
 444 <hr>
 445 <div class="refsect2">
 446 <a name="g-ptr-array-remove-fast"></a><h3>g_ptr_array_remove_fast ()</h3>
 447 <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>,
 448                                                          <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>
 449 <p>
 450 Removes the first occurrence of the given pointer from the pointer
 451 array. The last element in the array is used to fill in the space,
 452 so this function does not preserve the order of the array. But it is
 453 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>
 454 <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed element.
 455 </p>
 456 <p>
 457 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
 458 pointer was not found.
 459 </p>
 460 <div class="variablelist"><table border="0">
 461 <col align="left" valign="top">
 462 <tbody>
 463 <tr>
 464 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 465 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 466 </tr>
 467 <tr>
 468 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 469 <td>the pointer to remove.</td>
 470 </tr>
 471 <tr>
 472 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 473 <td>
 474 <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>
 475 </tr>
 476 </tbody>
 477 </table></div>
 478 </div>
 479 <hr>
 480 <div class="refsect2">
 481 <a name="g-ptr-array-remove-index-fast"></a><h3>g_ptr_array_remove_index_fast ()</h3>
 482 <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>,
 483                                                          <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>
 484 <p>
 485 Removes the pointer at the given index from the pointer array. The
 486 last element in the array is used to fill in the space, so this
 487 function does not preserve the order of the array. But it is faster
 488 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>
 489 <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed element.
 490 </p>
 491 <div class="variablelist"><table border="0">
 492 <col align="left" valign="top">
 493 <tbody>
 494 <tr>
 495 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 496 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 497 </tr>
 498 <tr>
 499 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 500 <td>the index of the pointer to remove.</td>
 501 </tr>
 502 <tr>
 503 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 504 <td>the pointer which was removed.</td>
 505 </tr>
 506 </tbody>
 507 </table></div>
 508 </div>
 509 <hr>
 510 <div class="refsect2">
 511 <a name="g-ptr-array-remove-range"></a><h3>g_ptr_array_remove_range ()</h3>
 512 <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>,
 513                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>,
 514                                                          <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>
 515 <p>
 516 Removes the given number of pointers starting at the given index
 517 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
 518 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
 519 for the removed elements.
 520 </p>
 521 <div class="variablelist"><table border="0">
 522 <col align="left" valign="top">
 523 <tbody>
 524 <tr>
 525 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 526 <td>a <em class="parameter"><code>GPtrArray</code></em>.</td>
 527 </tr>
 528 <tr>
 529 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 530 <td>the index of the first pointer to remove.</td>
 531 </tr>
 532 <tr>
 533 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
 534 <td>the number of pointers to remove.</td>
 535 </tr>
 536 </tbody>
 537 </table></div>
 538 <p class="since">Since 2.4</p>
 539 </div>
 540 <hr>
 541 <div class="refsect2">
 542 <a name="g-ptr-array-sort"></a><h3>g_ptr_array_sort ()</h3>
 543 <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>,
 544                                                          <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>
 545 <p>
 546 Sorts the array, using <em class="parameter"><code>compare_func</code></em> which should be a <code class="function">qsort()</code>-style
 547 comparison function (returns less than zero for first arg is less
 548 than second arg, zero for equal, greater than zero if irst arg is
 549 greater than second arg).
 550 </p>
 551 <p>
 552 </p>
 553 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 554 <h3 class="title">Note</h3>
 555 <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
 556 take the pointers from the array as arguments, it takes pointers to
 557 the pointers in the array.</p>
 558 </div>
 559 <p>
 560 </p>
 561 <p>
 562 This is guaranteed to be a stable sort since version 2.32.
 563 </p>
 564 <div class="variablelist"><table border="0">
 565 <col align="left" valign="top">
 566 <tbody>
 567 <tr>
 568 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 569 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 570 </tr>
 571 <tr>
 572 <td><p><span class="term"><em class="parameter"><code>compare_func</code></em> :</span></p></td>
 573 <td>comparison function.</td>
 574 </tr>
 575 </tbody>
 576 </table></div>
 577 </div>
 578 <hr>
 579 <div class="refsect2">
 580 <a name="g-ptr-array-sort-with-data"></a><h3>g_ptr_array_sort_with_data ()</h3>
 581 <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>,
 582                                                          <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>,
 583                                                          <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>
 584 <p>
 585 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
 586 user data argument.
 587 </p>
 588 <p>
 589 </p>
 590 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 591 <h3 class="title">Note</h3>
 592 <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>
 593 doesn't take the pointers from the array as arguments, it takes
 594 pointers to the pointers in the array.</p>
 595 </div>
 596 <p>
 597 </p>
 598 <p>
 599 This is guaranteed to be a stable sort since version 2.32.
 600 </p>
 601 <div class="variablelist"><table border="0">
 602 <col align="left" valign="top">
 603 <tbody>
 604 <tr>
 605 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 606 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 607 </tr>
 608 <tr>
 609 <td><p><span class="term"><em class="parameter"><code>compare_func</code></em> :</span></p></td>
 610 <td>comparison function.</td>
 611 </tr>
 612 <tr>
 613 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 614 <td>data to pass to <em class="parameter"><code>compare_func</code></em>.</td>
 615 </tr>
 616 </tbody>
 617 </table></div>
 618 </div>
 619 <hr>
 620 <div class="refsect2">
 621 <a name="g-ptr-array-set-size"></a><h3>g_ptr_array_set_size ()</h3>
 622 <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>,
 623                                                          <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>
 624 <p>
 625 Sets the size of the array. When making the array larger,
 626 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,
 627 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
 628 called for the removed elements.
 629 </p>
 630 <div class="variablelist"><table border="0">
 631 <col align="left" valign="top">
 632 <tbody>
 633 <tr>
 634 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 635 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 636 </tr>
 637 <tr>
 638 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
 639 <td>the new length of the pointer array.</td>
 640 </tr>
 641 </tbody>
 642 </table></div>
 643 </div>
 644 <hr>
 645 <div class="refsect2">
 646 <a name="g-ptr-array-index"></a><h3>g_ptr_array_index()</h3>
 647 <pre class="programlisting">#define             g_ptr_array_index(array,index_)</pre>
 648 <p>
 649 Returns the pointer at the given index of the pointer array.
 650 </p>
 651 <div class="variablelist"><table border="0">
 652 <col align="left" valign="top">
 653 <tbody>
 654 <tr>
 655 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 656 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 657 </tr>
 658 <tr>
 659 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 660 <td>the index of the pointer to return.</td>
 661 </tr>
 662 <tr>
 663 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 664 <td>the pointer at the given index.</td>
 665 </tr>
 666 </tbody>
 667 </table></div>
 668 </div>
 669 <hr>
 670 <div class="refsect2">
 671 <a name="g-ptr-array-free"></a><h3>g_ptr_array_free ()</h3>
 672 <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>,
 673                                                          <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>
 674 <p>
 675 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>
 676 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>
 677 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
 678 underlying array for use elsewhere. If the reference count of <em class="parameter"><code>array</code></em>
 679 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
 680 size of <em class="parameter"><code>array</code></em> will be set to zero.
 681 </p>
 682 <p>
 683 </p>
 684 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 685 <h3 class="title">Note</h3>
 686 <p>If array contents point to dynamically-allocated
 687 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
 688 <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>
 689 </div>
 690 <p>
 691 </p>
 692 <div class="variablelist"><table border="0">
 693 <col align="left" valign="top">
 694 <tbody>
 695 <tr>
 696 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 697 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</td>
 698 </tr>
 699 <tr>
 700 <td><p><span class="term"><em class="parameter"><code>free_seg</code></em> :</span></p></td>
 701 <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>
 702 </tr>
 703 <tr>
 704 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 705 <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>.
 706 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>
 707 </tr>
 708 </tbody>
 709 </table></div>
 710 </div>
 711 <hr>
 712 <div class="refsect2">
 713 <a name="g-ptr-array-foreach"></a><h3>g_ptr_array_foreach ()</h3>
 714 <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>,
 715                                                          <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>,
 716                                                          <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>
 717 <p>
 718 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>.
 719 </p>
 720 <div class="variablelist"><table border="0">
 721 <col align="left" valign="top">
 722 <tbody>
 723 <tr>
 724 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 725 <td>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>
 726 </td>
 727 </tr>
 728 <tr>
 729 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 730 <td>the function to call for each array element</td>
 731 </tr>
 732 <tr>
 733 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 734 <td>user data to pass to the function</td>
 735 </tr>
 736 </tbody>
 737 </table></div>
 738 <p class="since">Since 2.4</p>
 739 </div>
 740 </div>
 741 </div>
 742 <div class="footer">
 743 <hr>
 744           Generated by GTK-Doc V1.18</div>
 745 </body>
 746 </html>