array(3)

NAME
array - The array library interface

SYNTAX
#include <libowfat/array.h>

DESCRIPTION
An allocated array variable keeps track of

•   a (nonzero) pointer to a dynamically allocated region of memory;

•   the number of bytes allocated (always positive); and

•   the number of bytes initialized (between 0 and the number of bytes allocated).

There are two other possibilities for the state of an array variable: unallocated and failed. In both cases, there is no dynamically allocated region of memory. A new array variable is normally created as a static variable:
  #include <libowfat/array.h>
  static array x; At this point it is unallocated. The array library provides various allocation and inspection functions. A new array variable can also be created dynamically. It must be initialized to all-0, meaning unallocated, before it is given to any of the array functions. It must be returned to the unallocated (or failed) state, for example with array_reset, before it is destroyed. These rules prevent all memory leaks.

Expansion and inspection
  array x;
  t* p1 = array_allocate(&x,sizeof(t),pos);
  t* p2 = array_get(&x,sizeof(t),pos);
  t* p3 = array_start(&x);
  int64 len = array_length(&x,sizeof(t));
  int64 bytes = array_bytes(&x);

Truncation and deallocation
  array x;
  array_truncate(&x,sizeof(t),len);
  array_trunc(&x);
  array_reset(&x);
  array_fail(&x);

Comparison
  array x;
  array y;
  if (array_equal(&x,&y))
    /* arrays are equal... */

Concatenation
  array x;
  array y;
  array_cat(&x,&y);
  array_catb(&x,"fnord",5);
  array_cats(&x,"fnord");
  array_cats0(&x,"fnord"); /* also append the \0 */
  array_cat0(&x); /* append \0 */
  array_cate(&x,"fnord",1,4); /* append "nor" */

ORIGINAL API DEFINITION
http://cr.yp.to/lib/array.html

SEE ALSO
array_get(3), array_start(3), array_fail(3)