manpagez: man pages & more
info gawk
Home | html | info | man

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.
 
© manpagez.com 2000-2018
Individual documents may contain additional copyright information.