Add strnum support to API. Update rwarray extension and test.

2 files changed, 52 insertions, 27 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index ddf454f0..cafced8f 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2016-12-05         Andrew J. Schorr     <aschorr@telemetry-investments.com>
+
+	* gawktexi.in: Document strnum changes as relates to API.
+	Still stuff left to do -- tables for type conversions need
+	to be updated to show new strnum and regex rows and columns.
+
 2016-12-04         Andrew J. Schorr     <aschorr@telemetry-investments.com>
 
 	* gawktexi.in: Remove make_regex and replace it with make_const_regex
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 1450d09d..fc43c520 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -31572,7 +31572,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}.
@@ -31592,6 +31593,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
@@ -31613,7 +31615,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}.
 
@@ -31622,6 +31624,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,
@@ -31796,6 +31804,18 @@ 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_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}.
@@ -32532,29 +32552,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
@@ -32661,7 +32680,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
 
@@ -32782,7 +32801,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.