Decimal Arithmetic Specification, version 1.70
Copyright (c) IBM Corporation, 2009. All rights reserved. ©
|7 Apr 2009
|[previous | contents | next]
The full specification in the body of this document defines a
decimal floating-point arithmetic which gives exact results and
preserves exponents where possible. If insufficient precision is
available for this, then numbers are handled according to the rules of
IEEE 854. The use of IEEE 854 rules implies that special values
(infinities and NaNs) are allowed, as subnormal values and the value
For some applications and programming languages (especially those
intended for use by people who are not mathematically sophisticated),
it may be appropriate to provide an arithmetic where infinite, NaN, or
subnormal results are always treated as errors, –0 results are
hidden, and other (largely cosmetic) changes are provided to aid
acceptance of results.
The arithmetic defined in ANSI X3.274 is such an arithmetic; this
appendix describes the differences between this and the full specification.
Implementations which support this subset explicitly might provide the
subset behavior under the control of a parameter in the context
or might provide a different interface (additional or parameterized
methods, for example).
Simplified number set
In the subset arithmetic, a reduced set of number values is supported
and (where appropriate) numbers with positive exponents have their
exponent reduced to zero.
In the to-number conversion, if the coefficient for a
finite number has the value zero, then the sign and the
exponent are both set to 0.
If the coefficient in a result has the value zero,
then the sign is set to 0 and (unless the operation is
quantize) the exponent is set to 0.
In the to-number conversion, strings which represent special
values are not permitted. (That is, only finite numbers are accepted.)
Subnormal numbers are not permitted. If the result from a conversion or
operation would be subnormal then an Underflow error results (see
After any operation and the rounding of its result (unless the operation
is quantize), a result with a positive exponent is converted to
an integer provided that the resulting coefficient would have
no more than precision digits.
In other words, in this case a positive exponent is reduced to 0 by
multiplying the coefficient by 10exponent
(which has the effect of suffixing exponent zeros).
In the subset arithmetic, operands are rounded before use if necessary
(as in Numerical Turing
the Lost digits condition is added to the context,
the results of some operations are trimmed,
the rounding rule after a subtraction is less conservative, and raising
0 to the power 0 is not treated as an error.
If the number of decimal digits in the coefficient of an
operand to an operation is greater than the current precision
in the context then the operand is rounded to precision
significant digits using the rounding algorithm described by
the context before being used in the computation.
In other words, an automatic ‘convert to shorter’ is applied before
During an add or subtract operation,
if either number is zero then the other number, rounded to
precision if necessary, is used as the result (with sign
adjustment as appropriate).
The Lost digits condition is added to the abstract context; it
should be set to 0 in default contexts.
This condition is raised when non-zero digits are discarded before an
operation. This can occur when an operand which has more leading
significant digits in its coefficient than the
precision setting is rounded to precision digits
Note that the lost digits test does not treat trailing decimal zeros in
the coefficient as significant. For example, if
precision had the value 5, then the operands
would not cause an exception (whereas [0,123451,-1]
or [0,1234500001,0] would).
After a divide or power operation is complete and the
result has been rounded, any insignificant trailing zeros are removed.
That is, if the exponent is not zero and the
coefficient is a multiple of a positive power of ten then the
coefficient is divided by that power of ten and the
exponent increased accordingly. If the exponent was
negative it will not be increased above zero.
After an addition operation, the result is rounded to precision
digits if necessary, taking into account any extra (carry) digit on the
left after an addition, but otherwise counting from the position
corresponding to the most significant digit of the operands being added
or subtracted (rather than the most significant digit of the result).
For the max and min operations, the first
(left-hand) operand is chosen if the operands are numerically equal.
If both operands to a power operation are zero then the result
is 1 (instead of being an error); however, if the left-hand operand
is zero the right-hand operand must not be negative.
The right-hand operand to a power operation may be an
integer, and subset implementations are only required to provide the
power function for integer powers.
In this case the algorithm described below may be used for
calculating the result.
The fused-multiply-add operation is not defined for subset
implementations, because the rounding of operands rule conflicts with
the requirement for fused-multiply-add to deliver a result with only
Exceptional condition and rounding mode rules
In the subset arithmetic, exceptional conditions other than the
informational conditions (Lost digits, Inexact, Rounded, and Subnormal)
must be treated as errors, and results after these errors are undefined.
Special values and subnormal numbers, therefore, are not part of the
In the subset, only the Lost digits trap enabler is required. Inexact,
Rounded, and Subnormal trap enablers are optional, and the others are
(in effect) always set. Similarly, the status bits in the
context are optional.
Only the round-half-up rounding mode is required.
Calculating an integer power
Subset implementations are only required to provide the power
function for integer powers. To calculate this, the number
(left-hand operand) is in theory multiplied by itself for the number
of times expressed by the power.
If the right-hand operand is negative, the left-hand operand is used
as-is, the absolute value of the right-hand operand is used, and the
final result is inverted.
In practice (see the note below for the reasons), the power is often
calculated by the process of left-to-right binary reduction.
For power(x, n): ‘n’ is converted to
binary, and a temporary accumulator is set to 1.
If ‘n’ has the value 0 then the initial calculation is
Otherwise each bit (starting at the first non-zero bit) is inspected
from left to right.
If the current bit is 1 then the accumulator is multiplied by
If all bits have now been inspected then the initial calculation is
complete, otherwise the accumulator is squared by multiplication and the
next bit is inspected.
The multiplications and any final division are done under the normal
arithmetic operation rules, using the precision supplied for the
operation, except that the multiplications (and the division, if
needed) are carried out using an increased precision of
Here, elength is the length in decimal digits of the integer
part (coefficient) of the whole number ‘n’ (i.e., excluding
any sign, decimal part, decimal point, or insignificant leading zeros.
If, when raising to a negative power, an underflow occurs during the
division into 1, the operation is not halted at that point but
A particular algorithm for calculating integer powers is described,
since it is efficient (though not optimal) and considerably reduces
the number of actual multiplications performed.
It therefore gives better performance than the simpler definition of
Since results can occasionally differ from those of repeated
multiplication, the algorithm is defined here so that different
implementations which use it will give identical results for the
power operation on the same values, and may therefore use the same
testcases. Other algorithms for the power operation may also be
used, so long as the result is within 1 ulp (unit in last place) of
the correct result.
Implementations are encouraged to provide a power operator which will
accept a non-integral right-hand operand when the left-hand operand
is non-negative, as described in the body of this specification.
||The decNumber package, for example, provides the subset behavior if the
extended bit is set to 0.
||This rule, together with the to-number definition, ensures that
numbers with values such as -0 or 0.0000 will not result from
general operations in the subset arithmetic.
This allows a concrete representation for the subset to comprise simply
two integers in two’s complement form.
||The underlying intent here is that positive exponents in the operands
are reduced to zero before the operation, so that all
operations take place on numbers that could be expressed as
‘plain’ decimal numbers with no exponent. The rule is expressed
as a constraint on the result because it is often more convenient or
efficient to implement it in this way.
The rule also preserves integers as specified by ANSI X3.274, and in
particular ensures that the results of the divide and
divide-integer operations are identical when the result is an
||See: T. E. Hull, A. Abrham, M. S. Cohen, A. F. X. Curley, C. B. Hall, D.
A. Penny, and J. T. M. Sawchuk,
SIGNUM Newsletter, vol. 20 #3, pp26-34, ACM, May 1985.
||In the subset arithmetic, zeros have no exponent.
||This rule is slightly more complicated than inverting before the
calculation, in that it requires special treatment of overflow and
underflow conditions (which were not an issue in X3.274).
||The precision specified for the intermediate calculations ensures
that the final result will differ by at most 1, in the least
significant position, from the ‘true’ result
(given that the operands are expressed precisely under the current
setting of digits).
Half of this maximum error comes from the intermediate calculation, and
half from the final rounding.
||It can only be halted early if the result becomes zero.
[previous | contents | next]