17.4.12.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 opaque105 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.

awk_value_t index;
awk_value_t 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.


Footnotes

(105)

It is also a “cookie,” but the gawk developers did not wish to overuse this term.