1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 2001 Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17 * Boston, MA 02111-1307, USA.
27 #include <stdlib.h> /* qsort() */
29 #include "gvaluearray.h"
33 * SECTION:value_arrays
34 * @short_description: A container structure to maintain an array of
36 * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array()
37 * @title: Value arrays
39 * The prime purpose of a #GValueArray is for it to be used as an
40 * object property that holds an array of values. A #GValueArray wraps
41 * an array of #GValue elements in order for it to be used as a boxed
42 * type through %G_TYPE_VALUE_ARRAY.
44 * #GValueArray is deprecated in favour of #GArray since GLib 2.32. It
45 * is possible to create a #GArray that behaves like a #GValueArray by
46 * using the size of #GValue as the element size, and by setting
47 * g_value_unset() as the clear function using g_array_set_clear_func(),
48 * for instance, the following code:
51 * GValueArray *array = g_value_array_new (10);
57 * GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
58 * g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
63 #ifdef DISABLE_MEM_POOLS
64 # define GROUP_N_VALUES (1) /* power of 2 !! */
66 # define GROUP_N_VALUES (8) /* power of 2 !! */
70 /* --- functions --- */
72 * g_value_array_get_nth:
73 * @value_array: #GValueArray to get a value from
74 * @index_: index of the value of interest
76 * Return a pointer to the value at @index_ containd in @value_array.
78 * Returns: (transfer none): pointer to a value at @index_ in @value_array
80 * Deprecated: 2.32: Use g_array_index() instead.
83 g_value_array_get_nth (GValueArray
*value_array
,
86 g_return_val_if_fail (value_array
!= NULL
, NULL
);
87 g_return_val_if_fail (index
< value_array
->n_values
, NULL
);
89 return value_array
->values
+ index
;
93 value_array_grow (GValueArray
*value_array
,
97 g_return_if_fail (n_values
>= value_array
->n_values
);
99 value_array
->n_values
= n_values
;
100 if (value_array
->n_values
> value_array
->n_prealloced
)
102 guint i
= value_array
->n_prealloced
;
104 value_array
->n_prealloced
= (value_array
->n_values
+ GROUP_N_VALUES
- 1) & ~(GROUP_N_VALUES
- 1);
105 value_array
->values
= g_renew (GValue
, value_array
->values
, value_array
->n_prealloced
);
107 i
= value_array
->n_values
;
108 memset (value_array
->values
+ i
, 0,
109 (value_array
->n_prealloced
- i
) * sizeof (value_array
->values
[0]));
114 value_array_shrink (GValueArray
*value_array
)
116 #ifdef DISABLE_MEM_POOLS
117 if (value_array
->n_prealloced
>= value_array
->n_values
+ GROUP_N_VALUES
)
119 value_array
->n_prealloced
= (value_array
->n_values
+ GROUP_N_VALUES
- 1) & ~(GROUP_N_VALUES
- 1);
120 value_array
->values
= g_renew (GValue
, value_array
->values
, value_array
->n_prealloced
);
127 * @n_prealloced: number of values to preallocate space for
129 * Allocate and initialize a new #GValueArray, optionally preserve space
130 * for @n_prealloced elements. New arrays always contain 0 elements,
131 * regardless of the value of @n_prealloced.
133 * Returns: a newly allocated #GValueArray with 0 values
135 * Deprecated: 2.32: Use #GArray and g_array_sized_new() instead.
138 g_value_array_new (guint n_prealloced
)
140 GValueArray
*value_array
= g_slice_new (GValueArray
);
142 value_array
->n_values
= 0;
143 value_array
->n_prealloced
= 0;
144 value_array
->values
= NULL
;
145 value_array_grow (value_array
, n_prealloced
, TRUE
);
146 value_array
->n_values
= 0;
152 * g_value_array_free:
153 * @value_array: #GValueArray to free
155 * Free a #GValueArray including its contents.
157 * Deprecated: 2.32: Use #GArray and g_array_unref() instead.
160 g_value_array_free (GValueArray
*value_array
)
164 g_return_if_fail (value_array
!= NULL
);
166 for (i
= 0; i
< value_array
->n_values
; i
++)
168 GValue
*value
= value_array
->values
+ i
;
170 if (G_VALUE_TYPE (value
) != 0) /* we allow unset values in the array */
171 g_value_unset (value
);
173 g_free (value_array
->values
);
174 g_slice_free (GValueArray
, value_array
);
178 * g_value_array_copy:
179 * @value_array: #GValueArray to copy
181 * Construct an exact copy of a #GValueArray by duplicating all its
184 * Returns: (transfer full): Newly allocated copy of #GValueArray
186 * Deprecated: 2.32: Use #GArray and g_array_ref() instead.
189 g_value_array_copy (const GValueArray
*value_array
)
191 GValueArray
*new_array
;
194 g_return_val_if_fail (value_array
!= NULL
, NULL
);
196 new_array
= g_slice_new (GValueArray
);
197 new_array
->n_values
= 0;
198 new_array
->values
= NULL
;
199 new_array
->n_prealloced
= 0;
200 value_array_grow (new_array
, value_array
->n_values
, TRUE
);
201 for (i
= 0; i
< new_array
->n_values
; i
++)
202 if (G_VALUE_TYPE (value_array
->values
+ i
) != 0)
204 GValue
*value
= new_array
->values
+ i
;
206 g_value_init (value
, G_VALUE_TYPE (value_array
->values
+ i
));
207 g_value_copy (value_array
->values
+ i
, value
);
213 * g_value_array_prepend:
214 * @value_array: #GValueArray to add an element to
215 * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
217 * Insert a copy of @value as first element of @value_array. If @value is
218 * %NULL, an uninitialized value is prepended.
221 * Returns: (transfer none): the #GValueArray passed in as @value_array
223 * Deprecated: 2.32: Use #GArray and g_array_prepend_val() instead.
226 g_value_array_prepend (GValueArray
*value_array
,
229 g_return_val_if_fail (value_array
!= NULL
, NULL
);
231 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
232 return g_value_array_insert (value_array
, 0, value
);
233 G_GNUC_END_IGNORE_DEPRECATIONS
237 * g_value_array_append:
238 * @value_array: #GValueArray to add an element to
239 * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
241 * Insert a copy of @value as last element of @value_array. If @value is
242 * %NULL, an uninitialized value is appended.
244 * Returns: (transfer none): the #GValueArray passed in as @value_array
246 * Deprecated: 2.32: Use #GArray and g_array_append_val() instead.
249 g_value_array_append (GValueArray
*value_array
,
252 g_return_val_if_fail (value_array
!= NULL
, NULL
);
254 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
255 return g_value_array_insert (value_array
, value_array
->n_values
, value
);
256 G_GNUC_END_IGNORE_DEPRECATIONS
260 * g_value_array_insert:
261 * @value_array: #GValueArray to add an element to
262 * @index_: insertion position, must be <= value_array->n_values
263 * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
265 * Insert a copy of @value at specified position into @value_array. If @value
266 * is %NULL, an uninitialized value is inserted.
268 * Returns: (transfer none): the #GValueArray passed in as @value_array
270 * Deprecated: 2.32: Use #GArray and g_array_insert_val() instead.
273 g_value_array_insert (GValueArray
*value_array
,
279 g_return_val_if_fail (value_array
!= NULL
, NULL
);
280 g_return_val_if_fail (index
<= value_array
->n_values
, value_array
);
282 i
= value_array
->n_values
;
283 value_array_grow (value_array
, value_array
->n_values
+ 1, FALSE
);
284 if (index
+ 1 < value_array
->n_values
)
285 memmove (value_array
->values
+ index
+ 1, value_array
->values
+ index
,
286 (i
- index
) * sizeof (value_array
->values
[0]));
287 memset (value_array
->values
+ index
, 0, sizeof (value_array
->values
[0]));
290 g_value_init (value_array
->values
+ index
, G_VALUE_TYPE (value
));
291 g_value_copy (value
, value_array
->values
+ index
);
297 * g_value_array_remove:
298 * @value_array: #GValueArray to remove an element from
299 * @index_: position of value to remove, which must be less than
300 * <code>value_array-><link
301 * linkend="GValueArray.n-values">n_values</link></code>
303 * Remove the value at position @index_ from @value_array.
305 * Returns: (transfer none): the #GValueArray passed in as @value_array
307 * Deprecated: 2.32: Use #GArray and g_array_remove_index() instead.
310 g_value_array_remove (GValueArray
*value_array
,
313 g_return_val_if_fail (value_array
!= NULL
, NULL
);
314 g_return_val_if_fail (index
< value_array
->n_values
, value_array
);
316 if (G_VALUE_TYPE (value_array
->values
+ index
) != 0)
317 g_value_unset (value_array
->values
+ index
);
318 value_array
->n_values
--;
319 if (index
< value_array
->n_values
)
320 memmove (value_array
->values
+ index
, value_array
->values
+ index
+ 1,
321 (value_array
->n_values
- index
) * sizeof (value_array
->values
[0]));
322 value_array_shrink (value_array
);
323 if (value_array
->n_prealloced
> value_array
->n_values
)
324 memset (value_array
->values
+ value_array
->n_values
, 0, sizeof (value_array
->values
[0]));
330 * g_value_array_sort:
331 * @value_array: #GValueArray to sort
332 * @compare_func: (scope call): function to compare elements
334 * Sort @value_array using @compare_func to compare the elements according to
335 * the semantics of #GCompareFunc.
337 * The current implementation uses the same sorting algorithm as standard
338 * C qsort() function.
340 * Returns: (transfer none): the #GValueArray passed in as @value_array
342 * Deprecated: 2.32: Use #GArray and g_array_sort().
345 g_value_array_sort (GValueArray
*value_array
,
346 GCompareFunc compare_func
)
348 g_return_val_if_fail (compare_func
!= NULL
, NULL
);
350 if (value_array
->n_values
)
351 qsort (value_array
->values
,
352 value_array
->n_values
,
353 sizeof (value_array
->values
[0]),
359 * g_value_array_sort_with_data:
360 * @value_array: #GValueArray to sort
361 * @compare_func: (scope call): function to compare elements
362 * @user_data: (closure): extra data argument provided for @compare_func
364 * Sort @value_array using @compare_func to compare the elements according
365 * to the semantics of #GCompareDataFunc.
367 * The current implementation uses the same sorting algorithm as standard
368 * C qsort() function.
370 * Rename to: g_value_array_sort
371 * Returns: (transfer none): the #GValueArray passed in as @value_array
373 * Deprecated: 2.32: Use #GArray and g_array_sort_with_data().
376 g_value_array_sort_with_data (GValueArray
*value_array
,
377 GCompareDataFunc compare_func
,
380 g_return_val_if_fail (value_array
!= NULL
, NULL
);
381 g_return_val_if_fail (compare_func
!= NULL
, NULL
);
383 if (value_array
->n_values
)
384 g_qsort_with_data (value_array
->values
,
385 value_array
->n_values
,
386 sizeof (value_array
->values
[0]),
387 compare_func
, user_data
);