ATOMONEY C-3

NAME

atomoney - convert ASCII to MONEY value

This function converts a string pointed to by sptr to a MONEY value. Atomoney first tries to convert sptr with the format returned by getfmoney(C-3). If this fails, atomoney applies a set of standard input rules.

The standard input rules allow an optional string of tabs or 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.

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 atomoney 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)).

For atomoney, the first unrecognizable character ends the string.

fcountry(C-3), getfmoney(C-3), getfdec(C-3), getfthou(C-3),

getfplac(C-3), fatomoney(C-3), round(C-3)

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

A value of zero is returned for any conversion error, including overflow. Atomoney defines overflow to mean a number with more than 15 digits to the left of the decimal point.

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.