FATOMONEY C-3

fatomoney - convert ASCII to MONEY value

Fatomoney converts a string pointed to by sptr to a MONEY value using format to control the conversion. The result of the conversion is stored in the MONEY value pointed at by m. Size is the size of the MONEY value. Fatomoney supports both double and float values. Size must be the size of a double or the size of a float.

Fatomoney first tries to convert sptr using format. If this fails, fatomoney applies the standard input rules for MONEY values. These rules allow an optional string of tabs or spaces, an optional minus sign, and 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.

If sptr does not have a decimal separator character, the number of implied decimal places is the value returned by getfplac(C-3). Once the decimal separator has been positioned, the value is converted in the basic unit of currency for the defined country (pennies for U.S.A.).

Fractions of the basic unit of currency are accepted although small errors in representation can occur if much arithmetic is done with fractional values. Because of the method fatomoney uses to convert a string, there can never be representation errors with values that do not contain a fraction of the basic unit.

A MONEY value can represent values that contain 15 significant digits. This allows accurate representation of dollar values up to 10 trillion dollars. This number may be different for other country formats (depending on the value returned by getfplac(C-3)).

The first unrecognizable character ends the string. When doing edit checks, it is left to the calling program to determine if the remaining unrecognized characters should be considered valid.

fcountry(C-3), getfmoney(C-3), getfdec(C-3), getfthou(C-3), getfplac(C-3), atomoney(C-3), round(C-3)

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

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

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

FFORMAT format is invalid

FIFORMAT  sptr does not conform to any of the formatting rules

Fatomoney 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.

Internally, MONEY values are kept as a whole number of the basic unit of currency. For example, in the U.S.A., the basic unit of currency is the penny. In this case, all MONEY amounts are kept as the number of pennies. This representation guarantees accurate representation of any money amount.

When a value is being converted, the decimal separator is located (or implied) and moved left or right based on the value returned by getfplac(C-3). For example, if a string of 1.00 is entered for a U.S.A. MONEY value, the decimal separator (.) is moved right two places (100.) before the number is converted. The end result is a number of the basic units (100 pennies). This method guarantees that there is no round-off error when converting the string to a floating point value.