Description

These functions attempt to parse a numeric token from at most nmax
characters read from a string **pc, a file *pf, or function (*pget).
They set the decimal record *pd to reflect the value of the numeric
token recognized and set *pform and *pechar to indicate its form.

The accepted forms for the numeric token consist of an initial, possibly
empty, sequence of white-space characters, as defined by isspace(3C), followed by a subject
sequence representing a numeric value, infinity, or NaN. The subject sequence
consists of an optional plus or minus sign followed by one of
the following:

a non-empty sequence of decimal digits optionally containing a decimal point character, then an optional exponent part

one of INF or INFINITY, ignoring case

one of NAN or NAN(string), ignoring case in the NAN part; string can be any sequence of characters not containing ')' (right parenthesis) or '\0' (null).

The fortran_conventions argument provides additional control over the set of accepted forms.
It must be one of the following values:

0

no Fortran conventions

1

Fortran list-directed input conventions

2

Fortran formatted input conventions, blanks are ignored

3

Fortran formatted input conventions, blanks are interpreted as zeroes

When fortran_conventions is zero, the decimal point character is the current locale's
decimal point character, and the exponent part consists of the letter E
or e followed by an optional sign and a non-empty string of
decimal digits.

When fortran_conventions is non-zero, the decimal point character is “.” (period), and
the exponent part consists of either a sign or one of the
letters E, e, D, d, Q, or q followed by an optional sign,
then a non-empty string of decimal digits.

When fortran_conventions is 2 or 3, blanks can appear in the digit
strings for the integer, fraction, and exponent parts, between the exponent delimiter
and optional exponent sign, and after an INF, INFINITY, NAN, or NAN(string).
When fortran_conventions is 2, all blanks are ignored. When fortran_conventions
is 3, blanks in digit strings are interpreted as zeros and other
blanks are ignored.

The following table summarizes the accepted forms and shows the corresponding values
to which *pform and pd->fpclass are set. Here digits represents any string
of decimal digits, “.” (period) stands for the decimal point character, and exponent
represents the exponent part as defined above. Numbers in brackets refer
to the notes following the table.

form

*pform

pd->fpclass

all white space [1]

whitespace_form

fp_zero

digits

fixed_int_form

fp_normal [2]

digits.

fixed_intdot_form

fp_normal [2]

.digits

fixed_dotfrac_form

fp_normal [2]

digits.digits

fixed_intdotfrac_form

fp_normal
[2]

digitsexponent

floating_int_form

fp_normal [2]

digits. exponent

floating_intdot_form

fp_normal [2]

.digits exponent

floating_dotfrac_form

fp_normal [2]

digits.digitsexponent

floating_intdotfrac_form

fp_normal [2]

INF

inf_form

fp_infinity

INFINITY

infinity_form

fp_infinity

NAN

nan_form

fp_quiet

NAN(string)

nanstring_form

fp_quiet

none of the above

invalid_form

fp_signaling

Notes:

The whitespace_form is accepted only when fortran_conventions is 2 or 3 and is interpreted as zero.

For all numeric forms, pd->fpclass is set to fp_normal if any non-zero digits appear in the integer or fraction parts, and otherwise pd->fpclass is set to fp_zero.

If the accepted token has one of the numeric forms and represents
a non-zero number x, its significant digits are stored in pd->ds.
Leading and trailing zeroes and the radix point are omitted. pd->sign
and pd->exponent are set so that if m is the integer represented
by pd->ds,

-1**(pd->sign) * m * 10**(pd->exponent)

approximates x to at least 511 significant digits. pd->more is set
to 1 if this approximation is not exact (that is, the accepted
token contains additional non-zero digits beyond those copied to pd->ds) and to
0 otherwise.

If the accepted token has the NAN(string) form, up to 511 characters
from the string part are copied to pd->ds.

pd->ds is always terminated by a null byte, and pd->ndigits is set
to the length of the string stored in pd->ds.

On entry, *pc points to the beginning of a character string buffer.
The string_to_decimal() function reads characters from this buffer until either enough
characters are read to delimit the accepted token (for example, a null
character marking the end of the string is found) or the limit of
nmax characters is reached. The file_to_decimal() function reads characters from the file
*pf and stores them in the buffer. The func_to_decimal() function reads characters one
at a time by calling the function (*pget)() and stores them in
the buffer; (*pget)() must return integer values in the range -1 to
255, where -1 is interpreted as EOF and 0, ..., 255 are
interpreted as unsigned char values. Both file_to_decimal() and func_to_decimal() read characters until either enough
characters are read to delimit the accepted token, EOF is encountered, or
the limit of nmax characters is reached. These functions, therefore, typically read one
or more additional characters beyond the end of the accepted token and
attempt to push back any excess characters read. Provided that the punget
argument is not NULL, func_to_decimal() pushes back characters one at a time by
calling (*punget)(c), where c is an integer in the range 0 to
255 corresponding to a value previously read via (*pget)(). After pushing back
as many excess characters as possible, file_to_decimal() and func_to_decimal() store a null
byte in the buffer following the last character read and not pushed
back and set *pnread to the number of characters stored in the
buffer prior to this null byte. Since these functions can read up to
nmax characters, the buffer must be large enough to hold nmax +
1.

On exit, *pc points to the next character in the buffer past
the last one that was accepted as part of the numeric token.
If no valid token is found, *pc is unchanged. If
file_to_decimal() and func_to_decimal() successfully push back all unused characters, *pc points to the
null byte stored in the buffer following the last character read and
not pushed back.

If the accepted token contains an exponent part, *pechar is set to
point to the position in the buffer where the first character of
the exponent field is stored. If the accepted token does not
contain an exponent part, *pechar is set to NULL.

Usage

If the _IOWRT flag is set in *pf, file_to_decimal() reads characters directly
from the file buffer until a null character is found. (The
_IOWRT flag should only be set when file_to_decimal() is called from sscanf(3C).)
Otherwise, file_to_decimal() uses getc_unlocked(3C), so it is not MT-safe unless the caller
holds the stream lock.