atomoney - convert ASCII to MONEY value
#include 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" DIAGNOSTICS 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. DESCRIPTION
SEE ALSO
NOTES