gawk: Array Data Types
1
1 16.4.11.1 Array Data Types
1 ..........................
1
1 The data types associated with arrays are as follows:
1
1 'typedef void *awk_array_t;'
1 If you request the value of an array variable, you get back an
1 'awk_array_t' value. This value is opaque(1) to the extension; it
1 uniquely identifies the array but can only be used by passing it
1 into API functions or receiving it from API functions. This is
1 very similar to way 'FILE *' values are used with the '<stdio.h>'
1 library routines.
1
1 'typedef struct awk_element {'
1 ' /* convenience linked list pointer, not used by gawk */'
1 ' struct awk_element *next;'
1 ' enum {'
1 ' AWK_ELEMENT_DEFAULT = 0, /* set by gawk */'
1 ' AWK_ELEMENT_DELETE = 1 /* set by extension */'
1 ' } flags;'
1 ' awk_value_t index;'
1 ' awk_value_t value;'
1 '} awk_element_t;'
1 The 'awk_element_t' is a "flattened" array element. 'awk' produces
1 an array of these inside the 'awk_flat_array_t' (see the next
1 item). Individual elements may be marked for deletion. New
1 elements must be added individually, one at a time, using the
1 separate API for that purpose. The fields are as follows:
1
1 'struct awk_element *next;'
1 This pointer is for the convenience of extension writers. It
1 allows an extension to create a linked list of new elements
1 that can then be added to an array in a loop that traverses
1 the list.
1
1 'enum { ... } flags;'
1 A set of flag values that convey information between the
1 extension and 'gawk'. Currently there is only one:
1 'AWK_ELEMENT_DELETE'. Setting it causes 'gawk' to delete the
1 element from the original array upon release of the flattened
1 array.
1
1 'index'
1 'value'
1 The index and value of the element, respectively. _All_
1 memory pointed to by 'index' and 'value' belongs to 'gawk'.
1
1 'typedef struct awk_flat_array {'
1 ' awk_const void *awk_const opaque1; /* for use by gawk */'
1 ' awk_const void *awk_const opaque2; /* for use by gawk */'
1 ' awk_const size_t count; /* how many elements */'
1 ' awk_element_t elements[1]; /* will be extended */'
1 '} awk_flat_array_t;'
1 This is a flattened array. When an extension gets one of these
1 from 'gawk', the 'elements' array is of actual size 'count'. The
1 'opaque1' and 'opaque2' pointers are for use by 'gawk'; therefore
1 they are marked 'awk_const' so that the extension cannot modify
1 them.
1
1 ---------- Footnotes ----------
1
1 (1) It is also a "cookie," but the 'gawk' developers did not wish to
1 overuse this term.
1