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

17.4.12.2 Array Functions
.........................

The following functions relate to individual array elements:

'awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count);'
     For the array represented by 'a_cookie', place in '*count' the
     number of elements it contains.  A subarray counts as a single
     element.  Return false if there is an error.

'awk_bool_t get_array_element(awk_array_t a_cookie,'
'                             const awk_value_t *const index,'
'                             awk_valtype_t wanted,'
'                             awk_value_t *result);'
     For the array represented by 'a_cookie', return in '*result' the
     value of the element whose index is 'index'.  'wanted' specifies
     the type of value you wish to retrieve.  Return false if 'wanted'
     does not match the actual type or if 'index' is not in the array
     (*note Table 17.2: table-value-types-returned.).

     The value for 'index' can be numeric, in which case 'gawk' converts
     it to a string.  Using nonintegral values is possible, but requires
     that you understand how such values are converted to strings (*note
     Conversion::); thus, using integral values is safest.

     As with _all_ strings passed into 'gawk' from an extension, the
     string value of 'index' must come from 'gawk_malloc()',
     'gawk_calloc()', or 'gawk_realloc()', and 'gawk' releases the
     storage.

'awk_bool_t set_array_element(awk_array_t a_cookie,'
'                             const awk_value_t *const index,'
'                             const awk_value_t *const value);'
     In the array represented by 'a_cookie', create or modify the
     element whose index is given by 'index'.  The 'ARGV' and 'ENVIRON'
     arrays may not be changed, although the 'PROCINFO' array can be.

'awk_bool_t set_array_element_by_elem(awk_array_t a_cookie,'
'                                     awk_element_t element);'
     Like 'set_array_element()', but take the 'index' and 'value' from
     'element'.  This is a convenience macro.

'awk_bool_t del_array_element(awk_array_t a_cookie,'
'                             const awk_value_t* const index);'
     Remove the element with the given index from the array represented
     by 'a_cookie'.  Return true if the element was removed, or false if
     the element did not exist in the array.

   The following functions relate to arrays as a whole:

'awk_array_t create_array(void);'
     Create a new array to which elements may be added.  *Note Creating
     Arrays:: for a discussion of how to create a new array and add
     elements to it.

'awk_bool_t clear_array(awk_array_t a_cookie);'
     Clear the array represented by 'a_cookie'.  Return false if there
     was some kind of problem, true otherwise.  The array remains an
     array, but after calling this function, it has no elements.  This
     is equivalent to using the 'delete' statement (*note Delete::).

'awk_bool_t destroy_array(awk_array_t a_cookie);'
     Clear the array represented by 'a_cookie' and release the array
     allocated by 'create_array'.  Return false if there was some kind
     of problem, true otherwise.  The array will no longer exist and
     cannot be used again.

'awk_bool_t flatten_array_typed(awk_array_t a_cookie,'
'                               awk_flat_array_t **data,'
'                               awk_valtype_t index_type,'
'                               awk_valtype_t value_type);'
     For the array represented by 'a_cookie', create an
     'awk_flat_array_t' structure and fill it in with indices and values
     of the requested types.  Set the pointer whose address is passed as
     'data' to point to this structure.  Return true upon success, or
     false otherwise.  *Note Flattening Arrays::, for a discussion of
     how to flatten an array and work with it.

'awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);'
     For the array represented by 'a_cookie', create an
     'awk_flat_array_t' structure and fill it in with 'AWK_STRING'
     indices and 'AWK_UNDEFINED' values.  This is superseded by
     'flatten_array_typed()'.  It is provided as a macro, and remains
     for convenience and for source code compatibility with the previous
     version of the API.

'awk_bool_t release_flattened_array(awk_array_t a_cookie,'
'                                   awk_flat_array_t *data);'
     When done with a flattened array, release the storage using this
     function.  You must pass in both the original array cookie and the
     address of the created 'awk_flat_array_t' structure.  The function
     returns true upon success, false otherwise.