FATOREAL C-3

fatoreal - convert ASCII to REAL value

Fatoreal converts a string pointed to by sptr to a REAL value using format to control the conversion. The result of the conversion is stored in the REAL value pointed at by r. Size is the size of the REAL value. Fatoreal supports both double and float data types. Size must be the size of a double or the size of a float.

Fatoreal first tries to convert sptr using format. If this fails, fatoreal applies the standard input rules for REAL values. These rules allow an optional string of tabs and spaces, then an optional minus sign, then a string of digits optionally containing a decimal separator character (returned by getfdec(C-3)). The string may also contain one or more of the thousands separator character (returned by getfthou(C-3)) to make the number more readable.

Fatoreal returns the number of characters in sptr used to convert the value. The advantages of using fatoreal over atof(3) is that fatoreal understands special formats and special characters for the defined country, it accepts a number containing embedded thousands separator characters (commas for U.S.A. formats). Fatoreal also performs more edit checks than atof(3) and atoreal(C-3).

The first unrecognized character ends the string. When doing edit checks, it is left to the calling program to determine if what is left of sptr after the conversion process should be considered valid.

fcountry(C-3), getfthou(C-3), getfdec(C-3), atoreal(C-3), atof(3)

C/Base Reference Manual Chapter 13, "Formatting Data Values"

If an error occurs, fatoreal returns a negative number and the contents of r are undefined. The following symbolic error codes are defined in <cbase/dtypes.h>:

FTOOBIG size is not the size of a double or float (use sizeof function) or the result overflowed

FFORMAT format is invalid

FIFORMAT sptr does not conform to any of the formatting rules

Fatoreal defines overflow to mean a number with more than 15 digits to the left of the decimal point for double values, and more than 6 digits to the left of the decimal point for float values.