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
  29 /*
  30  * SYNOPSIS
  31  *
  32  * Life cycle of a darray (dynamically-allocated array):
  33  *
  34  *     darray(int) a = darray_new();
  35  *     darray_free(a);
  36  *
  37  *     struct {darray(int) a;} foo;
  38  *     darray_init(foo.a);
  39  *     darray_free(foo.a);
  40  *
  41  * Typedefs for darrays of common types:
  42  *
  43  *     darray_char, darray_schar, darray_uchar
  44  *     darray_short, darray_int, darray_long
  45  *     darray_ushort, darray_uint, darray_ulong
  46  *
  47  * Access:
  48  *
  49  *     T      darray_item(darray(T) arr, size_t index);
  50  *     size_t darray_size(darray(T) arr);
  51  *     size_t darray_alloc(darray(T) arr);
  52  *     bool   darray_empty(darray(T) arr);
  53  *
  54  *     // Access raw memory, starting from the item in offset.
  55  *     // Not safe, be careful, etc.
  56  *     T*     darray_mem(darray(T) arr, size_t offset);
  57  *
  58  * Insertion (single item):
  59  *
  60  *     void   darray_append(darray(T) arr, T item);
  61  *     void   darray_prepend(darray(T) arr, T item);
  62  *     void   darray_push(darray(T) arr, T item); // same as darray_append
  63  *
  64  * Insertion (multiple items):
  65  *
  66  *     void   darray_append_items(darray(T) arr, T *items, size_t count);
  67  *     void   darray_prepend_items(darray(T) arr, T *items, size_t count);
  68  *
  69  *     void   darray_appends(darray(T) arr, [T item, [...]]);
  70  *     void   darray_prepends(darray(T) arr, [T item, [...]]);
  71  *
  72  * Removal:
  73  *
  74  *     T      darray_pop(darray(T) arr | darray_size(arr) != 0);
  75  *     T*     darray_pop_check(darray(T*) arr);
  76  *
  77  * Replacement:
  78  *
  79  *     void   darray_from_items(darray(T) arr, T *items, size_t count);
  80  *     void   darray_from_c(darray(T) arr, T c_array[N]);
  81  *
  82  * String buffer:
  83  *
  84  *     void   darray_append_string(darray(char) arr, const char *str);
  85  *     void   darray_append_lit(darray(char) arr, char stringLiteral[N+1]);
  86  *
  87  *     void   darray_prepend_string(darray(char) arr, const char *str);
  88  *     void   darray_prepend_lit(darray(char) arr, char stringLiteral[N+1]);
  89  *
  90  *     void   darray_from_string(darray(T) arr, const char *str);
  91  *     void   darray_from_lit(darray(char) arr, char stringLiteral[N+1]);
  92  *
  93  * Size management:
  94  *
  95  *     void   darray_resize(darray(T) arr, size_t newSize);
  96  *     void   darray_resize0(darray(T) arr, size_t newSize);
  97  *
  98  *     void   darray_realloc(darray(T) arr, size_t newAlloc);
  99  *     void   darray_growalloc(darray(T) arr, size_t newAlloc);
 100  *
 101  * Traversal:
 102  *
 103  *     darray_foreach(T *&i, darray(T) arr) {...}
 104  *     darray_foreach_reverse(T *&i, darray(T) arr) {...}
 105  *
 106  * Except for darray_foreach and darray_foreach_reverse,
 107  * all macros evaluate their non-darray arguments only once.
 108  */
 109
 110 /*** Life cycle ***/
 111
 112 #define darray(type) struct { type *item; size_t size; size_t alloc; }
 113
 114 #define darray_new() { 0, 0, 0 }
 115
 116 #define darray_init(arr) do { \
 117     (arr).item = 0; (arr).size = 0; (arr).alloc = 0; \
 118 } while (0)
 119
 120 #define darray_free(arr) do { \
 121     free((arr).item); darray_init(arr); \
 122 } while (0)
 123
 124 /*
 125  * Typedefs for darrays of common types.  These are useful
 126  * when you want to pass a pointer to an darray(T) around.
 127  *
 128  * The following will produce an incompatible pointer warning:
 129  *
 130  *     void foo(darray(int) *arr);
 131  *     darray(int) arr = darray_new();
 132  *     foo(&arr);
 133  *
 134  * The workaround:
 135  *
 136  *     void foo(darray_int *arr);
 137  *     darray_int arr = darray_new();
 138  *     foo(&arr);
 139  */
 140
 141 typedef darray (char)           darray_char;
 142 typedef darray (signed char)    darray_schar;
 143 typedef darray (unsigned char)  darray_uchar;
 144
 145 typedef darray (short)          darray_short;
 146 typedef darray (int)            darray_int;
 147 typedef darray (long)           darray_long;
 148
 149 typedef darray (unsigned short) darray_ushort;
 150 typedef darray (unsigned int)   darray_uint;
 151 typedef darray (unsigned long)  darray_ulong;
 152
 153 /*** Access ***/
 154
 155 #define darray_item(arr, i)     ((arr).item[i])
 156 #define darray_size(arr)        ((arr).size)
 157 #define darray_alloc(arr)       ((arr).alloc)
 158 #define darray_empty(arr)       ((arr).size == 0)
 159
 160 #define darray_mem(arr, offset) ((arr).item + (offset))
 161 #define darray_same(arr1, arr2) ((arr1).item == (arr2).item)
 162
 163 /*** Insertion (single item) ***/
 164
 165 #define darray_append(arr, ...)  do { \
 166     darray_resize(arr, (arr).size + 1); \
 167     (arr).item[(arr).size - 1] = (__VA_ARGS__); \
 168 } while (0)
 169
 170 #define darray_prepend(arr, ...) do { \
 171     darray_resize(arr, (arr).size + 1); \
 172     memmove((arr).item + 1, (arr).item, \
 173             ((arr).size - 1) * sizeof(*(arr).item)); \
 174     (arr).item[0] = (__VA_ARGS__); \
 175 } while (0)
 176
 177 #define darray_push(arr, ...) darray_append(arr, __VA_ARGS__)
 178
 179 /*** Insertion (multiple items) ***/
 180
 181 #define darray_append_items(arr, items, count) do { \
 182     size_t __count = (count), __oldSize = (arr).size; \
 183     darray_resize(arr, __oldSize + __count); \
 184     memcpy((arr).item + __oldSize, items, __count * sizeof(*(arr).item)); \
 185 } while (0)
 186
 187 #define darray_prepend_items(arr, items, count) do { \
 188     size_t __count = (count), __oldSize = (arr).size; \
 189     darray_resize(arr, __count + __oldSize); \
 190     memmove((arr).item + __count, (arr).item, \
 191             __oldSize * sizeof(*(arr).item)); \
 192     memcpy((arr).item, items, __count * sizeof(*(arr).item)); \
 193 } while (0)
 194
 195 #define darray_append_items_nullterminate(arr, items, count) do { \
 196     size_t __count = (count), __oldSize = (arr).size; \
 197     darray_resize(arr, __oldSize + __count + 1); \
 198     memcpy((arr).item + __oldSize, items, __count * sizeof(*(arr).item)); \
 199     (arr).item[--(arr).size] = 0; \
 200 } while (0)
 201
 202 #define darray_prepend_items_nullterminate(arr, items, count) do { \
 203     size_t __count = (count), __oldSize = (arr).size; \
 204     darray_resize(arr, __count + __oldSize + 1); \
 205     memmove((arr).item + __count, (arr).item, \
 206             __oldSize * sizeof(*(arr).item)); \
 207     memcpy((arr).item, items, __count * sizeof(*(arr).item)); \
 208     (arr).item[--(arr).size] = 0; \
 209 } while (0)
 210
 211 #define darray_appends_t(arr, type, ...)  do { \
 212     type __src[] = { __VA_ARGS__ }; \
 213     darray_append_items(arr, __src, sizeof(__src) / sizeof(*__src)); \
 214 } while (0)
 215
 216 #define darray_prepends_t(arr, type, ...) do { \
 217     type __src[] = { __VA_ARGS__ }; \
 218     darray_prepend_items(arr, __src, sizeof(__src) / sizeof(*__src)); \
 219 } while (0)
 220
 221 #define darray_appends(arr, ...) \
 222     darray_appends_t(arr, typeof((*(arr).item)), __VA_ARGS__)
 223
 224 #define darray_prepends(arr, ...) \
 225     darray_prepends_t(arr, typeof((*(arr).item)), __VA_ARGS__)
 226
 227 /*** Removal ***/
 228
 229 /* Warning: Do not call darray_pop on an empty darray. */
 230 #define darray_pop(arr) ((arr).item[--(arr).size])
 231 #define darray_pop_check(arr) ((arr).size ? darray_pop(arr) : NULL)
 232
 233 /*** Replacement ***/
 234
 235 #define darray_from_items(arr, items, count) do { \
 236     size_t __count = (count); \
 237     darray_resize(arr, __count); \
 238     memcpy((arr).item, items, __count * sizeof(*(arr).item)); \
 239 } while (0)
 240
 241 #define darray_from_c(arr, c_array) \
 242     darray_from_items(arr, c_array, sizeof(c_array) / sizeof(*(c_array)))
 243
 244 #define darray_copy(arr_to, arr_from) \
 245     darray_from_items((arr_to), (arr_from).item, (arr_from).size)
 246
 247 /*** String buffer ***/
 248
 249 #define darray_append_string(arr, str) do { \
 250     const char *__str = (str); \
 251     darray_append_items(arr, __str, strlen(__str) + 1); \
 252     (arr).size--; \
 253 } while (0)
 254
 255 #define darray_append_lit(arr, stringLiteral) do { \
 256     darray_append_items(arr, stringLiteral, sizeof(stringLiteral)); \
 257     (arr).size--; \
 258 } while (0)
 259
 260 #define darray_prepend_string(arr, str) do { \
 261     const char *__str = (str); \
 262     darray_prepend_items_nullterminate(arr, __str, strlen(__str)); \
 263 } while (0)
 264
 265 #define darray_prepend_lit(arr, stringLiteral) \
 266     darray_prepend_items_nullterminate(arr, stringLiteral, \
 267                                        sizeof(stringLiteral) - 1)
 268
 269 #define darray_from_string(arr, str) do { \
 270     const char *__str = (str); \
 271     darray_from_items(arr, __str, strlen(__str) + 1); \
 272     (arr).size--; \
 273 } while (0)
 274
 275 #define darray_from_lit(arr, stringLiteral) do { \
 276     darray_from_items(arr, stringLiteral, sizeof(stringLiteral)); \
 277     (arr).size--; \
 278 } while (0)
 279
 280 /*** Size management ***/
 281
 282 #define darray_resize(arr, newSize) \
 283     darray_growalloc(arr, (arr).size = (newSize))
 284
 285 #define darray_resize0(arr, newSize) do { \
 286     size_t __oldSize = (arr).size, __newSize = (newSize); \
 287     (arr).size = __newSize; \
 288     if (__newSize > __oldSize) { \
 289         darray_growalloc(arr, __newSize); \
 290         memset(&(arr).item[__oldSize], 0, \
 291                (__newSize - __oldSize) * sizeof(*(arr).item)); \
 292     } \
 293 } while (0)
 294
 295 #define darray_realloc(arr, newAlloc) do { \
 296     (arr).item = realloc((arr).item, \
 297                          ((arr).alloc = (newAlloc)) * sizeof(*(arr).item)); \
 298 } while (0)
 299
 300 #define darray_growalloc(arr, need)   do { \
 301     size_t __need = (need); \
 302     if (__need > (arr).alloc) \
 303     darray_realloc(arr, darray_next_alloc((arr).alloc, __need)); \
 304 } while (0)
 305
 306 static inline size_t
 307 darray_next_alloc(size_t alloc, size_t need)
 308 {
 309     if (alloc == 0)
 310         alloc = 4;
 311     while (alloc < need)
 312         alloc *= 2;
 313     return alloc;
 314 }
 315
 316 /*** Traversal ***/
 317
 318 /*
 319  * darray_foreach(T *&i, darray(T) arr) {...}
 320  *
 321  * Traverse a darray.  `i` must be declared in advance as a pointer to an item.
 322  */
 323 #define darray_foreach(i, arr) \
 324     for ((i) = &(arr).item[0]; (i) < &(arr).item[(arr).size]; (i)++)
 325
 326 #define darray_foreach_from(i, arr, from) \
 327     for ((i) = &(arr).item[from]; (i) < &(arr).item[(arr).size]; (i)++)
 328
 329 /*
 330  * darray_foreach_reverse(T *&i, darray(T) arr) {...}
 331  *
 332  * Like darray_foreach, but traverse in reverse order.
 333  */
 334 #define darray_foreach_reverse(i, arr) \
 335     for ((i) = &(arr).item[(arr).size]; (i)-- > &(arr).item[0]; )
 336
 337 #endif /* CCAN_DARRAY_H */
 338
 339 /*
 340  *
 341  * darray_growalloc(arr, newAlloc) sees if the darray can currently hold newAlloc items;
 342  *      if not, it increases the alloc to satisfy this requirement, allocating slack
 343  *      space to avoid having to reallocate for every size increment.
 344  *
 345  * darray_from_string(arr, str) copies a string to an darray_char.
 346  *
 347  * darray_push(arr, item) pushes an item to the end of the darray.
 348  * darray_pop(arr) pops it back out.  Be sure there is at least one item in the darray before calling.
 349  * darray_pop_check(arr) does the same as darray_pop, but returns NULL if there are no more items left in the darray.
 350  *
 351  * 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.
 352  * Currently requires HAVE_STATEMENT_EXPR, but I plan to remove this dependency by creating an inline function.
 353  *
 354  * The following require HAVE_TYPEOF==1 :
 355  *
 356  * darray_appends(arr, item0, item1...) appends a collection of comma-delimited items to the darray.
 357  * darray_prepends(arr, item0, item1...) prepends a collection of comma-delimited items to the darray.\
 358  *
 359  *
 360  * Examples:
 361  *
 362  *      darray(int)  arr;
 363  *      int        *i;
 364  *
 365  *      darray_appends(arr, 0,1,2,3,4);
 366  *      darray_appends(arr, -5,-4,-3,-2,-1);
 367  *      darray_foreach(i, arr)
 368  *              printf("%d ", *i);
 369  *      printf("\n");
 370  *
 371  *      darray_free(arr);
 372  *
 373  *
 374  *      typedef struct {int n,d;} Fraction;
 375  *      darray(Fraction) fractions;
 376  *      Fraction        *i;
 377  *
 378  *      darray_appends(fractions, {3,4}, {3,5}, {2,1});
 379  *      darray_foreach(i, fractions)
 380  *              printf("%d/%d\n", i->n, i->d);
 381  *
 382  *      darray_free(fractions);
 383  */