← Back to branch summary

~ubuntu-branches/debian/jessie/glib2.0/jessie

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Gustavo Noronha Silva
  • Date: 2009-02-15 13:00:43 UTC
  • mfrom: (1.3.1 upstream) (69.1.10 intrepid)
  • Revision ID: james.westby@ubuntu.com-20090215130043-q47fbt3owmt42m2f
Tags: 2.18.4-2
* Release to unstable
* debian/rules:
- bump SHVER, since we are already forcing a 2.18.0 dependecy on the
  symbols introduced in the development versions
* debian/control.in:
- added Homepage and Vcs-* control fields

Show diffs side-by-side

added added

removed removed

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