cairo/src/cairo-array.c

   1 /* cairo - a vector graphics library with display and print output
   2  *
   3  * Copyright © 2004 Red Hat, Inc
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it either under the terms of the GNU Lesser General Public
   7  * License version 2.1 as published by the Free Software Foundation
   8  * (the "LGPL") or, at your option, under the terms of the Mozilla
   9  * Public License Version 1.1 (the "MPL"). If you do not alter this
  10  * notice, a recipient may use your version of this file under either
  11  * the MPL or the LGPL.
  12  *
  13  * You should have received a copy of the LGPL along with this library
  14  * in the file COPYING-LGPL-2.1; if not, write to the Free Software
  15  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  16  * You should have received a copy of the MPL along with this library
  17  * in the file COPYING-MPL-1.1
  18  *
  19  * The contents of this file are subject to the Mozilla Public License
  20  * Version 1.1 (the "License"); you may not use this file except in
  21  * compliance with the License. You may obtain a copy of the License at
  22  * http://www.mozilla.org/MPL/
  23  *
  24  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
  25  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  26  * the specific language governing rights and limitations.
  27  *
  28  * The Original Code is the cairo graphics library.
  29  *
  30  * The Initial Developer of the Original Code is University of Southern
  31  * California.
  32  *
  33  * Contributor(s):
  34  *      Kristian Høgsberg <krh@redhat.com>
  35  *      Carl Worth <cworth@cworth.org>
  36  */
  37
  38 #include "cairoint.h"
  39
  40 /**
  41  * _cairo_array_init:
  42  *
  43  * Initialize a new #cairo_array_t object to store objects each of size
  44  * @element_size.
  45  *
  46  * The #cairo_array_t object provides grow-by-doubling storage. It
  47  * never interprets the data passed to it, nor does it provide any
  48  * sort of callback mechanism for freeing resources held onto by
  49  * stored objects.
  50  *
  51  * When finished using the array, _cairo_array_fini() should be
  52  * called to free resources allocated during use of the array.
  53  **/
  54 void
  55 _cairo_array_init (cairo_array_t *array, int element_size)
  56 {
  57     array->size = 0;
  58     array->num_elements = 0;
  59     array->element_size = element_size;
  60     array->elements = NULL;
  61
  62     array->is_snapshot = FALSE;
  63 }
  64
  65 /**
  66  * _cairo_array_init_snapshot:
  67  * @array: A #cairo_array_t to be initialized as a snapshot
  68  * @other: The #cairo_array_t from which to create the snapshot
  69  *
  70  * Initialize @array as an immutable copy of @other. It is an error to
  71  * call an array-modifying function (other than _cairo_array_fini) on
  72  * @array after calling this function.
  73  **/
  74 void
  75 _cairo_array_init_snapshot (cairo_array_t       *array,
  76                             const cairo_array_t *other)
  77 {
  78     array->size = other->size;
  79     array->num_elements = other->num_elements;
  80     array->element_size = other->element_size;
  81     array->elements = other->elements;
  82
  83     array->is_snapshot = TRUE;
  84 }
  85
  86 /**
  87  * _cairo_array_fini:
  88  * @array: A #cairo_array_t
  89  *
  90  * Free all resources associated with @array. After this call, @array
  91  * should not be used again without a subsequent call to
  92  * _cairo_array_init() again first.
  93  **/
  94 void
  95 _cairo_array_fini (cairo_array_t *array)
  96 {
  97     if (array->is_snapshot)
  98         return;
  99
 100     if (array->elements) {
 101         free (* array->elements);
 102         free (array->elements);
 103     }
 104 }
 105
 106 /**
 107  * _cairo_array_grow_by:
 108  * @array: a #cairo_array_t
 109  *
 110  * Increase the size of @array (if needed) so that there are at least
 111  * @additional free spaces in the array. The actual size of the array
 112  * is always increased by doubling as many times as necessary.
 113  **/
 114 cairo_status_t
 115 _cairo_array_grow_by (cairo_array_t *array, unsigned int additional)
 116 {
 117     char *new_elements;
 118     unsigned int old_size = array->size;
 119     unsigned int required_size = array->num_elements + additional;
 120     unsigned int new_size;
 121
 122     assert (! array->is_snapshot);
 123
 124     /* check for integer overflow */
 125     if (required_size > INT_MAX || required_size < array->num_elements)
 126         return _cairo_error (CAIRO_STATUS_NO_MEMORY);
 127
 128     if (required_size <= old_size)
 129         return CAIRO_STATUS_SUCCESS;
 130
 131     if (old_size == 0)
 132         new_size = 1;
 133     else
 134         new_size = old_size * 2;
 135
 136     while (new_size < required_size)
 137         new_size = new_size * 2;
 138
 139     if (array->elements == NULL) {
 140         array->elements = malloc (sizeof (char *));
 141         if (array->elements == NULL)
 142             return _cairo_error (CAIRO_STATUS_NO_MEMORY);
 143
 144         *array->elements = NULL;
 145     }
 146
 147     array->size = new_size;
 148     new_elements = _cairo_realloc_ab (*array->elements,
 149                                       array->size, array->element_size);
 150
 151     if (new_elements == NULL) {
 152         array->size = old_size;
 153         return _cairo_error (CAIRO_STATUS_NO_MEMORY);
 154     }
 155
 156     *array->elements = new_elements;
 157
 158     return CAIRO_STATUS_SUCCESS;
 159 }
 160
 161 /**
 162  * _cairo_array_truncate:
 163  * @array: a #cairo_array_t
 164  *
 165  * Truncate size of the array to @num_elements if less than the
 166  * current size. No memory is actually freed. The stored objects
 167  * beyond @num_elements are simply "forgotten".
 168  **/
 169 void
 170 _cairo_array_truncate (cairo_array_t *array, unsigned int num_elements)
 171 {
 172     assert (! array->is_snapshot);
 173
 174     if (num_elements < array->num_elements)
 175         array->num_elements = num_elements;
 176 }
 177
 178 /**
 179  * _cairo_array_index:
 180  * @array: a #cairo_array_t
 181  * Returns: A pointer to the object stored at @index.
 182  *
 183  * If the resulting value is assigned to a pointer to an object of the same
 184  * element_size as initially passed to _cairo_array_init() then that
 185  * pointer may be used for further direct indexing with []. For
 186  * example:
 187  *
 188  * <informalexample><programlisting>
 189  *      cairo_array_t array;
 190  *      double *values;
 191  *
 192  *      _cairo_array_init (&array, sizeof(double));
 193  *      ... calls to _cairo_array_append() here ...
 194  *
 195  *      values = _cairo_array_index (&array, 0);
 196  *      for (i = 0; i < _cairo_array_num_elements (&array); i++)
 197  *          ... use values[i] here ...
 198  * </programlisting></informalexample>
 199  **/
 200 void *
 201 _cairo_array_index (cairo_array_t *array, unsigned int index)
 202 {
 203     /* We allow an index of 0 for the no-elements case.
 204      * This makes for cleaner calling code which will often look like:
 205      *
 206      *    elements = _cairo_array_index (array, num_elements);
 207      *    for (i=0; i < num_elements; i++) {
 208      *        ... use elements[i] here ...
 209      *    }
 210      *
 211      * which in the num_elements==0 case gets the NULL pointer here,
 212      * but never dereferences it.
 213      */
 214     if (index == 0 && array->num_elements == 0)
 215         return NULL;
 216
 217     assert (index < array->num_elements);
 218
 219     return (void *) &(*array->elements)[index * array->element_size];
 220 }
 221
 222 /**
 223  * _cairo_array_copy_element:
 224  * @array: a #cairo_array_t
 225  *
 226  * Copy a single element out of the array from index @index into the
 227  * location pointed to by @dst.
 228  **/
 229 void
 230 _cairo_array_copy_element (cairo_array_t *array, int index, void *dst)
 231 {
 232     memcpy (dst, _cairo_array_index (array, index), array->element_size);
 233 }
 234
 235 /**
 236  * _cairo_array_append:
 237  * @array: a #cairo_array_t
 238  *
 239  * Append a single item onto the array by growing the array by at
 240  * least one element, then copying element_size bytes from @element
 241  * into the array. The address of the resulting object within the
 242  * array can be determined with:
 243  *
 244  * _cairo_array_index (array, _cairo_array_num_elements (array) - 1);
 245  *
 246  * Return value: %CAIRO_STATUS_SUCCESS if successful or
 247  * %CAIRO_STATUS_NO_MEMORY if insufficient memory is available for the
 248  * operation.
 249  **/
 250 cairo_status_t
 251 _cairo_array_append (cairo_array_t      *array,
 252                      const void         *element)
 253 {
 254     assert (! array->is_snapshot);
 255
 256     return _cairo_array_append_multiple (array, element, 1);
 257 }
 258
 259 /**
 260  * _cairo_array_append:
 261  * @array: a #cairo_array_t
 262  *
 263  * Append one or more items onto the array by growing the array by
 264  * @num_elements, then copying @num_elements * element_size bytes from
 265  * @elements into the array.
 266  *
 267  * Return value: %CAIRO_STATUS_SUCCESS if successful or
 268  * %CAIRO_STATUS_NO_MEMORY if insufficient memory is available for the
 269  * operation.
 270  **/
 271 cairo_status_t
 272 _cairo_array_append_multiple (cairo_array_t     *array,
 273                               const void        *elements,
 274                               int                num_elements)
 275 {
 276     cairo_status_t status;
 277     void *dest;
 278
 279     assert (! array->is_snapshot);
 280
 281     status = _cairo_array_allocate (array, num_elements, &dest);
 282     if (status)
 283         return status;
 284
 285     memcpy (dest, elements, num_elements * array->element_size);
 286
 287     return CAIRO_STATUS_SUCCESS;
 288 }
 289
 290 /**
 291  * _cairo_array_allocate:
 292  * @array: a #cairo_array_t
 293  *
 294  * Allocate space at the end of the array for @num_elements additional
 295  * elements, providing the address of the new memory chunk in
 296  * @elements. This memory will be unitialized, but will be accounted
 297  * for in the return value of _cairo_array_num_elements().
 298  *
 299  * Return value: %CAIRO_STATUS_SUCCESS if successful or
 300  * %CAIRO_STATUS_NO_MEMORY if insufficient memory is available for the
 301  * operation.
 302  **/
 303 cairo_status_t
 304 _cairo_array_allocate (cairo_array_t     *array,
 305                        unsigned int       num_elements,
 306                        void             **elements)
 307 {
 308     cairo_status_t status;
 309
 310     assert (! array->is_snapshot);
 311
 312     status = _cairo_array_grow_by (array, num_elements);
 313     if (status)
 314         return status;
 315
 316     assert (array->num_elements + num_elements <= array->size);
 317
 318     *elements = &(*array->elements)[array->num_elements * array->element_size];
 319
 320     array->num_elements += num_elements;
 321
 322     return CAIRO_STATUS_SUCCESS;
 323 }
 324
 325 /**
 326  * _cairo_array_num_elements:
 327  * @array: a #cairo_array_t
 328  * Returns: The number of elements stored in @array.
 329  *
 330  * This space was left intentionally blank, but gtk-doc filled it.
 331  **/
 332 int
 333 _cairo_array_num_elements (cairo_array_t *array)
 334 {
 335     return array->num_elements;
 336 }
 337
 338 /**
 339  * _cairo_array_size:
 340  * @array: a #cairo_array_t
 341  * Returns: The number of elements for which there is currently space
 342  * allocated in @array.
 343  *
 344  * This space was left intentionally blank, but gtk-doc filled it.
 345  **/
 346 int
 347 _cairo_array_size (cairo_array_t *array)
 348 {
 349     return array->size;
 350 }
 351
 352 /* #cairo_user_data_array_t */
 353
 354 typedef struct {
 355     const cairo_user_data_key_t *key;
 356     void *user_data;
 357     cairo_destroy_func_t destroy;
 358 } cairo_user_data_slot_t;
 359
 360 /**
 361  * _cairo_user_data_array_init:
 362  * @array: a #cairo_user_data_array_t
 363  *
 364  * Initializes a #cairo_user_data_array_t structure for future
 365  * use. After initialization, the array has no keys. Call
 366  * _cairo_user_data_array_fini() to free any allocated memory
 367  * when done using the array.
 368  **/
 369 void
 370 _cairo_user_data_array_init (cairo_user_data_array_t *array)
 371 {
 372     _cairo_array_init (array, sizeof (cairo_user_data_slot_t));
 373 }
 374
 375 /**
 376  * _cairo_user_data_array_fini:
 377  * @array: a #cairo_user_data_array_t
 378  *
 379  * Destroys all current keys in the user data array and deallocates
 380  * any memory allocated for the array itself.
 381  **/
 382 void
 383 _cairo_user_data_array_fini (cairo_user_data_array_t *array)
 384 {
 385     int i, num_slots;
 386     cairo_user_data_slot_t *slots;
 387
 388     num_slots = array->num_elements;
 389     slots = _cairo_array_index (array, 0);
 390     for (i = 0; i < num_slots; i++) {
 391         if (slots[i].user_data != NULL && slots[i].destroy != NULL)
 392             slots[i].destroy (slots[i].user_data);
 393     }
 394
 395     _cairo_array_fini (array);
 396 }
 397
 398 /**
 399  * _cairo_user_data_array_get_data:
 400  * @array: a #cairo_user_data_array_t
 401  * @key: the address of the #cairo_user_data_key_t the user data was
 402  * attached to
 403  *
 404  * Returns user data previously attached using the specified
 405  * key.  If no user data has been attached with the given key this
 406  * function returns %NULL.
 407  *
 408  * Return value: the user data previously attached or %NULL.
 409  **/
 410 void *
 411 _cairo_user_data_array_get_data (cairo_user_data_array_t     *array,
 412                                  const cairo_user_data_key_t *key)
 413 {
 414     int i, num_slots;
 415     cairo_user_data_slot_t *slots;
 416
 417     /* We allow this to support degenerate objects such as cairo_surface_nil. */
 418     if (array == NULL)
 419         return NULL;
 420
 421     num_slots = array->num_elements;
 422     slots = _cairo_array_index (array, 0);
 423     for (i = 0; i < num_slots; i++) {
 424         if (slots[i].key == key)
 425             return slots[i].user_data;
 426     }
 427
 428     return NULL;
 429 }
 430
 431 /**
 432  * _cairo_user_data_array_set_data:
 433  * @array: a #cairo_user_data_array_t
 434  * @key: the address of a #cairo_user_data_key_t to attach the user data to
 435  * @user_data: the user data to attach
 436  * @destroy: a #cairo_destroy_func_t which will be called when the
 437  * user data array is destroyed or when new user data is attached using the
 438  * same key.
 439  *
 440  * Attaches user data to a user data array.  To remove user data,
 441  * call this function with the key that was used to set it and %NULL
 442  * for @data.
 443  *
 444  * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
 445  * slot could not be allocated for the user data.
 446  **/
 447 cairo_status_t
 448 _cairo_user_data_array_set_data (cairo_user_data_array_t     *array,
 449                                  const cairo_user_data_key_t *key,
 450                                  void                        *user_data,
 451                                  cairo_destroy_func_t         destroy)
 452 {
 453     cairo_status_t status;
 454     int i, num_slots;
 455     cairo_user_data_slot_t *slots, *slot, new_slot;
 456
 457     if (user_data) {
 458         new_slot.key = key;
 459         new_slot.user_data = user_data;
 460         new_slot.destroy = destroy;
 461     } else {
 462         new_slot.key = NULL;
 463         new_slot.user_data = NULL;
 464         new_slot.destroy = NULL;
 465     }
 466
 467     slot = NULL;
 468     num_slots = array->num_elements;
 469     slots = _cairo_array_index (array, 0);
 470     for (i = 0; i < num_slots; i++) {
 471         if (slots[i].key == key) {
 472             slot = &slots[i];
 473             if (slot->destroy && slot->user_data)
 474                 slot->destroy (slot->user_data);
 475             break;
 476         }
 477         if (user_data && slots[i].user_data == NULL) {
 478             slot = &slots[i];   /* Have to keep searching for an exact match */
 479         }
 480     }
 481
 482     if (slot) {
 483         *slot = new_slot;
 484         return CAIRO_STATUS_SUCCESS;
 485     }
 486
 487     status = _cairo_array_append (array, &new_slot);
 488     if (status)
 489         return status;
 490
 491     return CAIRO_STATUS_SUCCESS;
 492 }