17.4.11.1 Array Data Types

The data types associated with arrays are as follows:

typedef void *awk_array_t;

If you request the value of an array variable, you get back an awk_array_t value. This value is opaque¹¹¹ to the extension; it uniquely identifies the array but can only be used by passing it into API functions or receiving it from API functions. This is very similar to way ‘FILE *’ values are used with the <stdio.h> library routines.

typedef struct awk_element {

    /* convenience linked list pointer, not used by gawk */

    struct awk_element *next;

    enum {

        AWK_ELEMENT_DEFAULT = 0,  /* set by gawk */

        AWK_ELEMENT_DELETE = 1    /* set by extension */

    } flags;

    awk_value_t index;

    awk_value_t value;

} awk_element_t;

The awk_element_t is a “flattened” array element. awk produces an array of these inside the awk_flat_array_t (see the next item). Individual elements may be marked for deletion. New elements must be added individually, one at a time, using the separate API for that purpose. The fields are as follows:

struct awk_element *next;

This pointer is for the convenience of extension writers. It allows an extension to create a linked list of new elements that can then be added to an array in a loop that traverses the list.

enum { … } flags;

A set of flag values that convey information between the extension and gawk. Currently there is only one: AWK_ELEMENT_DELETE. Setting it causes gawk to delete the element from the original array upon release of the flattened array.

index

value

The index and value of the element, respectively. All memory pointed to by index and value belongs to gawk.

typedef struct awk_flat_array {

    awk_const void *awk_const opaque1;    /* for use by gawk */

    awk_const void *awk_const opaque2;    /* for use by gawk */

    awk_const size_t count;     /* how many elements */

    awk_element_t elements[1];  /* will be extended */

} awk_flat_array_t;

This is a flattened array. When an extension gets one of these from gawk, the elements array is of actual size count. The opaque1 and opaque2 pointers are for use by gawk; therefore they are marked awk_const so that the extension cannot modify them.