Documentation/technical/api-argv-array.txt

   1 argv-array API
   2 ==============
   3
   4 The argv-array API allows one to dynamically build and store
   5 NULL-terminated lists.  An argv-array maintains the invariant that the
   6 `argv` member always points to a non-NULL array, and that the array is
   7 always NULL-terminated at the element pointed to by `argv[argc]`. This
   8 makes the result suitable for passing to functions expecting to receive
   9 argv from main(), or the link:api-run-command.html[run-command API].
  10
  11 The string-list API (documented in string-list.h) is similar, but cannot be
  12 used for these purposes; instead of storing a straight string pointer,
  13 it contains an item structure with a `util` field that is not compatible
  14 with the traditional argv interface.
  15
  16 Each `argv_array` manages its own memory. Any strings pushed into the
  17 array are duplicated, and all memory is freed by argv_array_clear().
  18
  19 Data Structures
  20 ---------------
  21
  22 `struct argv_array`::
  23
  24         A single array. This should be initialized by assignment from
  25         `ARGV_ARRAY_INIT`, or by calling `argv_array_init`. The `argv`
  26         member contains the actual array; the `argc` member contains the
  27         number of elements in the array, not including the terminating
  28         NULL.
  29
  30 Functions
  31 ---------
  32
  33 `argv_array_init`::
  34         Initialize an array. This is no different than assigning from
  35         `ARGV_ARRAY_INIT`.
  36
  37 `argv_array_push`::
  38         Push a copy of a string onto the end of the array.
  39
  40 `argv_array_pushl`::
  41         Push a list of strings onto the end of the array. The arguments
  42         should be a list of `const char *` strings, terminated by a NULL
  43         argument.
  44
  45 `argv_array_pushf`::
  46         Format a string and push it onto the end of the array. This is a
  47         convenience wrapper combining `strbuf_addf` and `argv_array_push`.
  48
  49 `argv_array_pushv`::
  50         Push a null-terminated array of strings onto the end of the array.
  51
  52 `argv_array_pop`::
  53         Remove the final element from the array. If there are no
  54         elements in the array, do nothing.
  55
  56 `argv_array_clear`::
  57         Free all memory associated with the array and return it to the
  58         initial, empty state.
  59
  60 `argv_array_detach`::
  61         Disconnect the `argv` member from the `argv_array` struct and
  62         return it. The caller is responsible for freeing the memory used
  63         by the array, and by the strings it references. After detaching,
  64         the `argv_array` is in a reinitialized state and can be pushed
  65         into again.