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