Documentation / technical / api-allocation-growing.txton commit rev-list: disable object/refname ambiguity check with --stdin (4c30d50)
   1allocation growing API
   2======================
   3
   4Dynamically growing an array using realloc() is error prone and boring.
   5
   6Define your array with:
   7
   8* a pointer (`item`) that points at the array, initialized to `NULL`
   9  (although please name the variable based on its contents, not on its
  10  type);
  11
  12* an integer variable (`alloc`) that keeps track of how big the current
  13  allocation is, initialized to `0`;
  14
  15* another integer variable (`nr`) to keep track of how many elements the
  16  array currently has, initialized to `0`.
  17
  18Then before adding `n`th element to the item, call `ALLOC_GROW(item, n,
  19alloc)`.  This ensures that the array can hold at least `n` elements by
  20calling `realloc(3)` and adjusting `alloc` variable.
  21
  22------------
  23sometype *item;
  24size_t nr;
  25size_t alloc
  26
  27for (i = 0; i < nr; i++)
  28        if (we like item[i] already)
  29                return;
  30
  31/* we did not like any existing one, so add one */
  32ALLOC_GROW(item, nr + 1, alloc);
  33item[nr++] = value you like;
  34------------
  35
  36You are responsible for updating the `nr` variable.