string_to_decimal(3C)					   Standard C Library Functions 				     string_to_decimal(3C)

NAME

       string_to_decimal, file_to_decimal, func_to_decimal - parse characters into decimal record

SYNOPSIS

       #include <floatingpoint.h>

       void string_to_decimal(char **pc, int nmax, int fortran_conventions, decimal_record *pd, enum decimal_string_form *pform, char **pechar);

       void  func_to_decimal(char **pc, int nmax, int fortran_conventions, decimal_record *pd, enum decimal_string_form *pform, char **pechar, int
       (*pget)(void), int *pnread, int (*punget)(int c));

       #include <stdio.h>

       void file_to_decimal(char **pc, int nmax, int fortran_conventions, decimal_record *pd, enum decimal_string_form *pform, char **pechar, FILE
       *pf, int *pnread);

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  iss-
       pace(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:

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

	 o  one of INF or INFINITY, ignoring case

	 o  one of NAN or NAN(string), ignoring case in the NAN part; string can be any sequence of characters not containing ')' (right parenthe-
	    sis) or '' (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 con-
       sists 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 expo-
       nent 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]
       digits exponent		floating_int_form	   fp_normal [2]
       digits. exponent 	floating_intdot_form	   fp_normal [2]
       .digits exponent 	floating_dotfrac_form	   fp_normal [2]
       digits.digits exponent	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:

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

       2.  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.   Lead-
       ing  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 cor-
       responding 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.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       ctype(3C), decimal_to_floating(3C), getc_unlocked(3C),  isspace(3C),  localeconv(3C),  scanf(3C),  setlocale(3C),  strtod(3C),  ungetc(3C),
       attributes(5)

SunOS 5.10							    1 Oct 2003						     string_to_decimal(3C)