gawk: Constructor Functions

1 
1 16.4.4 Constructor Functions
1 ----------------------------
1 
1 The API provides a number of "constructor" functions for creating string
1 and numeric values, as well as a number of convenience macros.  This
1 node presents them all as function prototypes, in the way that extension
1 code would use them:
1 
1 'static inline awk_value_t *'
1 'make_const_string(const char *string, size_t length, awk_value_t *result);'
1      This function creates a string value in the 'awk_value_t' variable
1      pointed to by 'result'.  It expects 'string' to be a C string
1      constant (or other string data), and automatically creates a _copy_
1      of the data for storage in 'result'.  It returns 'result'.
1 
1 'static inline awk_value_t *'
1 'make_malloced_string(const char *string, size_t length, awk_value_t *result);'
1      This function creates a string value in the 'awk_value_t' variable
1      pointed to by 'result'.  It expects 'string' to be a 'char *' value
1      pointing to data previously obtained from 'gawk_malloc()',
1      'gawk_calloc()', or 'gawk_realloc()'.  The idea here is that the
1      data is passed directly to 'gawk', which assumes responsibility for
1      it.  It returns 'result'.
1 
1 'static inline awk_value_t *'
1 'make_null_string(awk_value_t *result);'
1      This specialized function creates a null string (the "undefined"
1      value) in the 'awk_value_t' variable pointed to by 'result'.  It
1      returns 'result'.
1 
1 'static inline awk_value_t *'
1 'make_number(double num, awk_value_t *result);'
1      This function simply creates a numeric value in the 'awk_value_t'
1      variable pointed to by 'result'.
1 
1 'static inline awk_value_t *'
1 'make_number_mpz(void *mpz, awk_value_t *result);'
1      This function creates a GMP number value in 'result'.  The 'mpz'
1      must be from a call to 'get_mpz_ptr()' (and thus be of real
1      underlying type 'mpz_ptr').  'gawk' takes ownership of this memory.
1 
1 'static inline awk_value_t *'
1 'make_number_mpfr(void *mpfr, awk_value_t *result);'
1      This function creates an MPFR number value in 'result'.  The 'mpfr'
1      must be from a call to 'get_mpfr_ptr()'.  (and thus be of real
1      underlying type 'mpfr_ptr') 'gawk' takes ownership of this memory.
1 
1 'static inline awk_value_t *'
1 'make_const_user_input(const char *string, size_t length, awk_value_t *result);'
1      This function is identical to 'make_const_string()', but the string
1      is flagged as user input that should be treated as a strnum value
1      if the contents of the string are numeric.
1 
1 'static inline awk_value_t *'
1 'make_malloced_user_input(const char *string, size_t length, awk_value_t *result);'
1      This function is identical to 'make_malloced_string()', but the
1      string is flagged as user input that should be treated as a strnum
1      value if the contents of the string are numeric.
1 
1 'static inline awk_value_t *'
1 'make_const_regex(const char *string, size_t length, awk_value_t *result);'
1      This function creates a strongly typed regexp value by allocating a
1      copy of the string.  'string' is the regular expression of length
1      'len'.
1 
1 'static inline awk_value_t *'
1 'make_malloced_regex(const char *string, size_t length, awk_value_t *result);'
1      This function creates a strongly typed regexp value.  'string' is
1      the regular expression of length 'len'.  It expects 'string' to be
1      a 'char *' value pointing to data previously obtained from
1      'gawk_malloc()', 'gawk_calloc()', or 'gawk_realloc()'.
1