File: gawk.info,  Node: Array Data Types,  Next: Array Functions,  Up: Array Manipulation

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 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 ''
     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.