← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/glib2.0/jaunty-updates

« back to all changes in this revision

Viewing changes to docs/reference/glib/xml/arrays_pointer.xml

  • Committer: Bazaar Package Importer
  • Author(s): Loic Minier
  • Date: 2008-09-26 16:11:28 UTC
  • mfrom: (1.2.42 upstream) (3.1.66 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080926161128-md8d1lq4g9jr5qn1
Tags: 2.16.6-1
* New upstream stable release; bug fixes; no API changes, except you'll get
  string.h #included by some glib headers as they are relying on string.h's
  API anyway.
  - Refresh patch 60_wait-longer-for-threads-to-die to apply cleanly.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/glib/xml/arrays_pointer.xml
 
1
<refentry id="glib-Pointer-Arrays">
 
2
<refmeta>
 
3
<refentrytitle role="top_of_page" id="glib-Pointer-Arrays.top_of_page">Pointer Arrays</refentrytitle>
 
4
<manvolnum>3</manvolnum>
 
5
<refmiscinfo>GLIB Library</refmiscinfo>
 
6
</refmeta>
 
7
 
 
8
<refnamediv>
 
9
<refname>Pointer Arrays</refname>
 
10
<refpurpose>arrays of pointers to any type of data, which grow automatically as new
 
11
elements are added</refpurpose>
 
12
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
 
13
</refnamediv>
 
14
 
 
15
<refsynopsisdiv id="glib-Pointer-Arrays.synopsis" role="synopsis">
 
16
<title role="synopsis.title">Synopsis</title>
 
17
 
 
18
<synopsis>
 
19
 
 
20
#include &lt;glib.h&gt;
 
21
 
 
22
                    <link linkend="GPtrArray">GPtrArray</link>;
 
23
<link linkend="GPtrArray">GPtrArray</link>*          <link linkend="g-ptr-array-new">g_ptr_array_new</link>                     (void);
 
24
<link linkend="GPtrArray">GPtrArray</link>*          <link linkend="g-ptr-array-sized-new">g_ptr_array_sized_new</link>               (<link linkend="guint">guint</link> reserved_size);
 
25
<link linkend="void">void</link>                <link linkend="g-ptr-array-add">g_ptr_array_add</link>                     (<link linkend="GPtrArray">GPtrArray</link> *array,
 
26
                                                         <link linkend="gpointer">gpointer</link> data);
 
27
<link linkend="gboolean">gboolean</link>            <link linkend="g-ptr-array-remove">g_ptr_array_remove</link>                  (<link linkend="GPtrArray">GPtrArray</link> *array,
 
28
                                                         <link linkend="gpointer">gpointer</link> data);
 
29
<link linkend="gpointer">gpointer</link>            <link linkend="g-ptr-array-remove-index">g_ptr_array_remove_index</link>            (<link linkend="GPtrArray">GPtrArray</link> *array,
 
30
                                                         <link linkend="guint">guint</link> index_);
 
31
<link linkend="gboolean">gboolean</link>            <link linkend="g-ptr-array-remove-fast">g_ptr_array_remove_fast</link>             (<link linkend="GPtrArray">GPtrArray</link> *array,
 
32
                                                         <link linkend="gpointer">gpointer</link> data);
 
33
<link linkend="gpointer">gpointer</link>            <link linkend="g-ptr-array-remove-index-fast">g_ptr_array_remove_index_fast</link>       (<link linkend="GPtrArray">GPtrArray</link> *array,
 
34
                                                         <link linkend="guint">guint</link> index_);
 
35
<link linkend="void">void</link>                <link linkend="g-ptr-array-remove-range">g_ptr_array_remove_range</link>            (<link linkend="GPtrArray">GPtrArray</link> *array,
 
36
                                                         <link linkend="guint">guint</link> index_,
 
37
                                                         <link linkend="guint">guint</link> length);
 
38
<link linkend="void">void</link>                <link linkend="g-ptr-array-sort">g_ptr_array_sort</link>                    (<link linkend="GPtrArray">GPtrArray</link> *array,
 
39
                                                         <link linkend="GCompareFunc">GCompareFunc</link> compare_func);
 
40
<link linkend="void">void</link>                <link linkend="g-ptr-array-sort-with-data">g_ptr_array_sort_with_data</link>          (<link linkend="GPtrArray">GPtrArray</link> *array,
 
41
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
 
42
                                                         <link linkend="gpointer">gpointer</link> user_data);
 
43
<link linkend="void">void</link>                <link linkend="g-ptr-array-set-size">g_ptr_array_set_size</link>                (<link linkend="GPtrArray">GPtrArray</link> *array,
 
44
                                                         <link linkend="gint">gint</link> length);
 
45
#define             <link linkend="g-ptr-array-index">g_ptr_array_index</link>                   (array,index_)
 
46
<link linkend="gpointer">gpointer</link>*           <link linkend="g-ptr-array-free">g_ptr_array_free</link>                    (<link linkend="GPtrArray">GPtrArray</link> *array,
 
47
                                                         <link linkend="gboolean">gboolean</link> free_seg);
 
48
<link linkend="void">void</link>                <link linkend="g-ptr-array-foreach">g_ptr_array_foreach</link>                 (<link linkend="GPtrArray">GPtrArray</link> *array,
 
49
                                                         <link linkend="GFunc">GFunc</link> func,
 
50
                                                         <link linkend="gpointer">gpointer</link> user_data);
 
51
</synopsis>
 
52
</refsynopsisdiv>
 
53
 
 
54
 
 
55
 
 
56
 
 
57
 
 
58
 
 
59
 
 
60
 
 
61
 
 
62
<refsect1 id="glib-Pointer-Arrays.description" role="desc">
 
63
<title role="desc.title">Description</title>
 
64
<para>
 
65
Pointer Arrays are similar to Arrays but are used only for storing pointers.
 
66
</para>
 
67
<note>
 
68
<para>
 
69
If you remove elements from the array, elements at the end of the array
 
70
are moved into the space previously occupied by the removed element.
 
71
This means that you should not rely on the index of particular elements
 
72
remaining the same. You should also be careful when deleting elements while
 
73
iterating over the array.
 
74
</para>
 
75
</note>
 
76
<para>
 
77
To create a pointer array, use <link linkend="g-ptr-array-new"><function>g_ptr_array_new()</function></link>.
 
78
</para>
 
79
<para>
 
80
To add elements to a pointer array, use <link linkend="g-ptr-array-add"><function>g_ptr_array_add()</function></link>.
 
81
</para>
 
82
<para>
 
83
To remove elements from a pointer array, use <link linkend="g-ptr-array-remove"><function>g_ptr_array_remove()</function></link>,
 
84
<link linkend="g-ptr-array-remove-index"><function>g_ptr_array_remove_index()</function></link> or <link linkend="g-ptr-array-remove-index-fast"><function>g_ptr_array_remove_index_fast()</function></link>.
 
85
</para>
 
86
<para>
 
87
To access an element of a pointer array, use <link linkend="g-ptr-array-index"><function>g_ptr_array_index()</function></link>.
 
88
</para>
 
89
<para>
 
90
To set the size of a pointer array, use <link linkend="g-ptr-array-set-size"><function>g_ptr_array_set_size()</function></link>.
 
91
</para>
 
92
<para>
 
93
To free a pointer array, use <link linkend="g-ptr-array-free"><function>g_ptr_array_free()</function></link>.
 
94
</para>
 
95
<example>
 
96
<title>Using a <structname>GPtrArray</structname></title>
 
97
<programlisting>
 
98
  GPtrArray *gparray;
 
99
  gchar *string1 = "one", *string2 = "two", *string3 = "three";
 
100
 
 
101
  gparray = g_ptr_array_new (<!-- -->);
 
102
  g_ptr_array_add (gparray, (gpointer) string1);
 
103
  g_ptr_array_add (gparray, (gpointer) string2);
 
104
  g_ptr_array_add (gparray, (gpointer) string3);
 
105
 
 
106
  if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
 
107
    g_print ("ERROR: got &percnt;p instead of &percnt;p\n",
 
108
             g_ptr_array_index (gparray, 0), string1);
 
109
 
 
110
  g_ptr_array_free (gparray, TRUE);
 
111
</programlisting></example>
 
112
</refsect1>
 
113
 
 
114
<refsect1 id="glib-Pointer-Arrays.details" role="details">
 
115
<title role="details.title">Details</title>
 
116
<refsect2 id="GPtrArray" role="struct">
 
117
<title>GPtrArray</title>
 
118
<indexterm zone="GPtrArray"><primary>GPtrArray</primary></indexterm><programlisting>typedef struct {
 
119
  gpointer *pdata;
 
120
  guint     len;
 
121
} GPtrArray;
 
122
</programlisting>
 
123
<para>
 
124
Contains the public fields of a pointer array.
 
125
</para><variablelist role="struct">
 
126
<varlistentry>
 
127
<term><link linkend="gpointer">gpointer</link>&nbsp;*<structfield>pdata</structfield>;</term>
 
128
<listitem><simpara>points to the array of pointers, which may be moved when the array grows.
 
129
</simpara></listitem>
 
130
</varlistentry>
 
131
<varlistentry>
 
132
<term><link linkend="guint">guint</link>&nbsp;<structfield>len</structfield>;</term>
 
133
<listitem><simpara>number of pointers in the array.
 
134
 
 
135
</simpara></listitem>
 
136
</varlistentry>
 
137
</variablelist></refsect2>
 
138
<refsect2 id="g-ptr-array-new" role="function">
 
139
<title>g_ptr_array_new ()</title>
 
140
<indexterm zone="g-ptr-array-new"><primary>g_ptr_array_new</primary></indexterm><programlisting><link linkend="GPtrArray">GPtrArray</link>*          g_ptr_array_new                     (void);</programlisting>
 
141
<para>
 
142
Creates a new <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
143
</para><variablelist role="params">
 
144
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the new <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
145
 
 
146
 
 
147
</simpara></listitem></varlistentry>
 
148
</variablelist></refsect2>
 
149
<refsect2 id="g-ptr-array-sized-new" role="function">
 
150
<title>g_ptr_array_sized_new ()</title>
 
151
<indexterm zone="g-ptr-array-sized-new"><primary>g_ptr_array_sized_new</primary></indexterm><programlisting><link linkend="GPtrArray">GPtrArray</link>*          g_ptr_array_sized_new               (<link linkend="guint">guint</link> reserved_size);</programlisting>
 
152
<para>
 
153
Creates a new <link linkend="GPtrArray"><type>GPtrArray</type></link> with <parameter>reserved_size</parameter> pointers
 
154
preallocated. This avoids frequent reallocation, if you are going to
 
155
add many pointers to the array. Note however that the size of the
 
156
array is still 0.
 
157
</para><variablelist role="params">
 
158
<varlistentry><term><parameter>reserved_size</parameter>&nbsp;:</term>
 
159
<listitem><simpara>number of pointers preallocated.
 
160
</simpara></listitem></varlistentry>
 
161
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the new <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
162
 
 
163
 
 
164
</simpara></listitem></varlistentry>
 
165
</variablelist></refsect2>
 
166
<refsect2 id="g-ptr-array-add" role="function">
 
167
<title>g_ptr_array_add ()</title>
 
168
<indexterm zone="g-ptr-array-add"><primary>g_ptr_array_add</primary></indexterm><programlisting><link linkend="void">void</link>                g_ptr_array_add                     (<link linkend="GPtrArray">GPtrArray</link> *array,
 
169
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
 
170
<para>
 
171
Adds a pointer to the end of the pointer array.
 
172
The array will grow in size automatically if necessary.
 
173
</para><variablelist role="params">
 
174
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
175
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
176
</simpara></listitem></varlistentry>
 
177
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
178
<listitem><simpara>the pointer to add.
 
179
 
 
180
 
 
181
</simpara></listitem></varlistentry>
 
182
</variablelist></refsect2>
 
183
<refsect2 id="g-ptr-array-remove" role="function">
 
184
<title>g_ptr_array_remove ()</title>
 
185
<indexterm zone="g-ptr-array-remove"><primary>g_ptr_array_remove</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ptr_array_remove                  (<link linkend="GPtrArray">GPtrArray</link> *array,
 
186
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
 
187
<para>
 
188
Removes the first occurrence of the given pointer from the pointer array.
 
189
The following elements are moved down one place.
 
190
</para>
 
191
<para>
 
192
It returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the pointer was removed, or <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the pointer
 
193
was not found.
 
194
</para><variablelist role="params">
 
195
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
196
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
197
</simpara></listitem></varlistentry>
 
198
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
199
<listitem><simpara>the pointer to remove.
 
200
</simpara></listitem></varlistentry>
 
201
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the pointer is removed. <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the pointer is not found
 
202
in the array.
 
203
 
 
204
 
 
205
</simpara></listitem></varlistentry>
 
206
</variablelist></refsect2>
 
207
<refsect2 id="g-ptr-array-remove-index" role="function">
 
208
<title>g_ptr_array_remove_index ()</title>
 
209
<indexterm zone="g-ptr-array-remove-index"><primary>g_ptr_array_remove_index</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_ptr_array_remove_index            (<link linkend="GPtrArray">GPtrArray</link> *array,
 
210
                                                         <link linkend="guint">guint</link> index_);</programlisting>
 
211
<para>
 
212
Removes the pointer at the given index from the pointer array.
 
213
The following elements are moved down one place.
 
214
</para><variablelist role="params">
 
215
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
216
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
217
</simpara></listitem></varlistentry>
 
218
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
 
219
<listitem><simpara>the index of the pointer to remove.
 
220
</simpara></listitem></varlistentry>
 
221
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the pointer which was removed.
 
222
 
 
223
 
 
224
</simpara></listitem></varlistentry>
 
225
</variablelist></refsect2>
 
226
<refsect2 id="g-ptr-array-remove-fast" role="function">
 
227
<title>g_ptr_array_remove_fast ()</title>
 
228
<indexterm zone="g-ptr-array-remove-fast"><primary>g_ptr_array_remove_fast</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_ptr_array_remove_fast             (<link linkend="GPtrArray">GPtrArray</link> *array,
 
229
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
 
230
<para>
 
231
Removes the first occurrence of the given pointer from the pointer array.
 
232
The last element in the array is used to fill in the space, so this function
 
233
does not preserve the order of the array. But it is faster than
 
234
<link linkend="g-ptr-array-remove"><function>g_ptr_array_remove()</function></link>.
 
235
</para>
 
236
<para>
 
237
It returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the pointer was removed, or <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the pointer
 
238
was not found.
 
239
</para><variablelist role="params">
 
240
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
241
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
242
</simpara></listitem></varlistentry>
 
243
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
244
<listitem><simpara>the pointer to remove.
 
245
</simpara></listitem></varlistentry>
 
246
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the pointer was found in the array.
 
247
 
 
248
 
 
249
</simpara></listitem></varlistentry>
 
250
</variablelist></refsect2>
 
251
<refsect2 id="g-ptr-array-remove-index-fast" role="function">
 
252
<title>g_ptr_array_remove_index_fast ()</title>
 
253
<indexterm zone="g-ptr-array-remove-index-fast"><primary>g_ptr_array_remove_index_fast</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_ptr_array_remove_index_fast       (<link linkend="GPtrArray">GPtrArray</link> *array,
 
254
                                                         <link linkend="guint">guint</link> index_);</programlisting>
 
255
<para>
 
256
Removes the pointer at the given index from the pointer array.
 
257
The last element in the array is used to fill in the space, so this function
 
258
does not preserve the order of the array. But it is faster than
 
259
<link linkend="g-ptr-array-remove-index"><function>g_ptr_array_remove_index()</function></link>.
 
260
</para><variablelist role="params">
 
261
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
262
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
263
</simpara></listitem></varlistentry>
 
264
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
 
265
<listitem><simpara>the index of the pointer to remove.
 
266
</simpara></listitem></varlistentry>
 
267
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the pointer which was removed.
 
268
 
 
269
 
 
270
</simpara></listitem></varlistentry>
 
271
</variablelist></refsect2>
 
272
<refsect2 id="g-ptr-array-remove-range" role="function" condition="since:2.4">
 
273
<title>g_ptr_array_remove_range ()</title>
 
274
<indexterm zone="g-ptr-array-remove-range" role="2.4"><primary>g_ptr_array_remove_range</primary></indexterm><programlisting><link linkend="void">void</link>                g_ptr_array_remove_range            (<link linkend="GPtrArray">GPtrArray</link> *array,
 
275
                                                         <link linkend="guint">guint</link> index_,
 
276
                                                         <link linkend="guint">guint</link> length);</programlisting>
 
277
<para>
 
278
Removes the given number of pointers starting at the given index from a
 
279
<link linkend="GPtrArray"><type>GPtrArray</type></link>.  The following elements are moved to close the gap.
 
280
</para><variablelist role="params">
 
281
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
282
<listitem><simpara>a <parameter>GPtrArray</parameter>.
 
283
</simpara></listitem></varlistentry>
 
284
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
 
285
<listitem><simpara>the index of the first pointer to remove.
 
286
</simpara></listitem></varlistentry>
 
287
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
288
<listitem><simpara>the number of pointers to remove.
 
289
</simpara></listitem></varlistentry>
 
290
</variablelist><para role="since">Since 2.4
 
291
 
 
292
 
 
293
</para></refsect2>
 
294
<refsect2 id="g-ptr-array-sort" role="function">
 
295
<title>g_ptr_array_sort ()</title>
 
296
<indexterm zone="g-ptr-array-sort"><primary>g_ptr_array_sort</primary></indexterm><programlisting><link linkend="void">void</link>                g_ptr_array_sort                    (<link linkend="GPtrArray">GPtrArray</link> *array,
 
297
                                                         <link linkend="GCompareFunc">GCompareFunc</link> compare_func);</programlisting>
 
298
<para>
 
299
Sorts the array, using <parameter>compare_func</parameter> which should be a <link linkend="qsort"><function>qsort()</function></link>-style comparison
 
300
function (returns less than zero for first arg is less than second arg, 
 
301
zero for equal, greater than zero if irst arg is greater than second arg).
 
302
</para>
 
303
<para>
 
304
If two array elements compare equal, their order in the sorted array is
 
305
undefined.
 
306
</para>
 
307
<note><para>
 
308
The comparison function for <link linkend="g-ptr-array-sort"><function>g_ptr_array_sort()</function></link> doesn't take the pointers 
 
309
from the array as arguments, it takes pointers to the pointers in the array.
 
310
</para></note><variablelist role="params">
 
311
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
312
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
313
</simpara></listitem></varlistentry>
 
314
<varlistentry><term><parameter>compare_func</parameter>&nbsp;:</term>
 
315
<listitem><simpara>comparison function.
 
316
 
 
317
 
 
318
</simpara></listitem></varlistentry>
 
319
</variablelist></refsect2>
 
320
<refsect2 id="g-ptr-array-sort-with-data" role="function">
 
321
<title>g_ptr_array_sort_with_data ()</title>
 
322
<indexterm zone="g-ptr-array-sort-with-data"><primary>g_ptr_array_sort_with_data</primary></indexterm><programlisting><link linkend="void">void</link>                g_ptr_array_sort_with_data          (<link linkend="GPtrArray">GPtrArray</link> *array,
 
323
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
 
324
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
 
325
<para>
 
326
Like <link linkend="g-ptr-array-sort"><function>g_ptr_array_sort()</function></link>, but the comparison function has an extra user data 
 
327
argument.
 
328
</para>
 
329
<note><para>
 
330
The comparison function for <link linkend="g-ptr-array-sort-with-data"><function>g_ptr_array_sort_with_data()</function></link> doesn't take the 
 
331
pointers from the array as arguments, it takes pointers to the pointers in 
 
332
the array.
 
333
</para></note><variablelist role="params">
 
334
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
335
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
336
</simpara></listitem></varlistentry>
 
337
<varlistentry><term><parameter>compare_func</parameter>&nbsp;:</term>
 
338
<listitem><simpara>comparison function.
 
339
</simpara></listitem></varlistentry>
 
340
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
341
<listitem><simpara>data to pass to <parameter>compare_func</parameter>.
 
342
 
 
343
 
 
344
</simpara></listitem></varlistentry>
 
345
</variablelist></refsect2>
 
346
<refsect2 id="g-ptr-array-set-size" role="function">
 
347
<title>g_ptr_array_set_size ()</title>
 
348
<indexterm zone="g-ptr-array-set-size"><primary>g_ptr_array_set_size</primary></indexterm><programlisting><link linkend="void">void</link>                g_ptr_array_set_size                (<link linkend="GPtrArray">GPtrArray</link> *array,
 
349
                                                         <link linkend="gint">gint</link> length);</programlisting>
 
350
<para>
 
351
Sets the size of the array, expanding it if necessary.
 
352
New elements are set to <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
 
353
</para><variablelist role="params">
 
354
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
355
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
356
</simpara></listitem></varlistentry>
 
357
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
358
<listitem><simpara>the new length of the pointer array.
 
359
 
 
360
 
 
361
</simpara></listitem></varlistentry>
 
362
</variablelist></refsect2>
 
363
<refsect2 id="g-ptr-array-index" role="macro">
 
364
<title>g_ptr_array_index()</title>
 
365
<indexterm zone="g-ptr-array-index"><primary>g_ptr_array_index</primary></indexterm><programlisting>#define             g_ptr_array_index(array,index_)</programlisting>
 
366
<para>
 
367
Returns the pointer at the given index of the pointer array.
 
368
</para><variablelist role="params">
 
369
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
370
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
371
</simpara></listitem></varlistentry>
 
372
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
 
373
<listitem><simpara>the index of the pointer to return.
 
374
</simpara></listitem></varlistentry>
 
375
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the pointer at the given index.
 
376
 
 
377
 
 
378
</simpara></listitem></varlistentry>
 
379
</variablelist></refsect2>
 
380
<refsect2 id="g-ptr-array-free" role="function">
 
381
<title>g_ptr_array_free ()</title>
 
382
<indexterm zone="g-ptr-array-free"><primary>g_ptr_array_free</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>*           g_ptr_array_free                    (<link linkend="GPtrArray">GPtrArray</link> *array,
 
383
                                                         <link linkend="gboolean">gboolean</link> free_seg);</programlisting>
 
384
<para>
 
385
Frees the memory allocated for the <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
386
If <parameter>free_segment</parameter> is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> it frees the memory block holding the elements
 
387
as well. Pass <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if you want to free the <link linkend="GPtrArray"><type>GPtrArray</type></link> wrapper but preserve
 
388
the underlying array for use elsewhere.
 
389
</para>
 
390
<note>
 
391
<para>
 
392
If array contents point to dynamically-allocated memory, they should be freed
 
393
separately.
 
394
</para>
 
395
</note><variablelist role="params">
 
396
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
397
<listitem><simpara>a <link linkend="GPtrArray"><type>GPtrArray</type></link>.
 
398
</simpara></listitem></varlistentry>
 
399
<varlistentry><term><parameter>free_seg</parameter>&nbsp;:</term>
 
400
<listitem><simpara>if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the actual pointer array is freed as well.
 
401
</simpara></listitem></varlistentry>
 
402
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the pointer array if <parameter>free_seg</parameter> is <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, otherwise <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
 
403
        The pointer array should be freed using <link linkend="g-free"><function>g_free()</function></link>.
 
404
 
 
405
 
 
406
</simpara></listitem></varlistentry>
 
407
</variablelist></refsect2>
 
408
<refsect2 id="g-ptr-array-foreach" role="function" condition="since:2.4">
 
409
<title>g_ptr_array_foreach ()</title>
 
410
<indexterm zone="g-ptr-array-foreach" role="2.4"><primary>g_ptr_array_foreach</primary></indexterm><programlisting><link linkend="void">void</link>                g_ptr_array_foreach                 (<link linkend="GPtrArray">GPtrArray</link> *array,
 
411
                                                         <link linkend="GFunc">GFunc</link> func,
 
412
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
 
413
<para>
 
414
Calls a function for each element of a <link linkend="GPtrArray"><type>GPtrArray</type></link>.</para>
 
415
<para>
 
416
 
 
417
</para><variablelist role="params">
 
418
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
419
<listitem><simpara> a <link linkend="GPtrArray"><type>GPtrArray</type></link>
 
420
</simpara></listitem></varlistentry>
 
421
<varlistentry><term><parameter>func</parameter>&nbsp;:</term>
 
422
<listitem><simpara> the function to call for each array element
 
423
</simpara></listitem></varlistentry>
 
424
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
425
<listitem><simpara> user data to pass to the function
 
426
</simpara></listitem></varlistentry>
 
427
</variablelist><para role="since">Since  2.4
 
428
</para></refsect2>
 
429
 
 
430
</refsect1>
 
431
 
 
432
 
 
433
 
 
434
 
 
435
</refentry>