src/darray.h

   1 /*
   2  * Copyright (C) 2011 Joseph Adams <joeyadams3.14159@gmail.com>
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a copy
   5  * of this software and associated documentation files (the "Software"), to deal
   6  * in the Software without restriction, including without limitation the rights
   7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   8  * copies of the Software, and to permit persons to whom the Software is
   9  * furnished to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice shall be included in
  12  * all copies or substantial portions of the Software.
  13  *
  14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  19  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  20  * THE SOFTWARE.
  21  */
  22
  23 #ifndef CCAN_DARRAY_H
  24 #define CCAN_DARRAY_H
  25
  26 #include <stdlib.h>
  27 #include <string.h>
  28 #include "config.h"
  29
  30 /*
  31  * SYNOPSIS
  32  *
  33  * Life cycle of a darray (dynamically-allocated array):
  34  *
  35  *     darray(int) a = darray_new();
  36  *     darray_free(a);
  37  *
  38  *     struct {darray(int) a;} foo;
  39  *     darray_init(foo.a);
  40  *     darray_free(foo.a);
  41  *
  42  *     const struct {
  43  *         darray(int) a;
  44  *      } foo = {
  45  *         .a = darray_lit({1, 2, 3})
  46  *      };
  47  *
  48  * Typedefs for darrays of common types:
  49  *
  50  *     darray_char, darray_schar, darray_uchar
  51  *     darray_short, darray_int, darray_long
  52  *     darray_ushort, darray_uint, darray_ulong
  53  *
  54  * Access:
  55  *
  56  *     T      darray_item(darray(T) arr, size_t index);
  57  *     size_t darray_size(darray(T) arr);
  58  *     size_t darray_alloc(darray(T) arr);
  59  *     bool   darray_empty(darray(T) arr);
  60  *
  61  *     // Access raw memory, starting from the item in offset.
  62  *     // Not safe, be careful, etc.
  63  *     T*     darray_mem(darray(T) arr, size_t offset);
  64  *
  65  * Insertion (single item):
  66  *
  67  *     void   darray_append(darray(T) arr, T item);
  68  *     void   darray_prepend(darray(T) arr, T item);
  69  *     void   darray_push(darray(T) arr, T item); // same as darray_append
  70  *
  71  * Insertion (multiple items):
  72  *
  73  *     void   darray_append_items(darray(T) arr, T *items, size_t count);
  74  *     void   darray_prepend_items(darray(T) arr, T *items, size_t count);
  75  *
  76  *     void   darray_appends(darray(T) arr, [T item, [...]]);
  77  *     void   darray_prepends(darray(T) arr, [T item, [...]]);
  78  *
  79  *     // Same functionality as above, but does not require typeof.
  80  *     void   darray_appends_t(darray(T) arr, #T, [T item, [...]]);
  81  *     void   darray_prepends_t(darray(T) arr, #T, [T item, [...]]);
  82  *
  83  * Removal:
  84  *
  85  *     T      darray_pop(darray(T) arr | darray_size(arr) != 0);
  86  *     T*     darray_pop_check(darray(T*) arr);
  87  *
  88  * Replacement:
  89  *
  90  *     void   darray_from_items(darray(T) arr, T *items, size_t count);
  91  *     void   darray_from_c(darray(T) arr, T c_array[N]);
  92  *
  93  * String buffer:
  94  *
  95  *     void   darray_append_string(darray(char) arr, const char *str);
  96  *     void   darray_append_lit(darray(char) arr, char stringLiteral[N+1]);
  97  *
  98  *     void   darray_prepend_string(darray(char) arr, const char *str);
  99  *     void   darray_prepend_lit(darray(char) arr, char stringLiteral[N+1]);
 100  *
 101  *     void   darray_from_string(darray(T) arr, const char *str);
 102  *     void   darray_from_lit(darray(char) arr, char stringLiteral[N+1]);
 103  *
 104  * Size management:
 105  *
 106  *     void   darray_resize(darray(T) arr, size_t newSize);
 107  *     void   darray_resize0(darray(T) arr, size_t newSize);
 108  *
 109  *     void   darray_realloc(darray(T) arr, size_t newAlloc);
 110  *     void   darray_growalloc(darray(T) arr, size_t newAlloc);
 111  *
 112  *     void   darray_make_room(darray(T) arr, size_t room);
 113  *
 114  * Traversal:
 115  *
 116  *     darray_foreach(T *&i, darray(T) arr) {...}
 117  *     darray_foreach_reverse(T *&i, darray(T) arr) {...}
 118  *
 119  * Except for darray_foreach and darray_foreach_reverse,
 120  * all macros evaluate their non-darray arguments only once.
 121  */
 122
 123 /*** Life cycle ***/
 124
 125 #define darray(type)     struct { type *item; size_t size; size_t alloc; }
 126
 127 #define darray_new()     { 0, 0, 0 }
 128 #define darray_init(arr) do { (arr).item = 0; (arr).size = 0; (arr).alloc = 0; \
 129 } while (0)
 130 #define darray_free(arr) do { free((arr).item); darray_init(arr); } while (0)
 131
 132 /* Only use for immutable darray - e.g. for static const initialzers. */
 133 #define darray_lit(c_array) { (c_array), sizeof(c_array) / sizeof(*(c_array)), \
 134                               0 }
 135
 136 /*
 137  * Typedefs for darrays of common types.  These are useful
 138  * when you want to pass a pointer to an darray(T) around.
 139  *
 140  * The following will produce an incompatible pointer warning:
 141  *
 142  *     void foo(darray(int) *arr);
 143  *     darray(int) arr = darray_new();
 144  *     foo(&arr);
 145  *
 146  * The workaround:
 147  *
 148  *     void foo(darray_int *arr);
 149  *     darray_int arr = darray_new();
 150  *     foo(&arr);
 151  */
 152
 153 typedef darray (char)           darray_char;
 154 typedef darray (signed char)    darray_schar;
 155 typedef darray (unsigned char)  darray_uchar;
 156
 157 typedef darray (short)          darray_short;
 158 typedef darray (int)            darray_int;
 159 typedef darray (long)           darray_long;
 160
 161 typedef darray (unsigned short) darray_ushort;
 162 typedef darray (unsigned int)   darray_uint;
 163 typedef darray (unsigned long)  darray_ulong;
 164
 165 /*** Access ***/
 166
 167 #define darray_item(arr, i)     ((arr).item[i])
 168 #define darray_size(arr)        ((arr).size)
 169 #define darray_alloc(arr)       ((arr).alloc)
 170 #define darray_empty(arr)       ((arr).size == 0)
 171
 172 #define darray_mem(arr, offset) ((arr).item + (offset))
 173 #define darray_same(arr1, arr2) ((arr1).item == (arr2).item)
 174
 175 /*** Insertion (single item) ***/
 176
 177 #define darray_append(arr, ...)  do { \
 178         darray_resize(arr, (arr).size + 1); \
 179         (arr).item[(arr).size - 1] = (__VA_ARGS__); \
 180 } while (0)
 181 #define darray_prepend(arr, ...) do { \
 182         darray_resize(arr, (arr).size + 1); \
 183         memmove((arr).item + 1, (arr).item, \
 184                 ((arr).size - 1) * sizeof(*(arr).item)); \
 185         (arr).item[0] = (__VA_ARGS__); \
 186 } while (0)
 187 #define darray_push(arr, ...)    darray_append(arr, __VA_ARGS__)
 188
 189 /*** Insertion (multiple items) ***/
 190
 191 #define darray_append_items(arr, items, count)                do { \
 192         size_t __count = (count), __oldSize = (arr).size; \
 193         darray_resize(arr, __oldSize + __count); \
 194         memcpy((arr).item + __oldSize, items, __count * sizeof(*(arr).item)); \
 195 } while (0)
 196
 197 #define darray_prepend_items(arr, items, count)               do { \
 198         size_t __count = (count), __oldSize = (arr).size; \
 199         darray_resize(arr, __count + __oldSize); \
 200         memmove((arr).item + __count, (arr).item, __oldSize * \
 201                 sizeof(*(arr).item)); \
 202         memcpy((arr).item, items, __count * sizeof(*(arr).item)); \
 203 } while (0)
 204
 205 #define darray_append_items_nullterminate(arr, items, count)  do { \
 206         size_t __count = (count), __oldSize = (arr).size; \
 207         darray_resize(arr, __oldSize + __count + 1); \
 208         memcpy((arr).item + __oldSize, items, __count * sizeof(*(arr).item)); \
 209         (arr).item[--(arr).size] = 0; \
 210 } while (0)
 211
 212 #define darray_prepend_items_nullterminate(arr, items, count) do { \
 213         size_t __count = (count), __oldSize = (arr).size; \
 214         darray_resize(arr, __count + __oldSize + 1); \
 215         memmove((arr).item + __count, (arr).item, __oldSize * \
 216                 sizeof(*(arr).item)); \
 217         memcpy((arr).item, items, __count * sizeof(*(arr).item)); \
 218         (arr).item[--(arr).size] = 0; \
 219 } while (0)
 220
 221 #if HAVE_TYPEOF
 222 #define darray_appends(arr, ...)  darray_appends_t(arr, typeof((*(arr).item)), \
 223                                                    __VA_ARGS__)
 224 #define darray_prepends(arr, ...) darray_prepends_t(arr, typeof((*(arr).item)), \
 225                                                     __VA_ARGS__)
 226 #endif
 227
 228 #define darray_appends_t(arr, type, ...)  do { \
 229         type __src[] = { __VA_ARGS__ }; \
 230         darray_append_items(arr, __src, sizeof(__src) / sizeof(*__src)); \
 231 } while (0)
 232 #define darray_prepends_t(arr, type, ...) do { \
 233         type __src[] = { __VA_ARGS__ }; \
 234         darray_prepend_items(arr, __src, sizeof(__src) / sizeof(*__src)); \
 235 } while (0)
 236
 237 /*** Removal ***/
 238
 239 /* Warning: Do not call darray_pop on an empty darray. */
 240 #define darray_pop(arr)       ((arr).item[--(arr).size])
 241 #define darray_pop_check(arr) ((arr).size ? darray_pop(arr) : NULL)
 242
 243 /*** Replacement ***/
 244
 245 #define darray_from_items(arr, items, count) do { size_t __count = (count); \
 246                                                   darray_resize(arr, __count); \
 247                                                   memcpy((arr).item, items, \
 248                                                          __count \
 249                                                          * sizeof(*(arr).item)); \
 250 } while (0)
 251 #define darray_from_c(arr, c_array)          darray_from_items( \
 252         arr, c_array, sizeof(c_array) / sizeof(*(c_array)))
 253 #define darray_copy(arr_to, arr_from)        darray_from_items( \
 254         arr_to, \
 255         (arr_from). \
 256         item, (arr_from).size)
 257
 258 /*** String buffer ***/
 259
 260 #define darray_append_string(arr, str)        do { const char *__str = (str); \
 261                                                    darray_append_items( \
 262                                                        arr, __str, \
 263                                                        strlen(__str) + 1); \
 264                                                    (arr).size--; \
 265 } while (0)
 266 #define darray_append_lit(arr, stringLiteral) do { darray_append_items( \
 267                                                        arr, stringLiteral, \
 268                                                        sizeof(stringLiteral)); \
 269                                                    (arr).size--; } while (0)
 270
 271 #define darray_prepend_string(arr, str)       do { \
 272         const char *__str = (str); \
 273         darray_prepend_items_nullterminate(arr, __str, strlen(__str)); \
 274 } while (0)
 275 #define darray_prepend_lit(arr, stringLiteral) \
 276     darray_prepend_items_nullterminate(arr, stringLiteral, \
 277                                        sizeof(stringLiteral) - 1)
 278
 279 #define darray_from_string(arr, str)        do { const char *__str = (str); \
 280                                                  darray_from_items( \
 281                                                      arr, __str, strlen( \
 282                                                          __str) + 1); \
 283                                                  (arr).size--; \
 284 } while (0)
 285 #define darray_from_lit(arr, stringLiteral) do { darray_from_items( \
 286                                                      arr, stringLiteral, \
 287                                                      sizeof(stringLiteral)); \
 288                                                  (arr).size--; } while (0)
 289
 290 /*** Size management ***/
 291
 292 #define darray_resize(arr, newSize)   darray_growalloc(arr, (arr).size = \
 293                                                            (newSize))
 294 #define darray_resize0(arr, newSize)  do { \
 295         size_t __oldSize = (arr).size, __newSize = (newSize); \
 296         (arr).size = __newSize; \
 297         if (__newSize > __oldSize) { \
 298             darray_growalloc(arr, __newSize); \
 299             memset(&(arr).item[__oldSize], 0, \
 300                    (__newSize - __oldSize) * sizeof(*(arr).item)); \
 301         } \
 302 } while (0)
 303
 304 #define darray_realloc(arr, newAlloc) do { \
 305         (arr).item = \
 306             realloc((arr).item, ((arr).alloc = (newAlloc)) * \
 307                     sizeof(*(arr).item)); \
 308 } while (0)
 309 #define darray_growalloc(arr, need)   do { \
 310         size_t __need = (need); \
 311         if (__need > (arr).alloc) \
 312             darray_realloc(arr, darray_next_alloc((arr).alloc, __need)); \
 313 } while (0)
 314
 315 #if HAVE_STATEMENT_EXPR == 1
 316 #define darray_make_room(arr, \
 317                          room) ({ size_t newAlloc = (arr).size + (room); \
 318                                   if ((arr).alloc < \
 319                                       newAlloc) darray_realloc(arr, newAlloc); \
 320                                   (arr).item + (arr).size; })
 321 #endif
 322
 323 static inline size_t
 324 darray_next_alloc(size_t alloc, size_t need)
 325 {
 326     if (alloc == 0)
 327         alloc = 4;
 328     while (alloc < need)
 329         alloc *= 2;
 330     return alloc;
 331 }
 332
 333 /*** Traversal ***/
 334
 335 /*
 336  * darray_foreach(T *&i, darray(T) arr) {...}
 337  *
 338  * Traverse a darray.  `i` must be declared in advance as a pointer to an item.
 339  */
 340 #define darray_foreach(i, arr) \
 341     for ((i) = &(arr).item[0]; (i) < &(arr).item[(arr).size]; (i)++)
 342
 343 #define darray_foreach_from(i, arr, from) \
 344         for ((i) = &(arr).item[from]; (i) < &(arr).item[(arr).size]; (i)++)
 345
 346 /*
 347  * darray_foreach_reverse(T *&i, darray(T) arr) {...}
 348  *
 349  * Like darray_foreach, but traverse in reverse order.
 350  */
 351 #define darray_foreach_reverse(i, arr) \
 352     for ((i) = &(arr).item[(arr).size]; (i)-- > &(arr).item[0]; )
 353
 354 #endif /* CCAN_DARRAY_H */
 355
 356 /*
 357  *
 358  * darray_growalloc(arr, newAlloc) sees if the darray can currently hold newAlloc items;
 359  *      if not, it increases the alloc to satisfy this requirement, allocating slack
 360  *      space to avoid having to reallocate for every size increment.
 361  *
 362  * darray_from_string(arr, str) copies a string to an darray_char.
 363  *
 364  * darray_push(arr, item) pushes an item to the end of the darray.
 365  * darray_pop(arr) pops it back out.  Be sure there is at least one item in the darray before calling.
 366  * darray_pop_check(arr) does the same as darray_pop, but returns NULL if there are no more items left in the darray.
 367  *
 368  * darray_make_room(arr, room) ensures there's 'room' elements of space after the end of the darray, and it returns a pointer to this space.
 369  * Currently requires HAVE_STATEMENT_EXPR, but I plan to remove this dependency by creating an inline function.
 370  *
 371  * The following require HAVE_TYPEOF==1 :
 372  *
 373  * darray_appends(arr, item0, item1...) appends a collection of comma-delimited items to the darray.
 374  * darray_prepends(arr, item0, item1...) prepends a collection of comma-delimited items to the darray.\
 375  *
 376  *
 377  * Examples:
 378  *
 379  *      darray(int)  arr;
 380  *      int        *i;
 381  *
 382  *      darray_appends(arr, 0,1,2,3,4);
 383  *      darray_appends(arr, -5,-4,-3,-2,-1);
 384  *      darray_foreach(i, arr)
 385  *              printf("%d ", *i);
 386  *      printf("\n");
 387  *
 388  *      darray_free(arr);
 389  *
 390  *
 391  *      typedef struct {int n,d;} Fraction;
 392  *      darray(Fraction) fractions;
 393  *      Fraction        *i;
 394  *
 395  *      darray_appends(fractions, {3,4}, {3,5}, {2,1});
 396  *      darray_foreach(i, fractions)
 397  *              printf("%d/%d\n", i->n, i->d);
 398  *
 399  *      darray_free(fractions);
 400  */