gawk: Array Data Types
16.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(1) 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.
---------- Footnotes ----------
(1) It is also a "cookie," but the 'gawk' developers did not wish to
overuse this term.
Info Catalog
gawk: Array Manipulation
gawk: Array Functions