The decNumber Library, version 3.68
Copyright (c) IBM Corporation, 2010. All rights reserved. ©
| 23 Jan 2010 |
| [previous | contents]
|
This appendix documents changes since the first (internal) release of
this document (Draft 1.50, 21 Feb 2001).
- The significand of a number has been renamed from integer
to coefficient, to remove possible ambiguities.
-
The decNumberRescale function has been redefined to match the
base specification. In particular its rhs now specifies the
new exponent directly, rather than as a negated exponent.
-
In general, all functions now return a reference to their primary result
structure.
-
The decPackedToNumber function now handles only ‘classic’
Packed Decimal format (there must be a sign nibble, which must be the
final nibble of the packed bytes). This improved conversion speed by a
factor of two.
-
Minor clarifications and editorial changes have been made.
- The rounding modes DEC_ROUND_CEILING
and DEC_ROUND_FLOOR have been added.
-
Minor clarifications and editorial changes have been made.
This is the first public release of this document.
-
The decDoubleToSingle function will now round the value of the
decDouble number if it has more than 15 digits.
-
The decNumberToInteger, decNumberRemainderNear, and
decNumberVersion functions have been added.
-
Relatively minor changes have been made throughout to reflect support
for the extended specification.
-
The header files have been reorganized in order to move private type
names (such as Int and Flag) out of the external interface
header files. In the external interface, integer types now use
the stdint.h names from C99.
-
All but one of the compile-time parameters have been moved to the
‘internal’ decNumberLocal.h header file, and so are
described in a new section.
-
The decNumberAbs, decNumberMax, and
decNumberMin functions have been added.
-
Minor clarifications and editorial changes have been made.
-
The decNumberTrim function has been added.
-
The decNumberRescale function has been updated to match changed
specifications; it now sets the exponent as requested even for zero
values.
-
Minor clarifications and editorial changes have been made.
The package has been updated to reflect the changes included in the
combined arithmetic specification. These preserve more digits of the
coefficient together with extended zero values if extended in
the context is 1. Notably:
-
The decNumberDivide and decNumberPower functions do
not remove trailing zeros after the operation.
(The decNumberTrim function can be used to effect this, if
required.)
-
A non-zero exponent on a zero value is now possible and is preserved
in a manner consistent with other numbers (that is, zero is no longer a
special case).
-
The decPackedToNumber function has been enhanced to allow zeros
with non-zero exponents to be converted without loss of information.
-
The decNumberFromString, decSingleFromString, and
decDoubleFromString functions will now round the coefficient of
a number to fit, if necessary. They also now accept subnormal values and
preserve the exponent of a 0. If an overflow or underflow occurs,
the DEC_Overflow or DEC_Underflow
conditions are raised, respectively.
-
The package has been corrected to ensure that subnormal values are no
more precise than permitted by IEEE 854.
-
The underflow condition is now raised according to the IEEE 854
untrapped underflow criteria (instead of according to the IEEE 854
trapped criteria).
That is, underflow is now only raised when a result is both subnormal
and inexact.
-
The DEC_Subnormal condition has been added so that
subnormal results can be detected even if no Underflow condition is
raised.
-
Minor clarifications and editorial changes have been made.
-
The decNumberNormalize function has been added, as an operator.
This makes the coefficient of a number as short as possible while
maintaining its numerical value.
-
The decNumberSquareRoot function has been added. This returns
the exact square root of a number, rounded to the specified
precision and normalized.
-
When the extended setting is 1, long operands are used without
input rounding, to give a correctly rounded result (without double
rounding).
The DEC_Lost_digits flag can therefore only be set
when extended is 0.
-
Minor editorial changes have been made.
The major change in decNumber version 3 is the replacement of the
decSingle and decDouble formats by the three new formats
decimal32, decimal64, and decimal128.
These formats are now [June 2008] included in the
IEEE-SA 754 standard.
Related and other enhancements include:
-
The exponent minimum field, emin, has been added to the
decContext structure. This allows the unbalanced exponents used in the
new formats.
-
The exponent clamping flag, clamp, has been added to the
decContext structure. This provides explicit exponent clamping as used
in the new formats.
-
A new condition flag, DEC_Clamped has been introduced.
This reports any situation where the exponent of a finite result has
been limited to fit in the available exponent range.
-
The header file bcd2dpd.h has been renamed decDPD.h to
better describe its function.
-
The DECSUBSET tuning parameter has been added. This controls the
inclusion of the code and flags required for subset arithmetic; when set
to 0, the performance of many operations is improved by 10%–20%.
-
Double rounding which was possible with certain subnormal results has
been eliminated.
-
Minor editorial changes have been made.
This version implements some minor changes which track changes agreed
by the IEEE 754 revision committee.
-
The decNumberQuantize function has been added. Its function
is identical to decNumberRescale except that the second
argument specifies the target exponent ‘by example’ rather than by
value.
-
The decNumberQuantize and decNumberRescale functions
now report DEC_Invalid_operation rather
than DEC_Overflow if the result cannot fit.
-
The decNumberToInteger function has been replaced by
the decNumberToIntegralValue function. This implements the new
rules for round-to-integral-value agreed by IEEE 754r. Notably:
- the exponent is only set to zero if the operand had a negative exponent
- the Inexact flag is not set.
-
The decNumberSquareRoot function no longer normalizes. Its
preferred exponent is floor(operand.exponent/2).
This version adds a new function and slightly reorganizes the decimalnn
modules.
-
The decNumberSameQuantum function has been added.
This tests whether two numbers have the same exponents.
-
The decimal128.h, decimal64.h, and decimal32.h
header files now check that (if more than one is included) they are
included in order of reducing size. This makes it harder to use a
decNumber structure which is too small.
- .
The shared DPD pack/unpack routines have been moved
from decimal32.c to decimal64.c, because the latter is
more likely to be used alone.
-
NaN values may now use the coefficient to convey diagnostic information,
and NaN sign information is propagated along with that information.
-
The decNumberQuantize function now allows both arguments to be
infinite, and treats NaNs in the same way as other functions.
-
The decNumberIsInfinite, decNumberIsNaN,
decNumberIsNegative, and decNumberIsZero functions
have been added to simplify tests on numbers.
These functions are currently implemented as macros.
-
The decNumberMax and decNumberMin functions have
been altered to conform to the maxnum and minnum
functions in IEEE 754. That is, a total ordering is provided for
numerical comparisons, and if one operand is a quiet NaN
but the other is a number then the number is returned.
-
The decimal64FromString function (and the same function for
the other two formats) now uses the rounding mode provided in the
context structure.
-
Arguments to functions which are ‘input only’ are now
decorated with the const keyword to make the functions
easier and safer to call from a C++ wrapper class.
-
The performance of arithmetic when DECDPUN<=3 has been improved
substantially; DECDPUN==3 performance is now similar to DECDPUN==4.
-
An error in the decNumberRescale and decNumberQuantize functions has
been corrected. This returned 1.000 instead of NaN for
quantize(0.9998, 0.001) under a context with precision=3.
-
The decNumberExp function has been added. This returns
e raised to the power of the operand.
-
The decNumberLn and decNumberLog10 functions have
been added. These return the natural logarithm (logarithm in base
e) or the logarithm in the base ten of the operand,
respectively.
-
The decNumberPower function has been enhanced by removing
restrictions; notably it now allows raising numbers to non-integer
powers.
-
The DECENDIAN tuning parameter has been added. This allows
the compressed decimal formats to be stored using
platform-dependent ordering for better performance and compatibility
with binary formats.
This parameter can be set to 0 to get the same (big-endian) ordering
on all platforms, as in earlier versions of the decNumber package.
-
The DECUSE64 tuning parameter has been
added. This allows 64-bit integers to be used to improve the
performance of operations when DECDPUN<=4.
This parameter can be set to 0 to ensure only 32-bit integers are
used when DECDPUN<=4.
-
The compressed decimal formats are widely used with the decNumber
package, so the initial setting of DECDPUN has been changed to
3 (from 4), and DECENDIAN and DECUSE64 are both set to
1 (to use platform ordering and 64-bit arithmetic). These settings
significantly improve the speed of conversions to and from the
compressed formats and the speed of multiplications and other
operations.
-
Minor clarifications and editorial changes have been made.
-
The decNumberCompareTotal (total ordering comparison),
decNumberIsQNaN, and decNumberIsSNaN functions have
been added.
This is a major upgrade to decNumber to add logical and shifting
functions together with generalizations of most of the new functions
required by the IEEE 754 standard.
The changes included in this update are:
-
Thirty-four new functions have been added to the decNumber module
(all names have the prefix decNumber):
And, CompareSignal, CompareTotalMag,
CopyAbs, CopyNegate, CopySign,
Class, ClassToString, FMA,
FromInt, FromUInt, GetBCD,
Invert, IsCanonical, IsFinite,
IsNormal, IsSpecial, IsSubnormal,
LogB, MaxMag, MinMag, NextMinus,
NextPlus, NextToward, Or, Radix,
Rotate, ScaleB, SetBCD, Shift,
ToIntegralExact, ToInt32, ToUInt32,
Xor.
-
Two new functions have been added to each of the three decimalNN modules:
decimalNNIsCanonical, decimalNNCanonical.
-
The DECENDIAN setting (in decNumberLocal.h) has been removed to
improve performance; instead, you must set the
DECLITEND parameter
to 1 if compiling for a little-endian target, or to 0 if compiling
for a big-endian target.
If DECCHECK is set to 1 (highly recommended while testing),
any call to decContextDefault will check that DECLITEND is set
correctly.
-
The DECEXTFLAG parameter has been added
(in decContext.h). This controls whether the status flags returned by
decNumber are restricted to the five IEEE flags or comprise an
extended set which gives more detail about invalid operations along
with some extra flags (this does not affect performance). The
default is the extended set of flags, as in earlier versions of
decNumber.
-
Minor corrections (notably to the descriptions of the
FromString functions) and clarifications have been made.
This is a major upgrade to decNumber which adds three new modules
(decSingle, decDouble, and decQuad) with 175 new
functions. These modules provide functions which work directly with
the decimal32, decimal64, and decimal128 formats, to provide high
performance when arbitrary-precision calculations are not needed.
In addition to the new modules, the changes included in this update
are:
-
Two new examples have been added to the User’s Guide, showing how to
use the new modules either stand-alone or in conjunction with the
decNumber module.
-
Eleven new functions have been added to the decContext module
to match those required by the IEEE 754
standard.
-
Synonyms for DEC_INIT_DECIMAL32, etc.,
have been provided to match the names of the new modules,
called DEC_INIT_DECSINGLE, etc.
-
The decClasses enumeration and strings have been moved
from decNumber.h to decContext.h so that they can be
used from all modules.
-
The DECVERSION constant has been moved from decNumber.h
to decNumberLocal.h so that it can be used from all modules.
-
The decNumberNormalize function has been renamed
decNumberReduce for clarity (it is still available in the
code and header file under the old name, for compatibility).
-
A new appendix comparing the performance of the decNumber module to
the new decDouble and decQuad modules has been added.
-
Numerous clarifications and editorial changes have been made.
This release of decNumber is a code maintenance release; the problems
corrected are:
-
decNumberRemainder: the sign of a zero result was occasionally
different from that specified by IEEE 854
-
decNumberSquareRoot: several problems related to subnormal results
that were not covered by Hull’s algorithm and also when the input
argument was wider than the requested result width
-
decNumber and decFloats: under the DEC_ROUND_05UP
rounding mode Infinity was being returned after overflow instead of the
number with the greatest possible magnitude
-
decQuadDivide: divisions where both operands had more than 27 digits
and the result was extremely close to one (all but the last few
digits the same) could return a value slightly larger than one
instead of just less than one; this also affected the
decQuadDivideInteger and remainder functions (but not decDouble or
decNumber divisions or remainder)
-
decDoubleFromString and decQuadFromString: the restriction that the
input string should not be followed by unaddressable memory has been
removed
-
numerous code changes have been made to avoid new warnings in recent
releases of GCC.
New testcases have been added for all the above cases.
This release of decNumber is a code maintenance release primarily to
widen the applicability of the package. The changes are:
-
The modules now conform to the C99 strict aliasing rules (that is, no
longer cast char * pointers to int *, etc., because
such casts are forbidden in C99).
-
As a consequence of the previous change, the decDouble (etc.)
structures have been changed to unions, allowing access through wider
integer types as well as by bytes.
-
Accesses to memory through an integer type are now always aligned.
(Some RISC platforms reported alignment problems with parts of the
code; thanks are due to Nelson Beebe for identifying and testing
these cases.)
-
The decContextTestEndian function has been added. This
tests that the DECLITEND tuning parameter
is set correctly, and optionally displays a message if it is not. A
call to this function has been added to example1.c. This test
is no longer automatic under DECCHECK (it was inconvenient in
some cases).
-
The customization and tuning parameters are now only set to default
values in the header files if not already defined. These means that
they can be set from the compiler command line if desired
(e.g., with the option -DDECUSE64=0).
-
The decDoubleFromPackedChecked function has been added (also
for decSingle and decQuad); this is the same as decDoubleFromPacked
except that all input values are checked.
-
Edge-case errors in multiply, FMA, and remainder functions have been
corrected.
-
Minor code changes have been made to improve performance in some
areas.
This release of decNumber is a code maintenance and performance
release. The changes are:
-
A fastpath has been added to decDoubleAdd and decQuadAdd for the
common case of aligned additions with exact results. This typically
improves the performance in these cases by 2× or 3×
respectively.
-
The performance of decNumberSquareRoot has been improved
when the result is exact or definitely inexact.
-
The IEEE 854 names in decContext.h are now supplied with IEEE
754 names too
(e.g., DEC_IEEE_754_Inexact).
-
References to IEEE 854 and the old IEEE 754 standard have been
removed and/or changed to refer to IEEE 754-2008.
-
All references to the General Decimal Arithmetic website have been updated
to
http://speleotrove.com/decimal
(its new location).
-
A problem in decFloatSubtract and decFloatQuantize due to
the ISCOEFFZERO macro re-using UBTOUI has been
corrected (this only affected compilers that take advantage of C99
strict aliasing rules).
This problem was previously published as an errata to 3.56.
-
A buffer in decQuadQuantize was two bytes too short when the
coefficient of the first operand had to be extended with 33 zeros;
this is now corrected.
This problem was previously published as an errata to 3.56.
23 March 2009:
The document is now formatted using OpenOffice (generated from GML),
for improved PDF files with bookmarks, hot links, etc. There are no
technical changes.
This release of decNumber is primarily a code maintenance
release. The changes are:
-
Minor problems in the decNumberLogB, decNumberScaleB, decDoubleIsSigned, and
decQuadIsSigned functions have been corrected.
These problems were previously published as errata to 3.61.
-
The decDoubleIsLogical, decDoubleIsNegative, and
decDoubleIsPositive functions have been added (also for
decQuad); these test whether the argument is valid for use as an
operand to the logical functions, or is less than zero, or is greater
than zero, respectively.
-
The DECPRINT compile-time parameter has been added. If set
to 0, this stops the package using the printf function.
[previous | contents]