aboutsummaryrefslogtreecommitdiffstats
path: root/doc/gawktexi.in
diff options
context:
space:
mode:
Diffstat (limited to 'doc/gawktexi.in')
-rw-r--r--doc/gawktexi.in95
1 files changed, 64 insertions, 31 deletions
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index f7f232a9..c1674c11 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -31574,7 +31574,8 @@ multibyte encoding.
@itemx @ @ @ @ AWK_ARRAY,
@itemx @ @ @ @ AWK_SCALAR,@ @ @ @ @ @ @ @ @ /* opaque access to a variable */
@itemx @ @ @ @ AWK_VALUE_COOKIE,@ @ @ /* for updating a previously created value */
-@itemx @ @ @ @ AWK_REGEX
+@itemx @ @ @ @ AWK_REGEX,
+@itemx @ @ @ @ AWK_STRNUM
@itemx @} awk_valtype_t;
This @code{enum} indicates the type of a value.
It is used in the following @code{struct}.
@@ -31594,6 +31595,7 @@ The @code{val_type} member indicates what kind of value the
@code{union} holds, and each member is of the appropriate type.
@item #define str_value@ @ @ @ @ @ u.s
+@itemx #define strnum_value@ @ @ @ str_value
@itemx #define regex_value@ @ @ @ str_value
@itemx #define num_value@ @ @ @ @ @ u.d
@itemx #define array_cookie@ @ @ u.a
@@ -31615,7 +31617,7 @@ and in more detail in @ref{Cached values}.
@end table
-Scalar values in @command{awk} are numbers, strings, or typed regexps. The
+Scalar values in @command{awk} are numbers, strings, strnums, or typed regexps. The
@code{awk_value_t} struct represents values. The @code{val_type} member
indicates what is in the @code{union}.
@@ -31624,6 +31626,12 @@ require more work. Because @command{gawk} allows embedded @sc{nul} bytes
in string values, a string must be represented as a pair containing a
data pointer and length. This is the @code{awk_string_t} type.
+A strnum (numeric string) value is represented as a string and consists
+of user input data that appears to be numeric.
+When an extension attempts to create a strnum value, a string flagged
+as user input is created. Subsequent parsing will determine whether it
+looks like a number and should be treated as a strnum or a regular string.
+
Typed regexp values (@pxref{Strong Regexp Constants}) are not of
much use to extension functions. Extension functions can tell that
they've received them, and create them for scalar values. Otherwise,
@@ -31798,9 +31806,29 @@ This function simply creates a numeric value in the @code{awk_value_t} variable
pointed to by @code{result}.
@item static inline awk_value_t *
-@itemx make_regex(const char *string, size_t length, awk_value_t *result);
+@itemx make_const_user_input(const char *string, size_t length, awk_value_t *result);
+This function is identical to @code{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.
+
+@item static inline awk_value_t *
+@itemx make_malloced_user_input(const char *string, size_t length, awk_value_t *result);
+This function is identical to @code{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.
+
+@item static inline awk_value_t *
+@itemx 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.
+@code{string} is the regular expression of length @code{len}.
+
+@item static inline awk_value_t *
+@itemx make_malloced_regex(const char *string, size_t length, awk_value_t *result);
This function creates a strongly typed regexp value.
@code{string} is the regular expression of length @code{len}.
+It expects @code{string} to be a @samp{char *}
+value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}.
+
@end table
@node Registration Functions
@@ -32584,29 +32612,28 @@ value type, as appropriate. This behavior is summarized in
@end ifnotplaintext
@ifplaintext
@example
- +-------------------------------------------------------------+
- | Type of Actual Value: |
- +------------+------------+-----------+-----------+-----------+
- | String | Number | Regex | Array | Undefined |
-+-----------+-----------+------------+------------+-----------+-----------+-----------+
-| | String | String | String | String | false | false |
-| +-----------+------------+------------+-----------+-----------+-----------+
-| | Number | Number if | Number | false | false | false |
-| | | can be | | | | |
-| | | converted, | | | | |
-| | | else false | | | | |
-| +-----------+------------+------------+-----------+-----------+-----------+
-| | Regex | false | false | Regex | false | false |
-| +-----------+------------+------------+-----------+-----------+-----------+
-| Type | Array | false | false | false | Array | false |
-| Requested +-----------+------------+------------+-----------+-----------+-----------+
-| | Scalar | Scalar | Scalar | Scalar | false | false |
-| +-----------+------------+------------+-----------+-----------+-----------+
-| | Undefined | String | Number | Regex | Array | Undefined |
-| +-----------+------------+------------+-----------+-----------+-----------+
-| | Value | false | false | false | false | false |
-| | Cookie | | | | | |
-+-----------+-----------+------------+------------+-----------+-----------+-----------+
+ +-------------------------------------------------------+
+ | Type of Actual Value: |
+ +--------+--------+--------+--------+-------+-----------+
+ | String | Strnum | Number | Regex | Array | Undefined |
++-----------+-----------+--------+--------+--------+--------+-------+-----------+
+| | String | String | String | String | String | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Strnum | false | Strnum | Strnum | false | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Number | Number | Number | Number | false | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Regex | false | false | false | Regex | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| Type | Array | false | false | false | false | Array | false |
+| Requested +-----------+--------+--------+--------+--------+-------+-----------+
+| | Scalar | Scalar | Scalar | Scalar | Scalar | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Undefined | String | Strnum | Number | Regex | Array | Undefined |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Value | false | false | false | false | false | false |
+| | Cookie | | | | | | |
++-----------+-----------+--------+--------+--------+--------+-------+-----------+
@end example
@end ifplaintext
@end float
@@ -32706,7 +32733,7 @@ Return false if the value cannot be retrieved.
@item awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value);
Update the value associated with a scalar cookie. Return false if
-the new value is not of type @code{AWK_STRING}, @code{AWK_REGEX}, or @code{AWK_NUMBER}.
+the new value is not of type @code{AWK_STRING}, @code{AWK_STRNUM}, @code{AWK_REGEX}, or @code{AWK_NUMBER}.
Here too, the predefined variables may not be updated.
@end table
@@ -32827,7 +32854,7 @@ is what the routines in this @value{SECTION} let you do. The functions are as f
@table @code
@item awk_bool_t create_value(awk_value_t *value, awk_value_cookie_t *result);
Create a cached string or numeric value from @code{value} for
-efficient later assignment. Only values of type @code{AWK_NUMBER}, @code{AWK_REGEX},
+efficient later assignment. Only values of type @code{AWK_NUMBER}, @code{AWK_REGEX}, @code{AWK_STRNUM},
and @code{AWK_STRING} are allowed. Any other type is rejected.
@code{AWK_UNDEFINED} could be allowed, but doing so would result in
inferior performance.
@@ -33053,9 +33080,9 @@ The array remains an array, but after calling this function, it
has no elements. This is equivalent to using the @code{delete}
statement (@pxref{Delete}).
-@item awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);
+@item 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 @code{a_cookie}, create an @code{awk_flat_array_t}
-structure and fill it in. Set the pointer whose address is passed as @code{data}
+structure and fill it in with indices and values of the requested types. Set the pointer whose address is passed as @code{data}
to point to this structure.
Return true upon success, or false otherwise.
@ifset FOR_PRINT
@@ -33067,6 +33094,12 @@ See the next @value{SECTION}
for a discussion of how to
flatten an array and work with it.
+@item awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);
+For the array represented by @code{a_cookie}, create an @code{awk_flat_array_t}
+structure and fill it in with @code{AWK_STRING} indices and
+@code{AWK_UNDEFINED} values. This is superseded by @code{flatten_array_typed}
+and retained only for legacy binary compatibility.
+
@item awk_bool_t release_flattened_array(awk_array_t a_cookie,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_flat_array_t *data);
When done with a flattened array, release the storage using this function.
@@ -33179,7 +33212,7 @@ to double-check that the count in the @code{awk_flat_array_t}
is the same as the count just retrieved:
@example
- if (! flatten_array(value2.array_cookie, & flat_array)) @{
+ if (! flatten_array_typed(value2.array_cookie, & flat_array, AWK_STRING, AWK_UNDEFINED)) @{
printf("dump_array_and_delete: could not flatten array\n");
goto out;
@}
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-06 16:57:55 +0000