Requesting Values (The GNU Awk User’s Guide)

Next: Accessing and Updating Parameters, Previous: Updating ERRNO, Up: API Description [Contents][Index]

17.4.9 Requesting Values ¶

All of the functions that return values from gawk work in the same way. You pass in an awk_valtype_t value to indicate what kind of value you expect. If the actual value matches what you requested, the function returns true and fills in the awk_value_t result. Otherwise, the function returns false, and the val_type member indicates the type of the actual value. You may then print an error message or reissue the request for the actual value type, as appropriate. This behavior is summarized in Table 17.2.

	Type of Actual Value

		String	Strnum	Number	Regex	Bool	Array	Undefined
	String	String	String	String	String	String	false	false
	Strnum	false	Strnum	Strnum	false	false	false	false
	Number	Number	Number	Number	false	Number	false	false
Type	Regex	false	false	false	Regex	false	false	false
Requested	Bool	false	false	false	false	Bool	false	false
	Array	false	false	false	false	false	Array	false
	Scalar	Scalar	Scalar	Scalar	Scalar	Scalar	false	false
	Undefined	String	Strnum	Number	Regex	Bool	Array	Undefined
	Value cookie	false	false	false	false	false	false	false

Table 17.2: API value types returned

There are a number of points of note:

A request for AWK_UNDEFINED always returns true, filling in the actual type of the particular value. You can think of this as a sort of “wildcard” request.
Requesting an AWK_STRING causes gawk to convert any scalar value to a string result, and that is what is returned.
Requesting an AWK_NUMBER causes gawk to convert any scalar value, except for a regexp, to a numeric result, and that is what is returned.
Conversion between string and number in the API thus parallels how gawk behaves in running code.
The API functions do not distinguish between "undefined" and "unassigned" as returned by typeof() (see Dynamic Typing In gawk). AWK_UNDEFINED serves for both. This is unlikely to change, as the documentation and code are already complicated enough.