Array Functions (The GNU Awk User’s Guide)
Next: Flattening Arrays, Previous: Array Data Types, Up: Array Manipulation [Contents][Index]
17.4.11.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 isindex
.wanted
specifies the type of value you wish to retrieve. Return false ifwanted
does not match the actual type or ifindex
is not in the array (see Table 17.2).The value for
index
can be numeric, in which casegawk
converts it to a string. Using nonintegral values is possible, but requires that you understand how such values are converted to strings (see section Conversion of Strings and Numbers); thus, using integral values is safest.As with all strings passed into
gawk
from an extension, the string value ofindex
must come fromgawk_malloc()
,gawk_calloc()
, orgawk_realloc()
, andgawk
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 byindex
. TheARGV
andENVIRON
arrays may not be changed, although thePROCINFO
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 theindex
andvalue
fromelement
. 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. See section How To Create and Populate 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 thedelete
statement (see section The delete Statement). 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 anawk_flat_array_t
structure and fill it in with indices and values of the requested types. Set the pointer whose address is passed asdata
to point to this structure. Return true upon success, or false otherwise. See section Working With All The Elements of an Array, 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 anawk_flat_array_t
structure and fill it in withAWK_STRING
indices andAWK_UNDEFINED
values. This is superseded byflatten_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.
Next: Flattening Arrays, Previous: Array Data Types, Up: Array Manipulation [Contents][Index]