1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 2001 Red Hat, Inc.
3 *
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.
8 *
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.
13 *
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.
18 */
19
20 /*
21 * MT safe
22 */
23
24 #include "config.h"
25
26 #include <string.h>
27 #include <stdlib.h> /* qsort() */
28
29 #include "gvaluearray.h"
30 #include "gobjectalias.h"
31
32
33 /**
34 * SECTION:value_arrays
35 * @short_description: A container structure to maintain an array of
36 * generic values
37 * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array()
38 * @title: Value arrays
39 *
40 * The prime purpose of a #GValueArray is for it to be used as an
41 * object property that holds an array of values. A #GValueArray wraps
42 * an array of #GValue elements in order for it to be used as a boxed
43 * type through %G_TYPE_VALUE_ARRAY.
44 */
45
46
47 #ifdef DISABLE_MEM_POOLS
48 # define GROUP_N_VALUES (1) /* power of 2 !! */
49 #else
50 # define GROUP_N_VALUES (8) /* power of 2 !! */
51 #endif
52
53
54 /* --- functions --- */
55 /**
56 * g_value_array_get_nth:
57 * @value_array: #GValueArray to get a value from
58 * @index_: index of the value of interest
59 *
60 * Return a pointer to the value at @index_ containd in @value_array.
61 *
62 * Returns: pointer to a value at @index_ in @value_array
63 */
64 GValue*
g_value_array_get_nth(GValueArray * value_array,guint index)65 g_value_array_get_nth (GValueArray *value_array,
66 guint index)
67 {
68 g_return_val_if_fail (value_array != NULL, NULL);
69 g_return_val_if_fail (index < value_array->n_values, NULL);
70
71 return value_array->values + index;
72 }
73
74 static inline void
value_array_grow(GValueArray * value_array,guint n_values,gboolean zero_init)75 value_array_grow (GValueArray *value_array,
76 guint n_values,
77 gboolean zero_init)
78 {
79 g_return_if_fail (n_values >= value_array->n_values);
80
81 value_array->n_values = n_values;
82 if (value_array->n_values > value_array->n_prealloced)
83 {
84 guint i = value_array->n_prealloced;
85
86 value_array->n_prealloced = (value_array->n_values + GROUP_N_VALUES - 1) & ~(GROUP_N_VALUES - 1);
87 value_array->values = g_renew (GValue, value_array->values, value_array->n_prealloced);
88 if (!zero_init)
89 i = value_array->n_values;
90 memset (value_array->values + i, 0,
91 (value_array->n_prealloced - i) * sizeof (value_array->values[0]));
92 }
93 }
94
95 static inline void
value_array_shrink(GValueArray * value_array)96 value_array_shrink (GValueArray *value_array)
97 {
98 #ifdef DISABLE_MEM_POOLS
99 if (value_array->n_prealloced >= value_array->n_values + GROUP_N_VALUES)
100 {
101 value_array->n_prealloced = (value_array->n_values + GROUP_N_VALUES - 1) & ~(GROUP_N_VALUES - 1);
102 value_array->values = g_renew (GValue, value_array->values, value_array->n_prealloced);
103 }
104 #endif
105 }
106
107 /**
108 * g_value_array_new:
109 * @n_prealloced: number of values to preallocate space for
110 *
111 * Allocate and initialize a new #GValueArray, optionally preserve space
112 * for @n_prealloced elements. New arrays always contain 0 elements,
113 * regardless of the value of @n_prealloced.
114 *
115 * Returns: a newly allocated #GValueArray with 0 values
116 */
117 GValueArray*
g_value_array_new(guint n_prealloced)118 g_value_array_new (guint n_prealloced)
119 {
120 GValueArray *value_array = g_slice_new (GValueArray);
121
122 value_array->n_values = 0;
123 value_array->n_prealloced = 0;
124 value_array->values = NULL;
125 value_array_grow (value_array, n_prealloced, TRUE);
126 value_array->n_values = 0;
127
128 return value_array;
129 }
130
131 /**
132 * g_value_array_free:
133 * @value_array: #GValueArray to free
134 *
135 * Free a #GValueArray including its contents.
136 */
137 void
g_value_array_free(GValueArray * value_array)138 g_value_array_free (GValueArray *value_array)
139 {
140 guint i;
141
142 g_return_if_fail (value_array != NULL);
143
144 for (i = 0; i < value_array->n_values; i++)
145 {
146 GValue *value = value_array->values + i;
147
148 if (G_VALUE_TYPE (value) != 0) /* we allow unset values in the array */
149 g_value_unset (value);
150 }
151 g_free (value_array->values);
152 g_slice_free (GValueArray, value_array);
153 }
154
155 /**
156 * g_value_array_copy:
157 * @value_array: #GValueArray to copy
158 *
159 * Construct an exact copy of a #GValueArray by duplicating all its
160 * contents.
161 *
162 * Returns: Newly allocated copy of #GValueArray
163 */
164 GValueArray*
g_value_array_copy(const GValueArray * value_array)165 g_value_array_copy (const GValueArray *value_array)
166 {
167 GValueArray *new_array;
168 guint i;
169
170 g_return_val_if_fail (value_array != NULL, NULL);
171
172 new_array = g_slice_new (GValueArray);
173 new_array->n_values = 0;
174 new_array->values = NULL;
175 new_array->n_prealloced = 0;
176 value_array_grow (new_array, value_array->n_values, TRUE);
177 for (i = 0; i < new_array->n_values; i++)
178 if (G_VALUE_TYPE (value_array->values + i) != 0)
179 {
180 GValue *value = new_array->values + i;
181
182 g_value_init (value, G_VALUE_TYPE (value_array->values + i));
183 g_value_copy (value_array->values + i, value);
184 }
185 return new_array;
186 }
187
188 /**
189 * g_value_array_prepend:
190 * @value_array: #GValueArray to add an element to
191 * @value: #GValue to copy into #GValueArray
192 *
193 * Insert a copy of @value as first element of @value_array.
194 *
195 * Returns: the #GValueArray passed in as @value_array
196 */
197 GValueArray*
g_value_array_prepend(GValueArray * value_array,const GValue * value)198 g_value_array_prepend (GValueArray *value_array,
199 const GValue *value)
200 {
201 g_return_val_if_fail (value_array != NULL, NULL);
202
203 return g_value_array_insert (value_array, 0, value);
204 }
205
206 /**
207 * g_value_array_append:
208 * @value_array: #GValueArray to add an element to
209 * @value: #GValue to copy into #GValueArray
210 *
211 * Insert a copy of @value as last element of @value_array.
212 *
213 * Returns: the #GValueArray passed in as @value_array
214 */
215 GValueArray*
g_value_array_append(GValueArray * value_array,const GValue * value)216 g_value_array_append (GValueArray *value_array,
217 const GValue *value)
218 {
219 g_return_val_if_fail (value_array != NULL, NULL);
220
221 return g_value_array_insert (value_array, value_array->n_values, value);
222 }
223
224 /**
225 * g_value_array_insert:
226 * @value_array: #GValueArray to add an element to
227 * @index_: insertion position, must be <= value_array->n_values
228 * @value: #GValue to copy into #GValueArray
229 *
230 * Insert a copy of @value at specified position into @value_array.
231 *
232 * Returns: the #GValueArray passed in as @value_array
233 */
234 GValueArray*
g_value_array_insert(GValueArray * value_array,guint index,const GValue * value)235 g_value_array_insert (GValueArray *value_array,
236 guint index,
237 const GValue *value)
238 {
239 guint i;
240
241 g_return_val_if_fail (value_array != NULL, NULL);
242 g_return_val_if_fail (index <= value_array->n_values, value_array);
243
244 /* we support NULL for "value" as a shortcut for an unset value */
245
246 i = value_array->n_values;
247 value_array_grow (value_array, value_array->n_values + 1, FALSE);
248 if (index + 1 < value_array->n_values)
249 g_memmove (value_array->values + index + 1, value_array->values + index,
250 (i - index) * sizeof (value_array->values[0]));
251 memset (value_array->values + index, 0, sizeof (value_array->values[0]));
252 if (value)
253 {
254 g_value_init (value_array->values + index, G_VALUE_TYPE (value));
255 g_value_copy (value, value_array->values + index);
256 }
257 return value_array;
258 }
259
260 /**
261 * g_value_array_remove:
262 * @value_array: #GValueArray to remove an element from
263 * @index_: position of value to remove, must be < value_array->n_values
264 *
265 * Remove the value at position @index_ from @value_array.
266 *
267 * Returns: the #GValueArray passed in as @value_array
268 */
269 GValueArray*
g_value_array_remove(GValueArray * value_array,guint index)270 g_value_array_remove (GValueArray *value_array,
271 guint index)
272 {
273 g_return_val_if_fail (value_array != NULL, NULL);
274 g_return_val_if_fail (index < value_array->n_values, value_array);
275
276 if (G_VALUE_TYPE (value_array->values + index) != 0)
277 g_value_unset (value_array->values + index);
278 value_array->n_values--;
279 if (index < value_array->n_values)
280 g_memmove (value_array->values + index, value_array->values + index + 1,
281 (value_array->n_values - index) * sizeof (value_array->values[0]));
282 value_array_shrink (value_array);
283 if (value_array->n_prealloced > value_array->n_values)
284 memset (value_array->values + value_array->n_values, 0, sizeof (value_array->values[0]));
285
286 return value_array;
287 }
288
289 /**
290 * g_value_array_sort:
291 * @value_array: #GValueArray to sort
292 * @compare_func: function to compare elements
293 *
294 * Sort @value_array using @compare_func to compare the elements accoring to
295 * the semantics of #GCompareFunc.
296 *
297 * The current implementation uses Quick-Sort as sorting algorithm.
298 *
299 * Returns: the #GValueArray passed in as @value_array
300 */
301 GValueArray*
g_value_array_sort(GValueArray * value_array,GCompareFunc compare_func)302 g_value_array_sort (GValueArray *value_array,
303 GCompareFunc compare_func)
304 {
305 g_return_val_if_fail (compare_func != NULL, NULL);
306
307 if (value_array->n_values)
308 qsort (value_array->values,
309 value_array->n_values,
310 sizeof (value_array->values[0]),
311 compare_func);
312 return value_array;
313 }
314
315 /**
316 * g_value_array_sort_with_data:
317 * @value_array: #GValueArray to sort
318 * @compare_func: function to compare elements
319 * @user_data: extra data argument provided for @compare_func
320 *
321 * Sort @value_array using @compare_func to compare the elements accoring
322 * to the semantics of #GCompareDataFunc.
323 *
324 * The current implementation uses Quick-Sort as sorting algorithm.
325 *
326 * Returns: the #GValueArray passed in as @value_array
327 */
328 GValueArray*
g_value_array_sort_with_data(GValueArray * value_array,GCompareDataFunc compare_func,gpointer user_data)329 g_value_array_sort_with_data (GValueArray *value_array,
330 GCompareDataFunc compare_func,
331 gpointer user_data)
332 {
333 g_return_val_if_fail (value_array != NULL, NULL);
334 g_return_val_if_fail (compare_func != NULL, NULL);
335
336 if (value_array->n_values)
337 g_qsort_with_data (value_array->values,
338 value_array->n_values,
339 sizeof (value_array->values[0]),
340 compare_func, user_data);
341 return value_array;
342 }
343
344 #define __G_VALUE_ARRAY_C__
345 #include "gobjectaliasdef.c"
346