File: gawk.info,  Node: Constructor Functions,  Next: API Ownership of MPFR and GMP Values,  Prev: Memory Allocation Functions,  Up: Extension API Description

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
node 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').

'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()'.

'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()'.

'static inline awk_value_t *'
'make_bool(awk_bool_t boolval, awk_value_t *result);'
     This function creates a boolean value in the 'awk_value_t' variable
     pointed to by 'result'.