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