docs/reference/glib/html/glib-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>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-String-Chunks.html" title="String Chunks">
  10 <link rel="next" href="glib-Pointer-Arrays.html" title="Pointer 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-String-Chunks.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-Pointer-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-Arrays.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Arrays.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-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-Arrays.top_of_page"></a>Arrays</span></h2>
  34 <p>Arrays — arrays of arbitrary elements which grow
  35                     automatically as 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-Arrays.synopsis"></a><h2>Synopsis</h2>
  41 <pre class="synopsis">
  42 #include &lt;glib.h&gt;
  43
  44 struct              <a class="link" href="glib-Arrays.html#GArray" title="struct GArray">GArray</a>;
  45 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-new" title="g_array_new ()">g_array_new</a>                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> zero_terminated</code></em>,
  46                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> clear_</code></em>,
  47                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> element_size</code></em>);
  48 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-sized-new" title="g_array_sized_new ()">g_array_sized_new</a>                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> zero_terminated</code></em>,
  49                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> clear_</code></em>,
  50                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> element_size</code></em>,
  51                                                          <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>);
  52 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-ref" title="g_array_ref ()">g_array_ref</a>                         (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>);
  53 <span class="returnvalue">void</span>                <a class="link" href="glib-Arrays.html#g-array-unref" title="g_array_unref ()">g_array_unref</a>                       (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>);
  54 <a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               <a class="link" href="glib-Arrays.html#g-array-get-element-size" title="g_array_get_element_size ()">g_array_get_element_size</a>            (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>);
  55 #define             <a class="link" href="glib-Arrays.html#g-array-append-val" title="g_array_append_val()">g_array_append_val</a>                  (a,
  56                                                          v)
  57 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-append-vals" title="g_array_append_vals ()">g_array_append_vals</a>                 (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  58                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> data</code></em>,
  59                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> len</code></em>);
  60 #define             <a class="link" href="glib-Arrays.html#g-array-prepend-val" title="g_array_prepend_val()">g_array_prepend_val</a>                 (a,
  61                                                          v)
  62 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-prepend-vals" title="g_array_prepend_vals ()">g_array_prepend_vals</a>                (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  63                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> data</code></em>,
  64                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> len</code></em>);
  65 #define             <a class="link" href="glib-Arrays.html#g-array-insert-val" title="g_array_insert_val()">g_array_insert_val</a>                  (a,
  66                                                          i,
  67                                                          v)
  68 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-insert-vals" title="g_array_insert_vals ()">g_array_insert_vals</a>                 (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  69                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>,
  70                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> data</code></em>,
  71                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> len</code></em>);
  72 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-remove-index" title="g_array_remove_index ()">g_array_remove_index</a>                (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  73                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);
  74 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-remove-index-fast" title="g_array_remove_index_fast ()">g_array_remove_index_fast</a>           (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  75                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);
  76 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-remove-range" title="g_array_remove_range ()">g_array_remove_range</a>                (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  77                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>,
  78                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> length</code></em>);
  79 <span class="returnvalue">void</span>                <a class="link" href="glib-Arrays.html#g-array-sort" title="g_array_sort ()">g_array_sort</a>                        (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  80                                                          <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>);
  81 <span class="returnvalue">void</span>                <a class="link" href="glib-Arrays.html#g-array-sort-with-data" title="g_array_sort_with_data ()">g_array_sort_with_data</a>              (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  82                                                          <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>,
  83                                                          <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>);
  84 #define             <a class="link" href="glib-Arrays.html#g-array-index" title="g_array_index()">g_array_index</a>                       (a,
  85                                                          t,
  86                                                          i)
  87 <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            <a class="link" href="glib-Arrays.html#g-array-set-size" title="g_array_set_size ()">g_array_set_size</a>                    (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  88                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> length</code></em>);
  89 <span class="returnvalue">void</span>                <a class="link" href="glib-Arrays.html#g-array-set-clear-func" title="g_array_set_clear_func ()">g_array_set_clear_func</a>              (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  90                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> clear_func</code></em>);
  91 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Arrays.html#g-array-free" title="g_array_free ()">g_array_free</a>                        (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
  92                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> free_segment</code></em>);
  93 </pre>
  94 </div>
  95 <div class="refsect1">
  96 <a name="glib-Arrays.description"></a><h2>Description</h2>
  97 <p>
  98 Arrays are similar to standard C arrays, except that they grow
  99 automatically as elements are added.
 100 </p>
 101 <p>
 102 Array elements can be of any size (though all elements of one array
 103 are the same size), and the array can be automatically cleared to
 104 '0's and zero-terminated.
 105 </p>
 106 <p>
 107 To create a new array use <a class="link" href="glib-Arrays.html#g-array-new" title="g_array_new ()"><code class="function">g_array_new()</code></a>.
 108 </p>
 109 <p>
 110 To add elements to an array, use <a class="link" href="glib-Arrays.html#g-array-append-val" title="g_array_append_val()"><code class="function">g_array_append_val()</code></a>,
 111 <a class="link" href="glib-Arrays.html#g-array-append-vals" title="g_array_append_vals ()"><code class="function">g_array_append_vals()</code></a>, <a class="link" href="glib-Arrays.html#g-array-prepend-val" title="g_array_prepend_val()"><code class="function">g_array_prepend_val()</code></a>, and
 112 <a class="link" href="glib-Arrays.html#g-array-prepend-vals" title="g_array_prepend_vals ()"><code class="function">g_array_prepend_vals()</code></a>.
 113 </p>
 114 <p>
 115 To access an element of an array, use <a class="link" href="glib-Arrays.html#g-array-index" title="g_array_index()"><code class="function">g_array_index()</code></a>.
 116 </p>
 117 <p>
 118 To set the size of an array, use <a class="link" href="glib-Arrays.html#g-array-set-size" title="g_array_set_size ()"><code class="function">g_array_set_size()</code></a>.
 119 </p>
 120 <p>
 121 To free an array, use <a class="link" href="glib-Arrays.html#g-array-free" title="g_array_free ()"><code class="function">g_array_free()</code></a>.
 122 </p>
 123 <p>
 124 </p>
 125 <div class="example">
 126 <a name="id846827"></a><p class="title"><b>Example 14. Using a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> to store <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> values</b></p>
 127 <div class="example-contents">
 128   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 129     <tbody>
 130       <tr>
 131         <td class="listing_lines" align="right"><pre>1
 132 2
 133 3
 134 4
 135 5
 136 6
 137 7
 138 8
 139 9
 140 10
 141 11
 142 12</pre></td>
 143         <td class="listing_code"><pre class="programlisting"><span class="usertype">GArray</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">garray</span><span class="symbol">;</span>
 144 <span class="usertype">gint</span><span class="normal"> i</span><span class="symbol">;</span>
 145 <span class="comment">/* We create a new array to store gint values.</span>
 146 <span class="comment">   We don't want it zero-terminated or cleared to 0's. */</span>
 147 <span class="normal">garray </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Arrays.html#g-array-new">g_array_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">,</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">,</span><span class="normal"> </span><span class="keyword">sizeof</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="glib-Basic-Types.html#gint">gint</a></span><span class="symbol">));</span>
 148 <span class="keyword">for</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">i </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span><span class="normal"> i </span><span class="symbol">&lt;</span><span class="normal"> </span><span class="number">10000</span><span class="symbol">;</span><span class="normal"> i</span><span class="symbol">++)</span>
 149 <span class="normal">  </span><span class="function"><a href="glib-Arrays.html#g-array-append-val">g_array_append_val</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">garray</span><span class="symbol">,</span><span class="normal"> i</span><span class="symbol">);</span>
 150 <span class="keyword">for</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">i </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span><span class="normal"> i </span><span class="symbol">&lt;</span><span class="normal"> </span><span class="number">10000</span><span class="symbol">;</span><span class="normal"> i</span><span class="symbol">++)</span>
 151 <span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="glib-Arrays.html#g-array-index">g_array_index</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">garray</span><span class="symbol">,</span><span class="normal"> <a href="glib-Basic-Types.html#gint">gint</a></span><span class="symbol">,</span><span class="normal"> i</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">!=</span><span class="normal"> i</span><span class="symbol">)</span>
 152 <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 %d instead of %d</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">,</span>
 153 <span class="normal">             </span><span class="function"><a href="glib-Arrays.html#g-array-index">g_array_index</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">garray</span><span class="symbol">,</span><span class="normal"> <a href="glib-Basic-Types.html#gint">gint</a></span><span class="symbol">,</span><span class="normal"> i</span><span class="symbol">),</span><span class="normal"> i</span><span class="symbol">);</span>
 154 <span class="function"><a href="glib-Arrays.html#g-array-free">g_array_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">garray</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>
 155       </tr>
 156     </tbody>
 157   </table>
 158 </div>
 159
 160 </div>
 161 <p><br class="example-break">
 162 </p>
 163 </div>
 164 <div class="refsect1">
 165 <a name="glib-Arrays.details"></a><h2>Details</h2>
 166 <div class="refsect2">
 167 <a name="GArray"></a><h3>struct GArray</h3>
 168 <pre class="programlisting">struct GArray {
 169   gchar *data;
 170   guint len;
 171 };
 172 </pre>
 173 <p>
 174 Contains the public fields of an <a class="link" href="glib-Arrays.html" title="Arrays">Array</a>.
 175 </p>
 176 <div class="variablelist"><table border="0">
 177 <col align="left" valign="top">
 178 <tbody>
 179 <tr>
 180 <td><p><span class="term"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *<em class="structfield"><code><a name="GArray.data"></a>data</code></em>;</span></p></td>
 181 <td>a pointer to the element data. The data may be moved as
 182 elements are added to the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 183 </tr>
 184 <tr>
 185 <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="GArray.len"></a>len</code></em>;</span></p></td>
 186 <td>the number of elements in the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> not including the
 187 possible terminating zero element.</td>
 188 </tr>
 189 </tbody>
 190 </table></div>
 191 </div>
 192 <hr>
 193 <div class="refsect2">
 194 <a name="g-array-new"></a><h3>g_array_new ()</h3>
 195 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_new                         (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> zero_terminated</code></em>,
 196                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> clear_</code></em>,
 197                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> element_size</code></em>);</pre>
 198 <p>
 199 Creates a new <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> with a reference count of 1.
 200 </p>
 201 <div class="variablelist"><table border="0">
 202 <col align="left" valign="top">
 203 <tbody>
 204 <tr>
 205 <td><p><span class="term"><em class="parameter"><code>zero_terminated</code></em> :</span></p></td>
 206 <td>
 207 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the array should have an extra element at
 208 the end which is set to 0.</td>
 209 </tr>
 210 <tr>
 211 <td><p><span class="term"><em class="parameter"><code>clear_</code></em> :</span></p></td>
 212 <td>
 213 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> elements should be automatically cleared
 214 to 0 when they are allocated.</td>
 215 </tr>
 216 <tr>
 217 <td><p><span class="term"><em class="parameter"><code>element_size</code></em> :</span></p></td>
 218 <td>the size of each element in bytes.</td>
 219 </tr>
 220 <tr>
 221 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 222 <td>the new <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 223 </tr>
 224 </tbody>
 225 </table></div>
 226 </div>
 227 <hr>
 228 <div class="refsect2">
 229 <a name="g-array-sized-new"></a><h3>g_array_sized_new ()</h3>
 230 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_sized_new                   (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> zero_terminated</code></em>,
 231                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> clear_</code></em>,
 232                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> element_size</code></em>,
 233                                                          <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>
 234 <p>
 235 Creates a new <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> with <em class="parameter"><code>reserved_size</code></em> elements preallocated and
 236 a reference count of 1. This avoids frequent reallocation, if you
 237 are going to add many elements to the array. Note however that the
 238 size of the array is still 0.
 239 </p>
 240 <div class="variablelist"><table border="0">
 241 <col align="left" valign="top">
 242 <tbody>
 243 <tr>
 244 <td><p><span class="term"><em class="parameter"><code>zero_terminated</code></em> :</span></p></td>
 245 <td>
 246 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the array should have an extra element at
 247 the end with all bits cleared.</td>
 248 </tr>
 249 <tr>
 250 <td><p><span class="term"><em class="parameter"><code>clear_</code></em> :</span></p></td>
 251 <td>
 252 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if all bits in the array should be cleared to 0 on
 253 allocation.</td>
 254 </tr>
 255 <tr>
 256 <td><p><span class="term"><em class="parameter"><code>element_size</code></em> :</span></p></td>
 257 <td>size of each element in the array.</td>
 258 </tr>
 259 <tr>
 260 <td><p><span class="term"><em class="parameter"><code>reserved_size</code></em> :</span></p></td>
 261 <td>number of elements preallocated.</td>
 262 </tr>
 263 <tr>
 264 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 265 <td>the new <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 266 </tr>
 267 </tbody>
 268 </table></div>
 269 </div>
 270 <hr>
 271 <div class="refsect2">
 272 <a name="g-array-ref"></a><h3>g_array_ref ()</h3>
 273 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_ref                         (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>);</pre>
 274 <p>
 275 Atomically increments the reference count of <em class="parameter"><code>array</code></em> by one. This
 276 function is MT-safe and may be called from any thread.
 277 </p>
 278 <div class="variablelist"><table border="0">
 279 <col align="left" valign="top">
 280 <tbody>
 281 <tr>
 282 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 283 <td>A <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 284 </tr>
 285 <tr>
 286 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 287 <td>The passed in <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 288 </tr>
 289 </tbody>
 290 </table></div>
 291 <p class="since">Since 2.22</p>
 292 </div>
 293 <hr>
 294 <div class="refsect2">
 295 <a name="g-array-unref"></a><h3>g_array_unref ()</h3>
 296 <pre class="programlisting"><span class="returnvalue">void</span>                g_array_unref                       (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>);</pre>
 297 <p>
 298 Atomically decrements the reference count of <em class="parameter"><code>array</code></em> by one. If the
 299 reference count drops to 0, all memory allocated by the array is
 300 released. This function is MT-safe and may be called from any
 301 thread.
 302 </p>
 303 <div class="variablelist"><table border="0">
 304 <col align="left" valign="top">
 305 <tbody><tr>
 306 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 307 <td>A <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 308 </tr></tbody>
 309 </table></div>
 310 <p class="since">Since 2.22</p>
 311 </div>
 312 <hr>
 313 <div class="refsect2">
 314 <a name="g-array-get-element-size"></a><h3>g_array_get_element_size ()</h3>
 315 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="returnvalue">guint</span></a>               g_array_get_element_size            (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>);</pre>
 316 <p>
 317 Gets the size of the elements in <em class="parameter"><code>array</code></em>.
 318 </p>
 319 <div class="variablelist"><table border="0">
 320 <col align="left" valign="top">
 321 <tbody>
 322 <tr>
 323 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 324 <td>A <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 325 </tr>
 326 <tr>
 327 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 328 <td>Size of each element, in bytes.</td>
 329 </tr>
 330 </tbody>
 331 </table></div>
 332 <p class="since">Since 2.22</p>
 333 </div>
 334 <hr>
 335 <div class="refsect2">
 336 <a name="g-array-append-val"></a><h3>g_array_append_val()</h3>
 337 <pre class="programlisting">#define             g_array_append_val(a,v)</pre>
 338 <p>
 339 Adds the value on to the end of the array. The array will grow in
 340 size automatically if necessary.
 341 </p>
 342 <p>
 343 </p>
 344 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 345 <h3 class="title">Note</h3>
 346 <p><a class="link" href="glib-Arrays.html#g-array-append-val" title="g_array_append_val()"><code class="function">g_array_append_val()</code></a> is a macro which uses a reference
 347 to the value parameter <em class="parameter"><code>v</code></em>. This means that you cannot use it with
 348 literal values such as "27". You must use variables.</p>
 349 </div>
 350 <p>
 351 </p>
 352 <div class="variablelist"><table border="0">
 353 <col align="left" valign="top">
 354 <tbody>
 355 <tr>
 356 <td><p><span class="term"><em class="parameter"><code>a</code></em> :</span></p></td>
 357 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 358 </tr>
 359 <tr>
 360 <td><p><span class="term"><em class="parameter"><code>v</code></em> :</span></p></td>
 361 <td>the value to append to the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 362 </tr>
 363 <tr>
 364 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 365 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 366 </tr>
 367 </tbody>
 368 </table></div>
 369 </div>
 370 <hr>
 371 <div class="refsect2">
 372 <a name="g-array-append-vals"></a><h3>g_array_append_vals ()</h3>
 373 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_append_vals                 (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 374                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> data</code></em>,
 375                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> len</code></em>);</pre>
 376 <p>
 377 Adds <em class="parameter"><code>len</code></em> elements onto the end of the array.
 378 </p>
 379 <div class="variablelist"><table border="0">
 380 <col align="left" valign="top">
 381 <tbody>
 382 <tr>
 383 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 384 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 385 </tr>
 386 <tr>
 387 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 388 <td>a pointer to the elements to append to the end of the array.</td>
 389 </tr>
 390 <tr>
 391 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 392 <td>the number of elements to append.</td>
 393 </tr>
 394 <tr>
 395 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 396 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 397 </tr>
 398 </tbody>
 399 </table></div>
 400 </div>
 401 <hr>
 402 <div class="refsect2">
 403 <a name="g-array-prepend-val"></a><h3>g_array_prepend_val()</h3>
 404 <pre class="programlisting">#define             g_array_prepend_val(a,v)</pre>
 405 <p>
 406 Adds the value on to the start of the array. The array will grow in
 407 size automatically if necessary.
 408 </p>
 409 <p>
 410 This operation is slower than <a class="link" href="glib-Arrays.html#g-array-append-val" title="g_array_append_val()"><code class="function">g_array_append_val()</code></a> since the
 411 existing elements in the array have to be moved to make space for
 412 the new element.
 413 </p>
 414 <p>
 415 </p>
 416 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 417 <h3 class="title">Note</h3>
 418 <p><a class="link" href="glib-Arrays.html#g-array-prepend-val" title="g_array_prepend_val()"><code class="function">g_array_prepend_val()</code></a> is a macro which uses a reference
 419 to the value parameter <em class="parameter"><code>v</code></em>. This means that you cannot use it with
 420 literal values such as "27". You must use variables.</p>
 421 </div>
 422 <p>
 423 </p>
 424 <div class="variablelist"><table border="0">
 425 <col align="left" valign="top">
 426 <tbody>
 427 <tr>
 428 <td><p><span class="term"><em class="parameter"><code>a</code></em> :</span></p></td>
 429 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 430 </tr>
 431 <tr>
 432 <td><p><span class="term"><em class="parameter"><code>v</code></em> :</span></p></td>
 433 <td>the value to prepend to the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 434 </tr>
 435 <tr>
 436 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 437 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 438 </tr>
 439 </tbody>
 440 </table></div>
 441 </div>
 442 <hr>
 443 <div class="refsect2">
 444 <a name="g-array-prepend-vals"></a><h3>g_array_prepend_vals ()</h3>
 445 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_prepend_vals                (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 446                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> data</code></em>,
 447                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> len</code></em>);</pre>
 448 <p>
 449 Adds <em class="parameter"><code>len</code></em> elements onto the start of the array.
 450 </p>
 451 <p>
 452 This operation is slower than <a class="link" href="glib-Arrays.html#g-array-append-vals" title="g_array_append_vals ()"><code class="function">g_array_append_vals()</code></a> since the
 453 existing elements in the array have to be moved to make space for
 454 the new elements.
 455 </p>
 456 <div class="variablelist"><table border="0">
 457 <col align="left" valign="top">
 458 <tbody>
 459 <tr>
 460 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 461 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 462 </tr>
 463 <tr>
 464 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 465 <td>a pointer to the elements to prepend to the start of the
 466 array.</td>
 467 </tr>
 468 <tr>
 469 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 470 <td>the number of elements to prepend.</td>
 471 </tr>
 472 <tr>
 473 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 474 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 475 </tr>
 476 </tbody>
 477 </table></div>
 478 </div>
 479 <hr>
 480 <div class="refsect2">
 481 <a name="g-array-insert-val"></a><h3>g_array_insert_val()</h3>
 482 <pre class="programlisting">#define             g_array_insert_val(a,i,v)</pre>
 483 <p>
 484 Inserts an element into an array at the given index.
 485 </p>
 486 <p>
 487 </p>
 488 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 489 <h3 class="title">Note</h3>
 490 <p><a class="link" href="glib-Arrays.html#g-array-insert-val" title="g_array_insert_val()"><code class="function">g_array_insert_val()</code></a> is a macro which uses a reference
 491 to the value parameter <em class="parameter"><code>v</code></em>. This means that you cannot use it with
 492 literal values such as "27". You must use variables.</p>
 493 </div>
 494 <p>
 495 </p>
 496 <div class="variablelist"><table border="0">
 497 <col align="left" valign="top">
 498 <tbody>
 499 <tr>
 500 <td><p><span class="term"><em class="parameter"><code>a</code></em> :</span></p></td>
 501 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 502 </tr>
 503 <tr>
 504 <td><p><span class="term"><em class="parameter"><code>i</code></em> :</span></p></td>
 505 <td>the index to place the element at.</td>
 506 </tr>
 507 <tr>
 508 <td><p><span class="term"><em class="parameter"><code>v</code></em> :</span></p></td>
 509 <td>the value to insert into the array.</td>
 510 </tr>
 511 <tr>
 512 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 513 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 514 </tr>
 515 </tbody>
 516 </table></div>
 517 </div>
 518 <hr>
 519 <div class="refsect2">
 520 <a name="g-array-insert-vals"></a><h3>g_array_insert_vals ()</h3>
 521 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_insert_vals                 (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 522                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>,
 523                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> data</code></em>,
 524                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> len</code></em>);</pre>
 525 <p>
 526 Inserts <em class="parameter"><code>len</code></em> elements into a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> at the given index.
 527 </p>
 528 <div class="variablelist"><table border="0">
 529 <col align="left" valign="top">
 530 <tbody>
 531 <tr>
 532 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 533 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 534 </tr>
 535 <tr>
 536 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 537 <td>the index to place the elements at.</td>
 538 </tr>
 539 <tr>
 540 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 541 <td>a pointer to the elements to insert.</td>
 542 </tr>
 543 <tr>
 544 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 545 <td>the number of elements to insert.</td>
 546 </tr>
 547 <tr>
 548 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 549 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 550 </tr>
 551 </tbody>
 552 </table></div>
 553 </div>
 554 <hr>
 555 <div class="refsect2">
 556 <a name="g-array-remove-index"></a><h3>g_array_remove_index ()</h3>
 557 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_remove_index                (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 558                                                          <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>
 559 <p>
 560 Removes the element at the given index from a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>. The following
 561 elements are moved down one place.
 562 </p>
 563 <div class="variablelist"><table border="0">
 564 <col align="left" valign="top">
 565 <tbody>
 566 <tr>
 567 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 568 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 569 </tr>
 570 <tr>
 571 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 572 <td>the index of the element to remove.</td>
 573 </tr>
 574 <tr>
 575 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 576 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 577 </tr>
 578 </tbody>
 579 </table></div>
 580 </div>
 581 <hr>
 582 <div class="refsect2">
 583 <a name="g-array-remove-index-fast"></a><h3>g_array_remove_index_fast ()</h3>
 584 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_remove_index_fast           (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 585                                                          <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>
 586 <p>
 587 Removes the element at the given index from a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>. The last
 588 element in the array is used to fill in the space, so this function
 589 does not preserve the order of the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>. But it is faster than
 590 <a class="link" href="glib-Arrays.html#g-array-remove-index" title="g_array_remove_index ()"><code class="function">g_array_remove_index()</code></a>.
 591 </p>
 592 <div class="variablelist"><table border="0">
 593 <col align="left" valign="top">
 594 <tbody>
 595 <tr>
 596 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 597 <td>a <em class="parameter"><code>GArray</code></em>.</td>
 598 </tr>
 599 <tr>
 600 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 601 <td>the index of the element to remove.</td>
 602 </tr>
 603 <tr>
 604 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 605 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 606 </tr>
 607 </tbody>
 608 </table></div>
 609 </div>
 610 <hr>
 611 <div class="refsect2">
 612 <a name="g-array-remove-range"></a><h3>g_array_remove_range ()</h3>
 613 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_remove_range                (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 614                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>,
 615                                                          <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>
 616 <p>
 617 Removes the given number of elements starting at the given index
 618 from a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.  The following elements are moved to close the gap.
 619 </p>
 620 <div class="variablelist"><table border="0">
 621 <col align="left" valign="top">
 622 <tbody>
 623 <tr>
 624 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 625 <td>a <em class="parameter"><code>GArray</code></em>.</td>
 626 </tr>
 627 <tr>
 628 <td><p><span class="term"><em class="parameter"><code>index_</code></em> :</span></p></td>
 629 <td>the index of the first element to remove.</td>
 630 </tr>
 631 <tr>
 632 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
 633 <td>the number of elements to remove.</td>
 634 </tr>
 635 <tr>
 636 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 637 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 638 </tr>
 639 </tbody>
 640 </table></div>
 641 <p class="since">Since 2.4</p>
 642 </div>
 643 <hr>
 644 <div class="refsect2">
 645 <a name="g-array-sort"></a><h3>g_array_sort ()</h3>
 646 <pre class="programlisting"><span class="returnvalue">void</span>                g_array_sort                        (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 647                                                          <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>
 648 <p>
 649 Sorts a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> using <em class="parameter"><code>compare_func</code></em> which should be a <code class="function">qsort()</code>-style
 650 comparison function (returns less than zero for first arg is less
 651 than second arg, zero for equal, greater zero if first arg is
 652 greater than second arg).
 653 </p>
 654 <p>
 655 If two array elements compare equal, their order in the sorted array
 656 is undefined. If you want equal elements to keep their order (i.e.
 657 you want a stable sort) you can write a comparison function that,
 658 if two elements would otherwise compare equal, compares them by
 659 their addresses.
 660 </p>
 661 <div class="variablelist"><table border="0">
 662 <col align="left" valign="top">
 663 <tbody>
 664 <tr>
 665 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 666 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 667 </tr>
 668 <tr>
 669 <td><p><span class="term"><em class="parameter"><code>compare_func</code></em> :</span></p></td>
 670 <td>comparison function.</td>
 671 </tr>
 672 </tbody>
 673 </table></div>
 674 </div>
 675 <hr>
 676 <div class="refsect2">
 677 <a name="g-array-sort-with-data"></a><h3>g_array_sort_with_data ()</h3>
 678 <pre class="programlisting"><span class="returnvalue">void</span>                g_array_sort_with_data              (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 679                                                          <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>,
 680                                                          <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>
 681 <p>
 682 Like <a class="link" href="glib-Arrays.html#g-array-sort" title="g_array_sort ()"><code class="function">g_array_sort()</code></a>, but the comparison function receives an extra
 683 user data argument.
 684 </p>
 685 <div class="variablelist"><table border="0">
 686 <col align="left" valign="top">
 687 <tbody>
 688 <tr>
 689 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 690 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 691 </tr>
 692 <tr>
 693 <td><p><span class="term"><em class="parameter"><code>compare_func</code></em> :</span></p></td>
 694 <td>comparison function.</td>
 695 </tr>
 696 <tr>
 697 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 698 <td>data to pass to <em class="parameter"><code>compare_func</code></em>.</td>
 699 </tr>
 700 </tbody>
 701 </table></div>
 702 </div>
 703 <hr>
 704 <div class="refsect2">
 705 <a name="g-array-index"></a><h3>g_array_index()</h3>
 706 <pre class="programlisting">#define             g_array_index(a,t,i)</pre>
 707 <p>
 708 Returns the element of a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> at the given index. The return
 709 value is cast to the given type.
 710 </p>
 711 <p>
 712 </p>
 713 <div class="example">
 714 <a name="id931834"></a><p class="title"><b>Example 15. Getting a pointer to an element in a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a></b></p>
 715 <div class="example-contents">
 716   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 717     <tbody>
 718       <tr>
 719         <td class="listing_lines" align="right"><pre>1
 720 2
 721 3
 722 4</pre></td>
 723         <td class="listing_code"><pre class="programlisting"><span class="usertype">EDayViewEvent</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">event</span><span class="symbol">;</span>
 724 <span class="comment">/* This gets a pointer to the 4th element</span>
 725 <span class="comment">   in the array of EDayViewEvent structs. */</span>
 726 <span class="normal">event </span><span class="symbol">=</span><span class="normal"> </span><span class="symbol">&amp;</span><span class="function"><a href="glib-Arrays.html#g-array-index">g_array_index</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">events</span><span class="symbol">,</span><span class="normal"> EDayViewEvent</span><span class="symbol">,</span><span class="normal"> </span><span class="number">3</span><span class="symbol">);</span></pre></td>
 727       </tr>
 728     </tbody>
 729   </table>
 730 </div>
 731
 732 </div>
 733 <p><br class="example-break">
 734 </p>
 735 <div class="variablelist"><table border="0">
 736 <col align="left" valign="top">
 737 <tbody>
 738 <tr>
 739 <td><p><span class="term"><em class="parameter"><code>a</code></em> :</span></p></td>
 740 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 741 </tr>
 742 <tr>
 743 <td><p><span class="term"><em class="parameter"><code>t</code></em> :</span></p></td>
 744 <td>the type of the elements.</td>
 745 </tr>
 746 <tr>
 747 <td><p><span class="term"><em class="parameter"><code>i</code></em> :</span></p></td>
 748 <td>the index of the element to return.</td>
 749 </tr>
 750 <tr>
 751 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 752 <td>the element of the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> at the index given by <em class="parameter"><code>i</code></em>.</td>
 753 </tr>
 754 </tbody>
 755 </table></div>
 756 </div>
 757 <hr>
 758 <div class="refsect2">
 759 <a name="g-array-set-size"></a><h3>g_array_set_size ()</h3>
 760 <pre class="programlisting"><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="returnvalue">GArray</span></a> *            g_array_set_size                    (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 761                                                          <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>
 762 <p>
 763 Sets the size of the array, expanding it if necessary. If the array
 764 was created with <em class="parameter"><code>clear_</code></em> set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, the new elements are set to 0.
 765 </p>
 766 <div class="variablelist"><table border="0">
 767 <col align="left" valign="top">
 768 <tbody>
 769 <tr>
 770 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 771 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 772 </tr>
 773 <tr>
 774 <td><p><span class="term"><em class="parameter"><code>length</code></em> :</span></p></td>
 775 <td>the new size of the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 776 </tr>
 777 <tr>
 778 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 779 <td>the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 780 </tr>
 781 </tbody>
 782 </table></div>
 783 </div>
 784 <hr>
 785 <div class="refsect2">
 786 <a name="g-array-set-clear-func"></a><h3>g_array_set_clear_func ()</h3>
 787 <pre class="programlisting"><span class="returnvalue">void</span>                g_array_set_clear_func              (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 788                                                          <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> clear_func</code></em>);</pre>
 789 <p>
 790 Sets a function to clear an element of <em class="parameter"><code>array</code></em>.
 791 </p>
 792 <p>
 793 The <em class="parameter"><code>clear_func</code></em> will be called when an element in the array
 794 data segment is removed and when the array is freed and data
 795 segment is deallocated as well.
 796 </p>
 797 <p>
 798 Note that in contrast with other uses of <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a>
 799 functions, <em class="parameter"><code>clear_func</code></em> is expected to clear the contents of
 800 the array element it is given, but not free the element itself.
 801 </p>
 802 <div class="variablelist"><table border="0">
 803 <col align="left" valign="top">
 804 <tbody>
 805 <tr>
 806 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 807 <td>A <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>
 808 </td>
 809 </tr>
 810 <tr>
 811 <td><p><span class="term"><em class="parameter"><code>clear_func</code></em> :</span></p></td>
 812 <td>a function to clear an element of <em class="parameter"><code>array</code></em>
 813 </td>
 814 </tr>
 815 </tbody>
 816 </table></div>
 817 <p class="since">Since 2.32</p>
 818 </div>
 819 <hr>
 820 <div class="refsect2">
 821 <a name="g-array-free"></a><h3>g_array_free ()</h3>
 822 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_array_free                        (<em class="parameter"><code><a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> *array</code></em>,
 823                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> free_segment</code></em>);</pre>
 824 <p>
 825 Frees the memory allocated for the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>. If <em class="parameter"><code>free_segment</code></em> is
 826 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> it frees the memory block holding the elements as well and
 827 also each element if <em class="parameter"><code>array</code></em> has a <em class="parameter"><code>element_free_func</code></em> set. Pass
 828 <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if you want to free the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> wrapper but preserve the
 829 underlying array for use elsewhere. If the reference count of <em class="parameter"><code>array</code></em>
 830 is greater than one, the <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a> wrapper is preserved but the size
 831 of <em class="parameter"><code>array</code></em> will be set to zero.
 832 </p>
 833 <p>
 834 </p>
 835 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 836 <h3 class="title">Note</h3>
 837 <p>If array elements contain dynamically-allocated memory,
 838 they should be freed separately.</p>
 839 </div>
 840 <p>
 841 </p>
 842 <div class="variablelist"><table border="0">
 843 <col align="left" valign="top">
 844 <tbody>
 845 <tr>
 846 <td><p><span class="term"><em class="parameter"><code>array</code></em> :</span></p></td>
 847 <td>a <a class="link" href="glib-Arrays.html#GArray" title="struct GArray"><span class="type">GArray</span></a>.</td>
 848 </tr>
 849 <tr>
 850 <td><p><span class="term"><em class="parameter"><code>free_segment</code></em> :</span></p></td>
 851 <td>if <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> the actual element data is freed as well.</td>
 852 </tr>
 853 <tr>
 854 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 855 <td>the element data if <em class="parameter"><code>free_segment</code></em> is <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>, otherwise
 856 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.  The element data 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>
 857 </tr>
 858 </tbody>
 859 </table></div>
 860 </div>
 861 </div>
 862 </div>
 863 <div class="footer">
 864 <hr>
 865           Generated by GTK-Doc V1.18</div>
 866 </body>
 867 </html>