From a3d8ddb902caa9cd8a9f265bd59aaefa01e41844 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Mon, 10 Jun 2024 13:58:07 -0600 Subject: [PATCH] perlapi: Rewrite pod for grok_number, combine with _flags I found the old version overly confusing. --- numeric.c | 80 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 53 insertions(+), 27 deletions(-) diff --git a/numeric.c b/numeric.c index c22e4ef3cc79..c838def16cc5 100644 --- a/numeric.c +++ b/numeric.c @@ -975,36 +975,62 @@ Perl_grok_infnan(pTHX_ const char** sp, const char* send) } /* -=for apidoc grok_number_flags - -Recognise (or not) a number. The type of the number is returned -(0 if unrecognised), otherwise it is a bit-ORed combination of -C, C, C, -C, C, C (defined in perl.h). - -If the value of the number can fit in a UV, it is returned in C<*valuep>. -C will be set to indicate that C<*valuep> is valid, C -will never be set unless C<*valuep> is valid, but C<*valuep> may have been assigned -to during processing even though C is not set on return. -If C is C, C will be set for the same cases as when -C is non-C, but no actual assignment (or SEGV) will occur. - -C will be set with C if trailing decimals were -seen (in which case C<*valuep> gives the true value truncated to an integer), and -C if the number is negative (in which case C<*valuep> holds the -absolute value). C is not set if C notation was used or the -number is larger than a UV. - -C allows only C, which allows for trailing -non-numeric text on an otherwise successful I, setting -C on the result. +=for apidoc grok_number +=for apidoc_item grok_number_flags + +Look for a number in the C bytes starting at C. If one isn't found, +return 0; otherwise return its type (and optionally its value). In +C all C bytes must be either leading C> +characters or part of the number. The same is true in C +unless C contains the C bit, which allows for +trailing non-numeric text. (This is the only difference between the two +functions.) + +The returned type is the ORing of various bits (#defined in F) as +described below: + +If the number is negative, the returned type will include the C +bit. + +If the absolute value of the integral portion of the found number fits in a UV, +the returned type will include the C bit. If it won't fit, +instead the C bit will be included. + +If the found number is not an integer, the returned type will include +the C bit. This happens either if the number +is expressed in exponential C notation, or if it includes a decimal +point (radix) character. If exponential notation is used, then neither +IS_NUMBER_IN_UV nor IS_NUMBER_GREATER_THAN_UV_MAX bits are set. +Otherwise, the integer part of the number is used to determine the +C and C bits. + +If the found number is a string indicating it is infinity, the +C and C bits are included in the +returned type. + +If the found number is a string indicating it is not a number, the +C and C bits are included in the +returned type. + +You can get the number's absolute integral value returned to you by calling +these functions with a non-NULL C argument. If the returned type +includes the C bit, C<*valuep> will be set to the correct +value. Otherwise, it could well have been zapped with garbage. + +In C when C contains the C +bit, and trailing non-numeric text was found, the returned type will include +the C bit. + +=for apidoc Amnh||IS_NUMBER_GREATER_THAN_UV_MAX +=for apidoc Amnh||IS_NUMBER_INFINITY +=for apidoc Amnh||IS_NUMBER_IN_UV +=for apidoc Amnh||IS_NUMBER_NAN +=for apidoc Amnh||IS_NUMBER_NEG +=for apidoc Amnh||IS_NUMBER_NOT_INT +=for apidoc Amnh||IS_NUMBER_TRAILING =for apidoc Amnh||PERL_SCAN_TRAILING -=for apidoc grok_number - -Identical to C with C set to zero. - =cut */ int