← Back to branch summary

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

« back to all changes in this revision

Viewing changes to docs/reference/glib/xml/arrays.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.xml
1
1
<refentry id="glib-Arrays">
2
2
<refmeta>
3
 
<refentrytitle role="top_of_page">Arrays</refentrytitle>
 
3
<refentrytitle role="top_of_page" id="glib-Arrays.top_of_page">Arrays</refentrytitle>
4
4
<manvolnum>3</manvolnum>
5
5
<refmiscinfo>GLIB Library</refmiscinfo>
6
6
</refmeta>
8
8
<refnamediv>
9
9
<refname>Arrays</refname>
10
10
<refpurpose>arrays of arbitrary elements which grow automatically as elements are added</refpurpose>
11
 
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
12
11
</refnamediv>
13
12
 
14
 
<refsynopsisdiv role="synopsis">
 
13
<refsynopsisdiv id="glib-Arrays.synopsis" role="synopsis">
15
14
<title role="synopsis.title">Synopsis</title>
16
15
 
17
16
<synopsis>
18
17
 
19
18
#include &lt;glib.h&gt;
20
19
 
21
 
 
22
20
                    <link linkend="GArray">GArray</link>;
23
21
<link linkend="GArray">GArray</link>*             <link linkend="g-array-new">g_array_new</link>                         (<link linkend="gboolean">gboolean</link> zero_terminated,
24
22
                                                         <link linkend="gboolean">gboolean</link> clear_,
68
66
 
69
67
 
70
68
 
71
 
<refsect1 role="desc">
 
69
<refsect1 id="glib-Arrays.description" role="desc">
72
70
<title role="desc.title">Description</title>
73
71
<para>
74
72
Arrays are similar to standard C arrays, except that they grow automatically
100
98
<programlisting>
101
99
  GArray *garray;
102
100
  gint i;
103
 
 
104
101
  /* We create a new array to store gint values.
105
102
     We don't want it zero-terminated or cleared to 0's. */
106
103
  garray = g_array_new (FALSE, FALSE, sizeof (gint));
107
104
  for (i = 0; i &lt; 10000; i++)
108
105
    g_array_append_val (garray, i);
109
 
 
110
106
  for (i = 0; i &lt; 10000; i++)
111
107
    if (g_array_index (garray, gint, i) != i)
112
108
      g_print ("ERROR: got &percnt;d instead of &percnt;d\n",
113
109
               g_array_index (garray, gint, i), i);
114
 
 
115
110
  g_array_free (garray, TRUE);
116
111
</programlisting></example>
117
112
</refsect1>
118
113
 
119
 
<refsect1 role="details">
 
114
<refsect1 id="glib-Arrays.details" role="details">
120
115
<title role="details.title">Details</title>
121
 
<refsect2>
122
 
<title><anchor id="GArray" role="struct"/>GArray</title>
123
 
<indexterm><primary>GArray</primary></indexterm><programlisting>typedef struct {
 
116
<refsect2 id="GArray" role="struct">
 
117
<title>GArray</title>
 
118
<indexterm zone="GArray"><primary sortas="GArray">GArray</primary></indexterm><programlisting>typedef struct {
124
119
  gchar *data;
125
120
  guint len;
126
121
} GArray;
129
124
Contains the public fields of an <link linkend="glib-arrays">Array</link>.
130
125
</para><variablelist role="struct">
131
126
<varlistentry>
132
 
<term><link linkend="gchar">gchar</link>&nbsp;*<structfield>data</structfield>;</term>
 
127
<term><link linkend="gchar">gchar</link>&#160;*<structfield>data</structfield>;</term>
133
128
<listitem><simpara>a pointer to the element data. The data may be moved as elements are
134
129
added to the <link linkend="GArray"><type>GArray</type></link>.
135
130
</simpara></listitem>
136
131
</varlistentry>
137
132
<varlistentry>
138
 
<term><link linkend="guint">guint</link>&nbsp;<structfield>len</structfield>;</term>
 
133
<term><link linkend="guint">guint</link>&#160;<structfield>len</structfield>;</term>
139
134
<listitem><simpara>the number of elements in the <link linkend="GArray"><type>GArray</type></link>.
140
 
 
141
135
</simpara></listitem>
142
136
</varlistentry>
143
137
</variablelist></refsect2>
144
 
<refsect2>
145
 
<title><anchor id="g-array-new" role="function"/>g_array_new ()</title>
146
 
<indexterm><primary>g_array_new</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_new                         (<link linkend="gboolean">gboolean</link> zero_terminated,
 
138
<refsect2 id="g-array-new" role="function">
 
139
<title>g_array_new ()</title>
 
140
<indexterm zone="g-array-new"><primary sortas="g_array_new">g_array_new</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_new                         (<link linkend="gboolean">gboolean</link> zero_terminated,
147
141
                                                         <link linkend="gboolean">gboolean</link> clear_,
148
142
                                                         <link linkend="guint">guint</link> element_size);</programlisting>
149
143
<para>
150
144
Creates a new <link linkend="GArray"><type>GArray</type></link>.
151
145
</para><variablelist role="params">
152
 
<varlistentry><term><parameter>zero_terminated</parameter>&nbsp;:</term>
153
 
<listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the array should have an extra element at the end
 
146
<varlistentry><term><parameter>zero_terminated</parameter>&#160;:</term>
 
147
<listitem><simpara>%TRUE if the array should have an extra element at the end
154
148
which is set to 0.
155
149
</simpara></listitem></varlistentry>
156
 
<varlistentry><term><parameter>clear_</parameter>&nbsp;:</term>
157
 
<listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <link linkend="GArray"><type>GArray</type></link> elements should be automatically cleared to 0
 
150
<varlistentry><term><parameter>clear_</parameter>&#160;:</term>
 
151
<listitem><simpara>%TRUE if <link linkend="GArray"><type>GArray</type></link> elements should be automatically cleared to 0
158
152
when they are allocated.
159
153
</simpara></listitem></varlistentry>
160
 
<varlistentry><term><parameter>element_size</parameter>&nbsp;:</term>
 
154
<varlistentry><term><parameter>element_size</parameter>&#160;:</term>
161
155
<listitem><simpara>the size of each element in bytes.
162
156
</simpara></listitem></varlistentry>
163
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the new <link linkend="GArray"><type>GArray</type></link>.
164
 
 
165
 
 
 
157
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the new <link linkend="GArray"><type>GArray</type></link>.
166
158
</simpara></listitem></varlistentry>
167
159
</variablelist></refsect2>
168
 
<refsect2>
169
 
<title><anchor id="g-array-sized-new" role="function"/>g_array_sized_new ()</title>
170
 
<indexterm><primary>g_array_sized_new</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_sized_new                   (<link linkend="gboolean">gboolean</link> zero_terminated,
 
160
<refsect2 id="g-array-sized-new" role="function">
 
161
<title>g_array_sized_new ()</title>
 
162
<indexterm zone="g-array-sized-new"><primary sortas="g_array_sized_new">g_array_sized_new</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_sized_new                   (<link linkend="gboolean">gboolean</link> zero_terminated,
171
163
                                                         <link linkend="gboolean">gboolean</link> clear_,
172
164
                                                         <link linkend="guint">guint</link> element_size,
173
165
                                                         <link linkend="guint">guint</link> reserved_size);</programlisting>
177
169
add many elements to the array. Note however that the size of the
178
170
array is still 0.
179
171
</para><variablelist role="params">
180
 
<varlistentry><term><parameter>zero_terminated</parameter>&nbsp;:</term>
181
 
<listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the array should have an extra element at the end with all bits cleared.
182
 
</simpara></listitem></varlistentry>
183
 
<varlistentry><term><parameter>clear_</parameter>&nbsp;:</term>
184
 
<listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if all bits in the array should be cleared to 0 on allocation.
185
 
</simpara></listitem></varlistentry>
186
 
<varlistentry><term><parameter>element_size</parameter>&nbsp;:</term>
 
172
<varlistentry><term><parameter>zero_terminated</parameter>&#160;:</term>
 
173
<listitem><simpara>%TRUE if the array should have an extra element at the end with all bits cleared.
 
174
</simpara></listitem></varlistentry>
 
175
<varlistentry><term><parameter>clear_</parameter>&#160;:</term>
 
176
<listitem><simpara>%TRUE if all bits in the array should be cleared to 0 on allocation.
 
177
</simpara></listitem></varlistentry>
 
178
<varlistentry><term><parameter>element_size</parameter>&#160;:</term>
187
179
<listitem><simpara>size of each element in the array.
188
180
</simpara></listitem></varlistentry>
189
 
<varlistentry><term><parameter>reserved_size</parameter>&nbsp;:</term>
 
181
<varlistentry><term><parameter>reserved_size</parameter>&#160;:</term>
190
182
<listitem><simpara>number of elements preallocated.
191
183
</simpara></listitem></varlistentry>
192
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the new <link linkend="GArray"><type>GArray</type></link>.
193
 
 
194
 
 
 
184
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the new <link linkend="GArray"><type>GArray</type></link>.
195
185
</simpara></listitem></varlistentry>
196
186
</variablelist></refsect2>
197
 
<refsect2>
198
 
<title><anchor id="g-array-append-val" role="macro"/>g_array_append_val()</title>
199
 
<indexterm><primary>g_array_append_val</primary></indexterm><programlisting>#define             g_array_append_val(a,v)</programlisting>
 
187
<refsect2 id="g-array-append-val" role="macro">
 
188
<title>g_array_append_val()</title>
 
189
<indexterm zone="g-array-append-val"><primary sortas="g_array_append_val">g_array_append_val</primary></indexterm><programlisting>#define             g_array_append_val(a,v)</programlisting>
200
190
<para>
201
191
Adds the value on to the end of the array.
202
192
The array will grow in size automatically if necessary.
208
198
such as "27". You must use variables.
209
199
</para>
210
200
</note><variablelist role="params">
211
 
<varlistentry><term><parameter>a</parameter>&nbsp;:</term>
 
201
<varlistentry><term><parameter>a</parameter>&#160;:</term>
212
202
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
213
203
</simpara></listitem></varlistentry>
214
 
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
 
204
<varlistentry><term><parameter>v</parameter>&#160;:</term>
215
205
<listitem><simpara>the value to append to the <link linkend="GArray"><type>GArray</type></link>.
216
206
</simpara></listitem></varlistentry>
217
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
218
 
 
219
 
 
 
207
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
220
208
</simpara></listitem></varlistentry>
221
209
</variablelist></refsect2>
222
 
<refsect2>
223
 
<title><anchor id="g-array-append-vals" role="function"/>g_array_append_vals ()</title>
224
 
<indexterm><primary>g_array_append_vals</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_append_vals                 (<link linkend="GArray">GArray</link> *array,
 
210
<refsect2 id="g-array-append-vals" role="function">
 
211
<title>g_array_append_vals ()</title>
 
212
<indexterm zone="g-array-append-vals"><primary sortas="g_array_append_vals">g_array_append_vals</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_append_vals                 (<link linkend="GArray">GArray</link> *array,
225
213
                                                         <link linkend="gconstpointer">gconstpointer</link> data,
226
214
                                                         <link linkend="guint">guint</link> len);</programlisting>
227
215
<para>
228
216
Adds <parameter>len</parameter> elements onto the end of the array.
229
217
</para><variablelist role="params">
230
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
218
<varlistentry><term><parameter>array</parameter>&#160;:</term>
231
219
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
232
220
</simpara></listitem></varlistentry>
233
 
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
221
<varlistentry><term><parameter>data</parameter>&#160;:</term>
234
222
<listitem><simpara>a pointer to the elements to append to the end of the array.
235
223
</simpara></listitem></varlistentry>
236
 
<varlistentry><term><parameter>len</parameter>&nbsp;:</term>
 
224
<varlistentry><term><parameter>len</parameter>&#160;:</term>
237
225
<listitem><simpara>the number of elements to append.
238
226
</simpara></listitem></varlistentry>
239
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
240
 
 
241
 
 
 
227
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
242
228
</simpara></listitem></varlistentry>
243
229
</variablelist></refsect2>
244
 
<refsect2>
245
 
<title><anchor id="g-array-prepend-val" role="macro"/>g_array_prepend_val()</title>
246
 
<indexterm><primary>g_array_prepend_val</primary></indexterm><programlisting>#define             g_array_prepend_val(a,v)</programlisting>
 
230
<refsect2 id="g-array-prepend-val" role="macro">
 
231
<title>g_array_prepend_val()</title>
 
232
<indexterm zone="g-array-prepend-val"><primary sortas="g_array_prepend_val">g_array_prepend_val</primary></indexterm><programlisting>#define             g_array_prepend_val(a,v)</programlisting>
247
233
<para>
248
234
Adds the value on to the start of the array.
249
235
The array will grow in size automatically if necessary.
259
245
such as "27". You must use variables.
260
246
</para>
261
247
</note><variablelist role="params">
262
 
<varlistentry><term><parameter>a</parameter>&nbsp;:</term>
 
248
<varlistentry><term><parameter>a</parameter>&#160;:</term>
263
249
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
264
250
</simpara></listitem></varlistentry>
265
 
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
 
251
<varlistentry><term><parameter>v</parameter>&#160;:</term>
266
252
<listitem><simpara>the value to prepend to the <link linkend="GArray"><type>GArray</type></link>.
267
253
</simpara></listitem></varlistentry>
268
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
269
 
 
270
 
 
 
254
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
271
255
</simpara></listitem></varlistentry>
272
256
</variablelist></refsect2>
273
 
<refsect2>
274
 
<title><anchor id="g-array-prepend-vals" role="function"/>g_array_prepend_vals ()</title>
275
 
<indexterm><primary>g_array_prepend_vals</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_prepend_vals                (<link linkend="GArray">GArray</link> *array,
 
257
<refsect2 id="g-array-prepend-vals" role="function">
 
258
<title>g_array_prepend_vals ()</title>
 
259
<indexterm zone="g-array-prepend-vals"><primary sortas="g_array_prepend_vals">g_array_prepend_vals</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_prepend_vals                (<link linkend="GArray">GArray</link> *array,
276
260
                                                         <link linkend="gconstpointer">gconstpointer</link> data,
277
261
                                                         <link linkend="guint">guint</link> len);</programlisting>
278
262
<para>
282
266
This operation is slower than <link linkend="g-array-append-vals"><function>g_array_append_vals()</function></link> since the existing elements
283
267
in the array have to be moved to make space for the new elements.
284
268
</para><variablelist role="params">
285
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
269
<varlistentry><term><parameter>array</parameter>&#160;:</term>
286
270
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
287
271
</simpara></listitem></varlistentry>
288
 
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
272
<varlistentry><term><parameter>data</parameter>&#160;:</term>
289
273
<listitem><simpara>a pointer to the elements to prepend to the start of the array.
290
274
</simpara></listitem></varlistentry>
291
 
<varlistentry><term><parameter>len</parameter>&nbsp;:</term>
 
275
<varlistentry><term><parameter>len</parameter>&#160;:</term>
292
276
<listitem><simpara>the number of elements to prepend.
293
277
</simpara></listitem></varlistentry>
294
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
295
 
 
296
 
 
 
278
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
297
279
</simpara></listitem></varlistentry>
298
280
</variablelist></refsect2>
299
 
<refsect2>
300
 
<title><anchor id="g-array-insert-val" role="macro"/>g_array_insert_val()</title>
301
 
<indexterm><primary>g_array_insert_val</primary></indexterm><programlisting>#define             g_array_insert_val(a,i,v)</programlisting>
 
281
<refsect2 id="g-array-insert-val" role="macro">
 
282
<title>g_array_insert_val()</title>
 
283
<indexterm zone="g-array-insert-val"><primary sortas="g_array_insert_val">g_array_insert_val</primary></indexterm><programlisting>#define             g_array_insert_val(a,i,v)</programlisting>
302
284
<para>
303
285
Inserts an element into an array at the given index.
304
286
</para>
309
291
such as "27". You must use variables.
310
292
</para>
311
293
</note><variablelist role="params">
312
 
<varlistentry><term><parameter>a</parameter>&nbsp;:</term>
 
294
<varlistentry><term><parameter>a</parameter>&#160;:</term>
313
295
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
314
296
</simpara></listitem></varlistentry>
315
 
<varlistentry><term><parameter>i</parameter>&nbsp;:</term>
 
297
<varlistentry><term><parameter>i</parameter>&#160;:</term>
316
298
<listitem><simpara>the index to place the element at.
317
299
</simpara></listitem></varlistentry>
318
 
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
 
300
<varlistentry><term><parameter>v</parameter>&#160;:</term>
319
301
<listitem><simpara>the value to insert into the array.
320
302
</simpara></listitem></varlistentry>
321
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
322
 
 
323
 
 
 
303
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
324
304
</simpara></listitem></varlistentry>
325
305
</variablelist></refsect2>
326
 
<refsect2>
327
 
<title><anchor id="g-array-insert-vals" role="function"/>g_array_insert_vals ()</title>
328
 
<indexterm><primary>g_array_insert_vals</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_insert_vals                 (<link linkend="GArray">GArray</link> *array,
 
306
<refsect2 id="g-array-insert-vals" role="function">
 
307
<title>g_array_insert_vals ()</title>
 
308
<indexterm zone="g-array-insert-vals"><primary sortas="g_array_insert_vals">g_array_insert_vals</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_insert_vals                 (<link linkend="GArray">GArray</link> *array,
329
309
                                                         <link linkend="guint">guint</link> index_,
330
310
                                                         <link linkend="gconstpointer">gconstpointer</link> data,
331
311
                                                         <link linkend="guint">guint</link> len);</programlisting>
332
312
<para>
333
313
Inserts <parameter>len</parameter> elements into a <link linkend="GArray"><type>GArray</type></link> at the given index.
334
314
</para><variablelist role="params">
335
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
315
<varlistentry><term><parameter>array</parameter>&#160;:</term>
336
316
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
337
317
</simpara></listitem></varlistentry>
338
 
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
 
318
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
339
319
<listitem><simpara>the index to place the elements at.
340
320
</simpara></listitem></varlistentry>
341
 
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
321
<varlistentry><term><parameter>data</parameter>&#160;:</term>
342
322
<listitem><simpara>a pointer to the elements to insert.
343
323
</simpara></listitem></varlistentry>
344
 
<varlistentry><term><parameter>len</parameter>&nbsp;:</term>
 
324
<varlistentry><term><parameter>len</parameter>&#160;:</term>
345
325
<listitem><simpara>the number of elements to insert.
346
326
</simpara></listitem></varlistentry>
347
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
348
 
 
349
 
 
 
327
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
350
328
</simpara></listitem></varlistentry>
351
329
</variablelist></refsect2>
352
 
<refsect2>
353
 
<title><anchor id="g-array-remove-index" role="function"/>g_array_remove_index ()</title>
354
 
<indexterm><primary>g_array_remove_index</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_remove_index                (<link linkend="GArray">GArray</link> *array,
 
330
<refsect2 id="g-array-remove-index" role="function">
 
331
<title>g_array_remove_index ()</title>
 
332
<indexterm zone="g-array-remove-index"><primary sortas="g_array_remove_index">g_array_remove_index</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_remove_index                (<link linkend="GArray">GArray</link> *array,
355
333
                                                         <link linkend="guint">guint</link> index_);</programlisting>
356
334
<para>
357
335
Removes the element at the given index from a <link linkend="GArray"><type>GArray</type></link>.
358
336
The following elements are moved down one place.
359
337
</para><variablelist role="params">
360
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
338
<varlistentry><term><parameter>array</parameter>&#160;:</term>
361
339
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
362
340
</simpara></listitem></varlistentry>
363
 
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
 
341
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
364
342
<listitem><simpara>the index of the element to remove.
365
343
</simpara></listitem></varlistentry>
366
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
367
 
 
368
 
 
 
344
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
369
345
</simpara></listitem></varlistentry>
370
346
</variablelist></refsect2>
371
 
<refsect2>
372
 
<title><anchor id="g-array-remove-index-fast" role="function"/>g_array_remove_index_fast ()</title>
373
 
<indexterm><primary>g_array_remove_index_fast</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_remove_index_fast           (<link linkend="GArray">GArray</link> *array,
 
347
<refsect2 id="g-array-remove-index-fast" role="function">
 
348
<title>g_array_remove_index_fast ()</title>
 
349
<indexterm zone="g-array-remove-index-fast"><primary sortas="g_array_remove_index_fast">g_array_remove_index_fast</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_remove_index_fast           (<link linkend="GArray">GArray</link> *array,
374
350
                                                         <link linkend="guint">guint</link> index_);</programlisting>
375
351
<para>
376
352
Removes the element at the given index from a <link linkend="GArray"><type>GArray</type></link>.
378
354
does not preserve the order of the <link linkend="GArray"><type>GArray</type></link>. But it is faster than
379
355
<link linkend="g-array-remove-index"><function>g_array_remove_index()</function></link>.
380
356
</para><variablelist role="params">
381
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
357
<varlistentry><term><parameter>array</parameter>&#160;:</term>
382
358
<listitem><simpara>a <parameter>GArray</parameter>.
383
359
</simpara></listitem></varlistentry>
384
 
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
 
360
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
385
361
<listitem><simpara>the index of the element to remove.
386
362
</simpara></listitem></varlistentry>
387
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
388
 
 
389
 
 
 
363
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
390
364
</simpara></listitem></varlistentry>
391
365
</variablelist></refsect2>
392
 
<refsect2>
393
 
<title><anchor id="g-array-remove-range" role="function" condition="since:2.4"/>g_array_remove_range ()</title>
394
 
<indexterm role="2.4"><primary>g_array_remove_range</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_remove_range                (<link linkend="GArray">GArray</link> *array,
 
366
<refsect2 id="g-array-remove-range" role="function" condition="since:2.4">
 
367
<title>g_array_remove_range ()</title>
 
368
<indexterm zone="g-array-remove-range" role="2.4"><primary sortas="g_array_remove_range">g_array_remove_range</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_remove_range                (<link linkend="GArray">GArray</link> *array,
395
369
                                                         <link linkend="guint">guint</link> index_,
396
370
                                                         <link linkend="guint">guint</link> length);</programlisting>
397
371
<para>
398
372
Removes the given number of elements starting at the given index from a
399
373
<link linkend="GArray"><type>GArray</type></link>.  The following elements are moved to close the gap.
400
374
</para><variablelist role="params">
401
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
375
<varlistentry><term><parameter>array</parameter>&#160;:</term>
402
376
<listitem><simpara>a <parameter>GArray</parameter>.
403
377
</simpara></listitem></varlistentry>
404
 
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
 
378
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
405
379
<listitem><simpara>the index of the first element to remove.
406
380
</simpara></listitem></varlistentry>
407
 
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
381
<varlistentry><term><parameter>length</parameter>&#160;:</term>
408
382
<listitem><simpara>the number of elements to remove.
409
383
</simpara></listitem></varlistentry>
410
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
 
384
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
411
385
</simpara></listitem></varlistentry>
412
 
</variablelist><para role="since">Since 2.4
413
 
 
414
 
 
415
 
</para></refsect2>
416
 
<refsect2>
417
 
<title><anchor id="g-array-sort" role="function"/>g_array_sort ()</title>
418
 
<indexterm><primary>g_array_sort</primary></indexterm><programlisting><link linkend="void">void</link>                g_array_sort                        (<link linkend="GArray">GArray</link> *array,
 
386
</variablelist><para role="since">Since 2.4</para></refsect2>
 
387
<refsect2 id="g-array-sort" role="function">
 
388
<title>g_array_sort ()</title>
 
389
<indexterm zone="g-array-sort"><primary sortas="g_array_sort">g_array_sort</primary></indexterm><programlisting><link linkend="void">void</link>                g_array_sort                        (<link linkend="GArray">GArray</link> *array,
419
390
                                                         <link linkend="GCompareFunc">GCompareFunc</link> compare_func);</programlisting>
420
391
<para>
421
392
Sorts a <link linkend="GArray"><type>GArray</type></link> using <parameter>compare_func</parameter> which should be a <link linkend="qsort"><function>qsort()</function></link>-style comparison
422
 
function (returns less than zero for first arg is less than second arg, 
 
393
function (returns less than zero for first arg is less than second arg,
423
394
zero for equal, greater zero if first arg is greater than second arg).
424
395
</para>
425
396
<para>
426
397
If two array elements compare equal, their order in the sorted array is
427
398
undefined.
428
399
</para><variablelist role="params">
429
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
400
<varlistentry><term><parameter>array</parameter>&#160;:</term>
430
401
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
431
402
</simpara></listitem></varlistentry>
432
 
<varlistentry><term><parameter>compare_func</parameter>&nbsp;:</term>
 
403
<varlistentry><term><parameter>compare_func</parameter>&#160;:</term>
433
404
<listitem><simpara>comparison function.
434
 
 
435
 
 
436
405
</simpara></listitem></varlistentry>
437
406
</variablelist></refsect2>
438
 
<refsect2>
439
 
<title><anchor id="g-array-sort-with-data" role="function"/>g_array_sort_with_data ()</title>
440
 
<indexterm><primary>g_array_sort_with_data</primary></indexterm><programlisting><link linkend="void">void</link>                g_array_sort_with_data              (<link linkend="GArray">GArray</link> *array,
 
407
<refsect2 id="g-array-sort-with-data" role="function">
 
408
<title>g_array_sort_with_data ()</title>
 
409
<indexterm zone="g-array-sort-with-data"><primary sortas="g_array_sort_with_data">g_array_sort_with_data</primary></indexterm><programlisting><link linkend="void">void</link>                g_array_sort_with_data              (<link linkend="GArray">GArray</link> *array,
441
410
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
442
411
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
443
412
<para>
444
413
Like <link linkend="g-array-sort"><function>g_array_sort()</function></link>, but the comparison function receives an extra user data
445
414
argument.
446
415
</para><variablelist role="params">
447
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
416
<varlistentry><term><parameter>array</parameter>&#160;:</term>
448
417
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
449
418
</simpara></listitem></varlistentry>
450
 
<varlistentry><term><parameter>compare_func</parameter>&nbsp;:</term>
 
419
<varlistentry><term><parameter>compare_func</parameter>&#160;:</term>
451
420
<listitem><simpara>comparison function.
452
421
</simpara></listitem></varlistentry>
453
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
422
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
454
423
<listitem><simpara>data to pass to <parameter>compare_func</parameter>.
455
 
 
456
 
 
457
424
</simpara></listitem></varlistentry>
458
425
</variablelist></refsect2>
459
 
<refsect2>
460
 
<title><anchor id="g-array-index" role="macro"/>g_array_index()</title>
461
 
<indexterm><primary>g_array_index</primary></indexterm><programlisting>#define             g_array_index(a,t,i)</programlisting>
 
426
<refsect2 id="g-array-index" role="macro">
 
427
<title>g_array_index()</title>
 
428
<indexterm zone="g-array-index"><primary sortas="g_array_index">g_array_index</primary></indexterm><programlisting>#define             g_array_index(a,t,i)</programlisting>
462
429
<para>
463
430
Returns the element of a <link linkend="GArray"><type>GArray</type></link> at the given index.
464
431
The return value is cast to the given type.
465
 
 
466
432
<example>
467
433
<title>Getting a pointer to an element in a <structname>GArray</structname></title>
468
434
<programlisting>
469
435
  EDayViewEvent *event;
470
 
 
471
 
  /* This gets a pointer to the 3rd element in the array of EDayViewEvent
 
436
  /* This gets a pointer to the 4th element in the array of EDayViewEvent
472
437
     structs. */
473
438
  event = &amp;g_array_index (events, EDayViewEvent, 3);
474
439
</programlisting>
475
440
</example>
476
441
</para><variablelist role="params">
477
 
<varlistentry><term><parameter>a</parameter>&nbsp;:</term>
 
442
<varlistentry><term><parameter>a</parameter>&#160;:</term>
478
443
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
479
444
</simpara></listitem></varlistentry>
480
 
<varlistentry><term><parameter>t</parameter>&nbsp;:</term>
 
445
<varlistentry><term><parameter>t</parameter>&#160;:</term>
481
446
<listitem><simpara>the type of the elements.
482
447
</simpara></listitem></varlistentry>
483
 
<varlistentry><term><parameter>i</parameter>&nbsp;:</term>
 
448
<varlistentry><term><parameter>i</parameter>&#160;:</term>
484
449
<listitem><simpara>the index of the element to return.
485
450
</simpara></listitem></varlistentry>
486
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the element of the <link linkend="GArray"><type>GArray</type></link> at the index given by <parameter>i</parameter>.
487
 
 
488
 
 
 
451
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the element of the <link linkend="GArray"><type>GArray</type></link> at the index given by <parameter>i</parameter>.
489
452
</simpara></listitem></varlistentry>
490
453
</variablelist></refsect2>
491
 
<refsect2>
492
 
<title><anchor id="g-array-set-size" role="function"/>g_array_set_size ()</title>
493
 
<indexterm><primary>g_array_set_size</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_set_size                    (<link linkend="GArray">GArray</link> *array,
 
454
<refsect2 id="g-array-set-size" role="function">
 
455
<title>g_array_set_size ()</title>
 
456
<indexterm zone="g-array-set-size"><primary sortas="g_array_set_size">g_array_set_size</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_set_size                    (<link linkend="GArray">GArray</link> *array,
494
457
                                                         <link linkend="guint">guint</link> length);</programlisting>
495
458
<para>
496
459
Sets the size of the array, expanding it if necessary.
497
 
If the array was created with <parameter>clear_</parameter> set to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, the new elements are set to 0.
 
460
If the array was created with <parameter>clear_</parameter> set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, the new elements are set to 0.
498
461
</para><variablelist role="params">
499
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
462
<varlistentry><term><parameter>array</parameter>&#160;:</term>
500
463
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
501
464
</simpara></listitem></varlistentry>
502
 
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
465
<varlistentry><term><parameter>length</parameter>&#160;:</term>
503
466
<listitem><simpara>the new size of the <link linkend="GArray"><type>GArray</type></link>.
504
467
</simpara></listitem></varlistentry>
505
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
506
 
 
507
 
 
 
468
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
508
469
</simpara></listitem></varlistentry>
509
470
</variablelist></refsect2>
510
 
<refsect2>
511
 
<title><anchor id="g-array-free" role="function"/>g_array_free ()</title>
512
 
<indexterm><primary>g_array_free</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_array_free                        (<link linkend="GArray">GArray</link> *array,
 
471
<refsect2 id="g-array-free" role="function">
 
472
<title>g_array_free ()</title>
 
473
<indexterm zone="g-array-free"><primary sortas="g_array_free">g_array_free</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_array_free                        (<link linkend="GArray">GArray</link> *array,
513
474
                                                         <link linkend="gboolean">gboolean</link> free_segment);</programlisting>
514
475
<para>
515
476
Frees the memory allocated for the <link linkend="GArray"><type>GArray</type></link>.
516
 
If <parameter>free_segment</parameter> is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> it frees the memory block holding the elements
517
 
as well. Pass <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if you want to free the <link linkend="GArray"><type>GArray</type></link> wrapper but preserve
 
477
If <parameter>free_segment</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> it frees the memory block holding the elements
 
478
as well. Pass <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if you want to free the <link linkend="GArray"><type>GArray</type></link> wrapper but preserve
518
479
the underlying array for use elsewhere.
519
480
</para>
520
481
<note>
523
484
separately.
524
485
</para>
525
486
</note><variablelist role="params">
526
 
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
 
487
<varlistentry><term><parameter>array</parameter>&#160;:</term>
527
488
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
528
489
</simpara></listitem></varlistentry>
529
 
<varlistentry><term><parameter>free_segment</parameter>&nbsp;:</term>
530
 
<listitem><simpara>if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the actual element data is freed as well.
 
490
<varlistentry><term><parameter>free_segment</parameter>&#160;:</term>
 
491
<listitem><simpara>if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> the actual element data is freed as well.
531
492
</simpara></listitem></varlistentry>
532
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the element data if <parameter>free_segment</parameter> is <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, otherwise <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
 
493
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the element data if <parameter>free_segment</parameter> is <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
533
494
        The element data should be freed using <link linkend="g-free"><function>g_free()</function></link>.
534
 
 
535
 
 
536
495
</simpara></listitem></varlistentry>
537
496
</variablelist></refsect2>
538
497
 
541
500
 
542
501
 
543
502
 
544
 
 
545
 
<refsect1><refsect2 /><refsect2 /></refsect1>
546
503
</refentry>