---
name: "array"
section: "3diet"
platform: "linux"
package: "libowfat-dev"
version: "0.28-2"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/array/3diet"
---

# array(3diet)

The array library interface

## NAME

array - The array library interface

## SYNTAX

**#include \<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 "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_get/3.md), [array\_start(3)](/array_start/3.md), [array\_fail(3)](/array_fail/3.md)