                         A Dollar-Value Package

The package resides in the files DOLLAR.CPP and DOLLAR.H.

Every dollar value is an instance of the class "dollar".

The number of digits in each dollar value is set by the variable
dollar::number_of_digits. It must be the same for every dollar value in
use. The default value is 18. It may be changed by a simple assignment
statement, provided no dollar values created before the assignment are
used after the assignment.

Two static variables are used to specify the character used as
a digit separator (a comma, by default) and a decimal point (a period,
by default):

     dollar::separator
     dollar::decimal

These may be changed by simple assignment. The changes will apply to
edits and scans made after the assignment.

A dollar value may be CREDIT, DEBIT or ZERO, as determined by the
following member function call:

     r = d.range();

     dollar d;        dollar value

     dollar::dcz r;   dollar::DEBIT, dollar::CREDIT or dollar::ZERO

The default constructor for the dollar class initializes the value to
ZERO.

The += operator may be used to add dollar values:

     d += e;

     dollar d;        dollar value

     dollar e;        dollar value

The user-defined function numeric_overflow() is called if the result
overflows. This function must abort the program in some suitable manner.

The following function changes a DEBIT value to the corresponding CREDIT
value, and vice-versa:

     d.negate();

     dollar d;        dollar value

The assignment operator must be used to copy a dollar value:

     d = e;

     dollar d;        dollar value

     dollar e;        dollar value


The following function is used to scan a dollar value from a string:

     r = d.scan(s);

     dollar d;        dollar value

     const char *&s;  pointer to string containing dollar value

     bool r;          true for a successful scan, false if an error was
                      detected

The function will scan away leading spaces and tabs.

The first character of a dollar amount MUST be a digit. If a decimal
point is used, it must be followed by two digits or by a non-digit.
If digit separators are used, they must be used to separate groups of
three digits in the usual way.

When the function returns, the argument s will point to the first
character after the dollar amount, or to the point where an error was
found.

The scanned value is always DEBIT or ZERO.

The following function is used to edit a dollar amount and send it to an
output stream:

     d.print(fp, type, cents, separators);

     dollar d;        dollar value to be edited

     FILE *fp;        output stream to receive edited result

     dollar::edit_type type;
                      see below

     bool cents;      true if decimal point and cents digits are to be
                      included; if this argument is false, the cents
                      part of the dollar value is lost

     bool separators; true if separators are to be used to separate
                      groups of three digits

The edited field always contains enough space to accommodate the largest
possible value (as specified by dollar::number_of_digits) and enclosing
parentheses. If the amount is smaller than this, it is right-justified
with blank fill at the left.

Parentheses are used to show debits where credits are expected, and vice
versa. A field of asterisks is the result if the value will not fit into
the specified width.

The type argument shows what is expected and what to do when the value
is not as expected:

     type                     when value is not as expected
     -----------------------  ----------------------------------------
     dollar::DEBIT_EXPECTED   CREDIT value is enclosed in parentheses
     dollar::DEBIT_REQUIRED   CREDIT value produces field of asterisks
     dollar::CREDIT_EXPECTED  DEBIT value is enclosed in parentheses
     dollar::CREDIT_REQUIRED  DEBIT value produces field of asterisks
     dollar::NO_DEBIT_CREDIT  not applicable

If the type is dollar::NO_DEBIT_CREDIT, then the value will be edited
without regard to its debit or credit status.

The ZERO value is edited to 0.00 (or simply 0 if no cents field is
specified), and is considered acceptable as a DEBIT or CREDIT value.

