17.4.4 Constructor Functions

The API provides a number of constructor functions for creating string and numeric values, as well as a number of convenience macros. This subsection presents them all as function prototypes, in the way that extension code would use them:

static inline awk_value_t *

make_const_string(const char *string, size_t length, awk_value_t *result);

This function creates a string value in the awk_value_t variable pointed to by result. It expects string to be a C string constant (or other string data), and automatically creates a copy of the data for storage in result. It returns result.

static inline awk_value_t *

make_malloced_string(const char *string, size_t length, awk_value_t *result);

This function creates a string value in the awk_value_t variable pointed to by result. It expects string to be a ‘char *’ value pointing to data previously obtained from gawk_malloc(), gawk_calloc(), or gawk_realloc(). The idea here is that the data is passed directly to gawk, which assumes responsibility for it. It returns result.

static inline awk_value_t *

make_null_string(awk_value_t *result);

This specialized function creates a null string (the “undefined” value) in the awk_value_t variable pointed to by result. It returns result.

static inline awk_value_t *

make_number(double num, awk_value_t *result);

This function simply creates a numeric value in the awk_value_t variable pointed to by result.

static inline awk_value_t *

make_number_mpz(void *mpz, awk_value_t *result);

This function creates a GMP number value in result. The mpz must be from a call to get_mpz_ptr() (and thus be of real underlying type mpz_ptr). gawk takes ownership of this memory.

static inline awk_value_t *

make_number_mpfr(void *mpfr, awk_value_t *result);

This function creates an MPFR number value in result. The mpfr must be from a call to get_mpfr_ptr(). (and thus be of real underlying type mpfr_ptr) gawk takes ownership of this memory.

static inline awk_value_t *

make_const_user_input(const char *string, size_t length, awk_value_t *result);

This function is identical to make_const_string(), but the string is flagged as user input that should be treated as a strnum value if the contents of the string are numeric.

static inline awk_value_t *

make_malloced_user_input(const char *string, size_t length, awk_value_t *result);

This function is identical to make_malloced_string(), but the string is flagged as user input that should be treated as a strnum value if the contents of the string are numeric.

static inline awk_value_t *

make_const_regex(const char *string, size_t length, awk_value_t *result);

This function creates a strongly typed regexp value by allocating a copy of the string. string is the regular expression of length len.

static inline awk_value_t *

make_malloced_regex(const char *string, size_t length, awk_value_t *result);

This function creates a strongly typed regexp value. string is the regular expression of length len. It expects string to be a ‘char *’ value pointing to data previously obtained from gawk_malloc(), gawk_calloc(), or gawk_realloc().