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