gawk: Array Functions

1 
1 16.4.11.2 Array Functions
1 .........................
1 
1 The following functions relate to individual array elements:
1 
1 'awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count);'
1      For the array represented by 'a_cookie', place in '*count' the
1      number of elements it contains.  A subarray counts as a single
1      element.  Return false if there is an error.
1 
1 'awk_bool_t get_array_element(awk_array_t a_cookie,'
1 '                             const awk_value_t *const index,'
1 '                             awk_valtype_t wanted,'
1 '                             awk_value_t *result);'
1      For the array represented by 'a_cookie', return in '*result' the
1      value of the element whose index is 'index'.  'wanted' specifies
1      the type of value you wish to retrieve.  Return false if 'wanted'
1      does not match the actual type or if 'index' is not in the array
1      (⇒Table 16.1 table-value-types-returned.).
1 
1      The value for 'index' can be numeric, in which case 'gawk' converts
1      it to a string.  Using nonintegral values is possible, but requires
11      that you understand how such values are converted to strings (⇒
      Conversion); thus, using integral values is safest.
1 
1      As with _all_ strings passed into 'gawk' from an extension, the
1      string value of 'index' must come from 'gawk_malloc()',
1      'gawk_calloc()', or 'gawk_realloc()', and 'gawk' releases the
1      storage.
1 
1 'awk_bool_t set_array_element(awk_array_t a_cookie,'
1 '                             const awk_value_t *const index,'
1 '                             const awk_value_t *const value);'
1      In the array represented by 'a_cookie', create or modify the
1      element whose index is given by 'index'.  The 'ARGV' and 'ENVIRON'
1      arrays may not be changed, although the 'PROCINFO' array can be.
1 
1 'awk_bool_t set_array_element_by_elem(awk_array_t a_cookie,'
1 '                                     awk_element_t element);'
1      Like 'set_array_element()', but take the 'index' and 'value' from
1      'element'.  This is a convenience macro.
1 
1 'awk_bool_t del_array_element(awk_array_t a_cookie,'
1 '                             const awk_value_t* const index);'
1      Remove the element with the given index from the array represented
1      by 'a_cookie'.  Return true if the element was removed, or false if
1      the element did not exist in the array.
1 
1    The following functions relate to arrays as a whole:
1 
1 'awk_array_t create_array(void);'
1      Arrays:: for a discussion of how to create a new array and add
1      elements to it.
1 
1 'awk_bool_t clear_array(awk_array_t a_cookie);'
1      Clear the array represented by 'a_cookie'.  Return false if there
1      was some kind of problem, true otherwise.  The array remains an
1      array, but after calling this function, it has no elements.  This
1      is equivalent to using the 'delete' statement (⇒Delete).
1 
1 'awk_bool_t flatten_array_typed(awk_array_t a_cookie,'
1 '                               awk_flat_array_t **data,'
1 '                               awk_valtype_t index_type,'
1 '                               awk_valtype_t value_type);'
1      For the array represented by 'a_cookie', create an
1      'awk_flat_array_t' structure and fill it in with indices and values
1      of the requested types.  Set the pointer whose address is passed as
1      'data' to point to this structure.  Return true upon success, or
1      false otherwise.  ⇒Flattening Arrays, for a discussion of
1      how to flatten an array and work with it.
1 
1 'awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);'
1      For the array represented by 'a_cookie', create an
1      'awk_flat_array_t' structure and fill it in with 'AWK_STRING'
1      indices and 'AWK_UNDEFINED' values.  This is superseded by
1      'flatten_array_typed()'.  It is provided as a macro, and remains
1      for convenience and for source code compatibility with the previous
1      version of the API.
1 
1 'awk_bool_t release_flattened_array(awk_array_t a_cookie,'
1 '                                   awk_flat_array_t *data);'
1      When done with a flattened array, release the storage using this
1      function.  You must pass in both the original array cookie and the
1      address of the created 'awk_flat_array_t' structure.  The function
1      returns true upon success, false otherwise.
1