NAME

atomoney - convert ASCII to MONEY value

SYNOPSIS

#include <cbase/dtypes.h>

MONEY atomoney (sptr)

char *sptr;

DESCRIPTION

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

SEE ALSO

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

NOTES

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