gobject/gvaluearray.c

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