The decNumber Library, version 3.68
Copyright (c) IBM Corporation, 2010. All rights reserved. ©
 23 Jan 2010 
[previous  contents  next]

The decNumber module defines the data structure used for representing
numbers in a form suitable for computation, and provides the functions
for operating on those values.
The decNumber structure is optimized for efficient processing of
relatively short numbers (tens or hundreds of digits); in particular it
allows the use of fixed sized structures and minimizes copy and move
operations. The functions in the module, however, support arbitrary
precision arithmetic (up to 999,999,999 decimal digits, with exponents
up to 9 digits).
The essential parts of a decNumber are the coefficient, which is
the significand of the number, the exponent (which indicates
the power of ten by which the coefficient should be multiplied),
and the sign, which is 1 if the number is negative, or 0
otherwise.
The numerical value of the number is then given by:
(1)^{sign}
× coefficient
× 10^{exponent}.
Numbers may also be a special value. The special values are
NaN (Not a Number), which may be quiet (propagates
quietly through operations) or signaling (raises the Invalid
operation condition when encountered), and ±infinity.
These parts are encoded in the four fields of the decNumber structure:
 digits

The digits field contains the length of the coefficient,
in decimal digits.
digits is of type int32_t, and must have a
value in the range 1 through 999,999,999.
 exponent

The exponent field holds the exponent of the number. Its range
is limited by the requirement that the range of the adjusted
exponent of the number be balanced and fit within a whole number of
decimal digits (in this implementation, be –999,999,999 through
+999,999,999). The adjusted exponent is the exponent that would result
if the number were expressed with a single digit before the decimal
point, and is therefore given by exponent+digits1.
When the extended flag in the context is 1, gradual underflow
(using subnormal values) is enabled. In this case,
the lower limit for the adjusted exponent becomes
–999,999,999–(precision–1), where
precision is the digits setting from the context; the adjusted
exponent may then have 10 digits.
exponent is of type int32_t.
 bits

The bits field comprises one bit which indicates the
sign of the number (1 for negative, 0 otherwise), 3 bits which
indicate the special values, and 4 further bits which are unused and
reserved. These reserved bits must be zero.
If the number has a special value, just one of the indicator bits
(DECINF, DECNAN, or DECSNAN) will be set (along
with DECNEG iff the sign is 1). If DECINF is set
digits must be 1 and the other fields must be 0. If the number
is a NaN, the exponent must be zero and the coefficient holds
any diagnostic information (with digits indicating its length,
as for finite numbers). A zero coefficient indicates no diagnostic
information.
bits is of type uint8_t (an unsigned byte).
Masks for the named bits, and some useful macros, are defined in the
header file.
 lsu

The lsu field is one or more units in length (of
type decNumberUnit, an unsigned integer),
and contains the digits of the coefficient. Each unit
represents one or more of the digits in the coefficient and has
a binary value in the range 0 through 10^{n}1,
where n is the number of digits in a unit, set by the
compiletime definition DECDPUN.
The size of a unit is the smallest of 1, 2, or 4 bytes which will
contain the maximum value held in the unit.
The units comprising the coefficient start with the least
significant unit (lsu).
Each unit except the most significant unit (msu) contains DECDPUN
digits. The msu contains from 1 through DECDPUN digits, and must
not be 0 unless digits is 1 (for the value zero).
Leading zeros in the msu are never included in the digits
count, except for the value zero.
The number of units predefined for the lsu field is determined
by DECNUMDIGITS, which defaults to 1 (the number of units will
be DECNUMDIGITS divided by DECDPUN, rounded up to a whole
unit).
For many applications, there will be a known maximum length for numbers
and DECNUMDIGITS can be set to that length, as in
Example 1.
In others, the length may vary over a wide range and it then becomes the
programmer’s responsibility to ensure that there are sufficient units
available immediately following the decNumber lsu field. This
can be achieved by enclosing the decNumber in other structures which
append various lengths of unit arrays, or in the more general case by
allocating storage with sufficient space for the other decNumber fields
and the units of the number.
lsu is an array of type decNumberUnit (an unsigned
integer whose length depends on the value of DECDPUN), with at
least one element. If digits needs fewer units than the size
of the array, remaining units are not used (they will neither be changed
nor referenced). For special values, only the first unit need be 0.
It is expected that decNumbers will usually be constructed by
conversions from other formats, such as strings or decimal64 structures,
so the decNumber structure is in some sense an ‘internal’
representation; in particular, it is machinedependent.^{[1]}
Examples:
If DECDPUN were 4, the value 1234.50 would be encoded with:
the value 0 would be:
and –¥ (minus infinity) would be:
Definitions
The decNumber.h header file defines the decNumber data structure
described above. It also includes:

The tuning parameter DECDPUN.
This sets the number of digits held in one unit,
which in turn alters the performance and other characteristics of the
library. Further details are given in the tuning
section.
If this parameter is changed, the decNumber.c source file must be
recompiled for the change to have effect.

The decClass enumeration (and corresponding strings) which is
used to classify decNumbers with the decNumberClass
function.

Constants naming the bits in the bits field,
such as DECNEG, the sign bit.

Definitions of the public functions and macros in the decNumber module.
Functions
The decNumber.c source file contains the public functions
defined in the header file. These comprise conversions to and from
strings, the arithmetic and logical operations, and some utility
functions.
The functions all follow some general rules:

Operands to the functions which are decNumber structures (referenced
by an argument) are never modified unless they are also specified to be
the result structure (which is always permitted).
Often, operations which do specify an operand and result as the same
structure can be carried out in place, giving improved performance.
For example, x=x+1, using the decNumberAdd function, can
be several times faster than x=y+1.

Each function forms its primary result by setting the content of one of
the structures referenced by the arguments; a pointer to this structure
is returned by the function.

Exceptional conditions and errors are reported by setting a bit in the
status field of a referenced decContext
structure. The corresponding bit in the traps field of the
decContext structure determines whether a trap is then raised, as
also described earlier.

If an argument to a function is corrupt (it is a NULL
reference, or it is an input argument and the content of the structure
it references is inconsistent), the function is unprotected (may
‘crash’) unless DECCHECK is enabled (see the next rule).
However, in normal operation (that is, no argument is corrupt), the
result will always be a valid decNumber structure.
The value of the decNumber result may be infinite or a quiet NaN if an
error was detected
(i.e., if one of the DEC_Errors
bits is set in the decContext status field).

For best performance, input operands are assumed to be valid (not
corrupt) and are not checked unless DECCHECK
is 1, which enables full operand checking.
Whether DECCHECK is 0 or 1, the value of a result is
undefined if an argument is corrupt. DECCHECK checking is a
diagnostic tool only; it will report the error and prevent code failure
by ensuring that results are valid numbers (unless the result reference
is NULL), but it does not attempt to correct arguments.
Conversion functions
The conversion functions build a decNumber from a string, or lay out a
decNumber as a character string. Additional Utility
functions are included in the package for conversions to and from
BCD strings and binary integers.
This function is used to convert a character string to decNumber format.
It implements the tonumber conversion from the arithmetic
specification.
The conversion is exact provided that the numeric string has no more
significant digits than are specified in context.digits and
the adjusted exponent is in the range specified
by context.emin and context.emax.
If there are more than context.digits digits in the string, or
the exponent is out of range, the value will be rounded as necessary
using the context.round rounding mode.
The context.digits field therefore both determines the maximum
precision for unrounded numbers and defines the minimum size of the
decNumber structure required.
The arguments are:
 number
 (decNumber *) Pointer to the structure to be set from the
character string.
 string
 (char *) Pointer to the input character string. This must
be a valid numeric string, as defined in the appropriate specification.
The string will not be altered.
 context
 (decContext *) Pointer to the context structure whose
digits, emin, and emax fields indicate the
maximum acceptable precision and exponent range, and whose
status field is used to report any errors.
If its extended field is 1, then special values
(±Inf, ±Infinity, ±NaN,
or ±sNaN, independent of case) are accepted, and the sign
and exponent of zeros are preserved. NaNs may also specify diagnostic
information as a string of digits following the name.
Returns number.
Possible errors are DEC_Conversion_syntax
(the string does not have the syntax of a number, which depends on the
setting of extended in the
context), DEC_Overflow (the adjusted exponent of the
number is larger than context.emax),
or DEC_Underflow (the adjusted exponent is less
than context.emin and the conversion is not exact).
If any of these conditions are set, the number structure will
have a defined value as described in the arithmetic specification (this
may be a subnormal or infinite value).
decNumberToString(number, string)
This function is used to convert a decNumber number to a character string,
using scientific notation if an exponent is needed (that is, there will
be just one digit before any decimal point).
It implements the toscientificstring conversion.
The arguments are:
 number
 (decNumber *) Pointer to the structure to be converted to a
string.
 string
 (char *) Pointer to the character string buffer which will
receive the converted number. It must be at least 14 characters longer
than the number of digits in the number (number>digits).
Returns string.
No error is possible from this function. Note that nonnumeric
strings (one of +Infinity, –Infinity, NaN,
or sNaN) are possible, and NaNs may have a – sign and/or
diagnostic information.
decNumberToEngString(number, string)
This function is used to convert a decNumber number to a character string,
using engineering notation (where the exponent will be a multiple of
three, and there may be up to three digits before any decimal point) if
an exponent is needed. It implements the toengineeringstring
conversion.
The arguments and result are the same as for the decNumberToString
function, and similarly no error is possible from this function.
The arithmetic and logical functions all follow the same syntax and
rules, and are summarized below.
They all take the following arguments:
 number
 (decNumber *) Pointer to the structure where the result will
be placed.
 lhs
 (decNumber *) Pointer to the structure which is the left
hand side (lhs) operand for the operation. This argument is omitted for
monadic operations.
 rhs
 (decNumber *) Pointer to the structure which is the right
hand side (rhs) operand for the operation.
 context
 (decContext *) Pointer to the context structure whose
settings are used for determining the result and for reporting any
exceptional conditions.
Each function returns number.
The decNumberFMA function also takes a third
numeric operand fhs (decNumber *), a pointer to the
structure which is the ‘far hand side’ operand for the
operation.
Some functions, such as decNumberExp, are described as
mathematical functions.
These have some restrictions: context.emax must be <
10^{6}, context.emin must be > –10^{6},
and context.digits must be < 10^{6}. Nonzero
operands to these functions must also fit within these bounds.
The precise definition of each operation can be found in the
specification document.
decNumberAbs(number, rhs, context)
The number is set to the absolute value of the rhs.
This has the same effect as decNumberPlus unless rhs is
negative, in which case it has the same effect as decNumberMinus.
decNumberAdd(number, lhs, rhs, context)
The number is set to the result of adding the lhs to
the rhs.
decNumberAnd(number, lhs, rhs, context)
The number is set to the result of the digitwise logical
and of lhs and rhs.
decNumberCompare(number, lhs, rhs, context)
This function compares two numbers numerically.
If the lhs is less than the rhs then the
number will be set to the value 1.
If they are equal (that is, when subtracted the result would be 0), then
number is set to 0.
If the lhs is greater than the rhs then the
number will be set to the value 1.
If the operands are not comparable (that is, one or both is a NaN)
the result will be NaN.
decNumberCompareSignal(number, lhs, rhs, context)
This function compares two numbers numerically. It is identical to
decNumberCompare except that all NaNs (including quiet NaNs) signal.
decNumberCompareTotal(number, lhs, rhs, context)
This function compares two numbers using the IEEE 754 total
ordering.
If the lhs is less than the rhs in the total order
then the number will be set to the value 1.
If they are equal, then
number is set to 0.
If the lhs is greater than the rhs then the
number will be set to the value 1.
The total order differs from the numerical comparison in that:
–NaN <
–sNaN <
–Infinity <
–finites <
–0 <
+0 <
+finites <
+Infinity <
+sNaN <
+NaN. Also, 1.000 < 1.0 (etc.) and NaNs are ordered by payload.
decNumberCompareTotalMag(number, lhs, rhs, context)
This function compares the magnitude of two numbers using the IEEE
754 total ordering. It is identical to decNumberCompareTotal
except that the signs of the operands are ignored and taken to be 0
(nonnegative).
decNumberDivide(number, lhs, rhs, context)
The number is set to the result of dividing the lhs by
the rhs.
decNumberDivideInteger(number, lhs, rhs, context)
The number is set to the integer part of the result of dividing
the lhs by the rhs.
Note that it must be possible to express the result as an integer. That
is, it must have no more digits than context.digits. If it does
then DEC_Division_impossible is raised.
decNumberExp(number, rhs, context)
The number is set to e raised to the power
of rhs, rounded if necessary using the digits setting in
the context and using the roundhalfeven rounding
algorithm.
Finite results will always be full precision and inexact, except
when rhs is a zero or –Infinity (giving 1 or 0
respectively). Inexact results will almost always be correctly
rounded, but may be up to 1 ulp (unit in last place) in error
in rare cases.
This is a mathematical function; the 10^{6} restrictions on
precision and range apply as described above.
The number is set to the result of multiplying the lhs
by the rhs and then adding fhs to that intermediate
result. It is equivalent to a multiplication followed by an addition
except that the intermediate result is not rounded and will not cause
overflow or underflow. That is, only the final result is rounded and
checked.
This is a mathematical function; the 10^{6} restrictions on
precision and range apply as described above.
decNumberInvert(number, rhs, context)
The number is set to the result of the digitwise inversion
of rhs (A 0 digit becomes 1 and vice versa.)
decNumberLn(number, rhs, context)
The number is set to the natural logarithm (logarithm in
base e) of rhs, rounded if necessary using the digits
setting in the context and using the
roundhalfeven rounding algorithm. rhs must be
positive or a zero.
Finite results will always be full precision and inexact, except
when rhs is equal to 1, which gives an exact result of 0.
Inexact results will almost always be correctly rounded, but may be
up to 1 ulp (unit in last place) in error in rare cases.
This is a mathematical function; the 10^{6} restrictions on
precision and range apply as described above.
decNumberLogB(number, rhs, context)
The number is set to the adjusted exponent of rhs,
according to the rules for the ‘logB’ operation of IEEE 754.
This returns the exponent of rhs as though its decimal point
had been moved to follow the first digit while keeping the same
value. The result is not limited by emin or emax.
decNumberLog10(number, rhs, context)
The number is set to the logarithm in base ten of
rhs, rounded if necessary using the digits setting in the
context and using the roundhalfeven rounding
algorithm. rhs must be positive or a zero.
Finite results will always be full precision and inexact, except
when rhs is equal to an integral power of ten, in which case
the result is the exact integer.
Inexact results will almost always be correctly rounded, but may be
up to 1 ulp (unit in last place) in error in rare cases.
This is a mathematical function; the 10^{6} restrictions on
precision and range apply as described above.
decNumberMax(number, lhs, rhs, context)
This function compares two numbers numerically and sets number
to the larger.
If the numbers compare equal then number is chosen with
regard to sign and exponent. Unusually, if one operand is a quiet
NaN and the other a number, then the number is returned.
decNumberMaxMag(number, lhs, rhs, context)
This function compares the magnitude of two numbers numerically and
sets number to the larger.
It is identical to decNumberMax except that the signs of the operands
are ignored and taken to be 0 (nonnegative).
decNumberMin(number, lhs, rhs, context)
This function compares two numbers numerically and sets number
to the smaller.
If the numbers compare equal then number is chosen with
regard to sign and exponent. Unusually, if one operand is a quiet
NaN and the other a number, then the number is returned.
decNumberMinMag(number, lhs, rhs, context)
This function compares the magnitude of two numbers numerically and
sets number to the smaller.
It is identical to decNumberMin except that the signs of the operands
are ignored and taken to be 0 (nonnegative).
decNumberMinus(number, rhs, context)
The number is set to the result of subtracting the rhs
from 0. That is, it is negated, following the usual arithmetic rules;
this may be used for implementing a prefix minus operation.
decNumberMultiply(number, lhs, rhs, context)
The number is set to the result of multiplying the lhs
by the rhs.
decNumberNextMinus(number, rhs, context)
The number is set to the closest value to rhs in
the direction of –Infinity.
This is computed as though by subtracting an infinitesimal amount
from rhs using DEC_ROUND_FLOOR,
except that no flags are set unless rhs is an sNaN.
This function is a generalization of the IEEE 754 nextDown
operation.
decNumberNextPlus(number, rhs, context)
The number is set to the closest value to rhs in
the direction of +Infinity.
This is computed as though by adding an infinitesimal amount
to rhs using DEC_ROUND_CEILING,
except that no flags are set unless rhs is an sNaN.
This function is a generalization of the IEEE 754 nextUp
operation.
decNumberNextToward(number, lhs, rhs, context)
The number is set to the closest value to lhs in
the direction of rhs.
This is computed as though by adding or subtracting an infinitesimal
amount to lhs using DEC_ROUND_CEILING
or DEC_ROUND_FLOOR, depending on whether
rhs is larger or smaller than lhs.
If rhs is numerically equal to lhs then the result
is a copy of lhs with the sign taken from
rhs.
Flags are set as usual for an addition or subtraction except that if
the operands are equal or the result is normal (finite, nonzero, and
not subnormal) no flags are set.
This function is a generalization of the proposed IEEE 754 nextAfter
operation.^{[2]}
decNumberOr(number, lhs, rhs, context)
The number is set to the result of the digitwise logical
inclusive or of lhs and rhs.
decNumberPlus(number, rhs, context)
The number is set to the result of adding the rhs
to 0. This takes place according to the settings given in the
context, following the usual arithmetic rules. This may
therefore be used for rounding or for implementing a prefix plus
operation.
The number is set to the result of raising the lhs
to the power of the rhs, rounded if necessary using the
settings in the context.
Results will be exact when the rhs has an integral value and
the result does not need to be rounded, and also will be exact in
certain special cases, such as when the lhs is a zero (see
the arithmetic specification for details).
Inexact results will always be full precision, and will almost always
be correctly rounded, but may be up to 1 ulp (unit in last
place) in error in rare cases.
This is a mathematical function; the 10^{6} restrictions on
precision and range apply as described above, except that the normal
range of values and context is allowed if the rhs has an
integral value in the range –1999999997 through +999999999.^{[3]}
This function is used to modify a number so that its exponent has a
specific value, equal to that of the rhs.
The decNumberRescale function may also be used for
this purpose, but requires the exponent to be given as a decimal number.
When rhs is a finite number, its exponent is
used as the requested exponent (it provides a ‘pattern’ for the
result). Its coefficient and sign are ignored.
The number is set to a value which is numerically equal (except
for any rounding) to the lhs, modified as necessary so that it
has the requested exponent.
To achieve this, the coefficient of the number is adjusted
(by rounding or shifting) so that its exponent has the
requested value.
For example, if the lhs had the value 123.4567, and
the rhs had the value 0.12, the result would
be 123.46 (that is, 12346 with an exponent
of 2, matching the exponent of the rhs).
Note that the exponent of the rhs may be positive, which will
lead to the number being adjusted so that it is a multiple of
the specified power of ten.
If adjusting the exponent would mean that more than context.digits
would be needed in the coefficient, then
the DEC_Invalid_operation condition is
raised.
This guarantees that in the absence of error the exponent of
number is always equal to that of the rhs.
If either operand is a special value then the usual rules
apply, except that if either operand is infinite and the other is finite
then the DEC_Invalid_operation condition is
raised, or if both are infinite then the result is the first operand.
decNumberRemainder(number, lhs, rhs, context)
Integerdivides lhs by rhs and places the remainder
from the division in number.
That is, if the same lhs, rhs, and context
arguments were given to the decNumberDivideInteger and
decNumberRemainder functions, resulting in i and r
respectively, then the identity
holds.
Note that, as for decNumberDivideInteger, it must be possible to express
the integer part of the result (i) as an integer. That
is, it must have no more digits than context.digits. If it
does have more
then DEC_Division_impossible is raised.
decNumberRemainderNear(number, lhs, rhs, context)
The number is set to the remainder when lhs is divided
by the rhs, using the rules defined in IEEE 754. This follows
the same definition as decNumberRemainder, except that the nearest
integer (or the nearest even integer if the remainder is equidistant
from two) is used for i instead of the result from
decNumberDivideInteger.
For example, if lhs had the value 10 and rhs had the
value 6 then the result would be 2 (instead of 4) because the nearest
multiple of 6 is 12 (rather than 6).
This function is used to rescale a number so that its exponent has a
specific value, given by the rhs.
The decNumberQuantize function may also be used for
this purpose, and is often easier to use.
The rhs must be a whole number (before any rounding); that is,
any digits in the fractional part of the number must be zero. It must
have no more than nine digits, or context.digits digits,
(whichever is smaller) in the integer part of the number.
The number is set to a value which is numerically equal (except
for any rounding) to the lhs, rescaled so that it has the
requested exponent.
To achieve this, the coefficient of the number is adjusted
(by rounding or shifting) so that its exponent has the value of
the rhs.
For example, if the lhs had the value 123.4567, and
decNumberRescale was used to set its exponent to 2, the result
would be 123.46 (that is, 12346 with an exponent
of 2).
Note that the rhs may be positive, which will lead to the
number being adjusted so that it is a multiple of the specified
power of ten.
If adjusting the scale would mean that more than context.digits
would be needed in the coefficient, then
the DEC_Invalid_operation condition is
raised.
This guarantees that in the absence of error the exponent of
number is always equal to the rhs.
This function is used to rotate the digits in the coefficient of a
number as though its coefficient had the length given
by context.digits and its mostsignificant digit were
connected to its leastsignificant digit.
The number is set to a copy of lhs with the
digits of its coefficient rotated to the left (if rhs
is positive) or to the right (if rhs is negative) without
adjusting the exponent or the sign. If lhs has fewer digits
than context.digits the coefficient is padded with zeros on
the left before the rotate. Any insignificant leading zeros in the
result are removed, as usual.
rhs is the count of digits to rotate; it must be an integer
(that is, it must have an exponent of 0) and must be in the
range –context.digits through +context.digits.
This function is used to test whether the exponents of two numbers are
equal.
The coefficients and signs of the operands (lhs and
rhs) are ignored.
If the exponents of the operands are equal, or if they are both Infinities
or they are both NaNs, number is set to 1. In all other cases,
number is set to 0. No error is possible.
decNumberScaleB(number, lhs, rhs, context)
This function is used to adjust (scale) the exponent of a number,
using the rules of the ‘scaleB’ operation in IEEE 754.
The number is set to the result of multiplying
lhs by ten raised to the power of rhs. rhs
must be an integer (that is, it must have an exponent of 0)
and it must also be in the range –1999999997 through
+999999999.^{[4]}
This function is used to shift the digits in the coefficient of a
number.
The number is set to a copy of lhs with the
digits of its coefficient shifted to the left (if rhs
is positive) or to the right (if rhs is negative) without
adjusting the exponent or the sign. The coefficient is padded with
zeros on the left or right, as necessary. Any leading zeros in the
result are ignored, as usual.
rhs is the count of digits to shift; it must be an integer
(that is, it must have an exponent of 0) and must be in the
range –context.digits through +context.digits.
decNumberSquareRoot(number, rhs, context)
The number is set to the square root of the rhs,
rounded if necessary using the digits setting in the context
and using the roundhalfeven rounding algorithm. The
preferred exponent of the result is floor(exponent/2).
decNumberSubtract(number, lhs, rhs, context)
The number is set to the result of subtracting the rhs
from the lhs.
decNumberToIntegralExact(number, rhs, context)
The number is set to the rhs, with any fractional part
removed if necessary using the rounding mode in the context.
The Inexact flag is set if the result is numerically different
from rhs. Other than that, no flags are set (unless the
operand is a signaling NaN). The result may have a positive
exponent.
decNumberToIntegralValue(number, rhs, context)
The number is set to the rhs, with any fractional part
removed if necessary using the rounding mode in the context.
No flags, not even Inexact, are set (unless the operand is a
signaling NaN). The result may have a positive exponent.
decNumberXor(number, lhs, rhs, context)
The number is set to the result of the digitwise logical
exclusive or of lhs and rhs.
The utility functions include copying, trimming, test, and
initializing functions, along with specialized conversions and a
function for determining the version of the decNumber package.
This function is used to determine the class of a decNumber.
The arguments are:
 number
 (decNumber *) Pointer to the decNumber to be classified.
 context
 (decContext *) Pointer to the context (the value of
emin is used to determine if a finite number is normal or
subnormal).
Returns an enum decClass (defined in decNumber.h),
which can be converted to a character string using decNumberClassToString.
No error is possible from this function.
decNumberClassToString(number, context)
This function is used to convert a decClass enumeration to a string.
The argument is:
 class
 (enum decClass) The enumeration to be converted.
Returns a string (const char *) which points to one of the
constant strings "sNaN", "NaN",
"Infinity",
"Normal", "Subnormal",
"Zero", "+Zero", "+Subnormal", "+Normal",
"+Infinity", or "Invalid". No error is possible from this
function.
decNumberCopy(number, source)
This function is used to copy the content of one decNumber structure to
another. It is used when the structures may be of different sizes and
hence a straightforward structure copy by C assignment is inappropriate.
It also may have performance benefits when the number is short relative
to the size of the structure, as only the units containing the digits in
use in the source structure are copied.
The arguments are:
 number
 (decNumber *) Pointer to the structure to receive the copy.
It must have space for source>digits digits.
 source
 (decNumber *) Pointer to the structure which will be copied
to number.
All fields
are copied, with the units containing
the source>digits digits being copied starting from
lsu. The source structure is unchanged.
Returns number. No error is possible from this function.
decNumberCopyAbs(number, source)
This function is used to copy the absolute value of the content of
one decNumber structure to another. It is identical to decNumberCopy
except that the sign of the result is always 0. This is
equivalent to the quiet abs function described in IEEE 754.
Returns number. No error is possible from this function.
decNumberCopyNegate(number, source)
This function is used to copy the value of the content of one
decNumber structure to another while inverting its sign. It is
identical to decNumberCopy except that the sign of the
result is the inverse of that in source. This is equivalent
to the quiet negate function described in IEEE 754.
Returns number. No error is possible from this function.
decNumberCopySign(number, source, pattern)
This function is used to copy the value of the content of one
decNumber structure to another and changing its sign to that of a
third. It is identical to decNumberCopy except that the
sign of the result is taken from the third argument instead
of from source. This is equivalent to the quiet
copysign function described in IEEE 754.
The first two arguments are as for decNumberCopy. The third is:
 pattern
 (decNumber *) Pointer to the structure which provides the
sign.
Returns number. No error is possible from this function.
decNumberFromInt32(number, i)
This function is used to convert a signed (two’s complement) 32bit
binary integer to a decNumber.
The arguments are:
 number
 (decNumber *) Pointer to the structure that will received
the converted integer. This must have space for the digits needed to
represent the value of i, which may need up to ten digits.
 i
 (int32_t) The integer to be converted.
Returns number. No error is possible from this function.
decNumberFromUInt32(number, u)
This function is used to convert an unsigned 32bit
binary integer to a decNumber.
The arguments are:
 number
 (decNumber *) Pointer to the structure that will received
the converted integer. This must have space for the digits needed to
represent the value of u, which may need up to ten digits.
 u
 (uint32_t) The integer to be converted.
Returns number. No error is possible from this function.
decNumberGetBCD(number, bcd)
This function is used to convert the coefficient of a decNumber to
Binary Coded Decimal, one digit (value 0–9) per byte.
The arguments are:
 number
 (decNumber *) Pointer to the structure containing the
coefficient to be converted.
 bcd
 (uint8_t *) Pointer to the byte array which
will receive the converted coefficient; the most significant digit of
the coefficient will be placed in bcd[0].
The first number>digits elements of bcd will have
their values set; no other elements are affected.
Returns bcd. No error is possible from this function.
decNumberIsCanonical(number)
This function is used to test whether the encoding of a decNumber is
canonical.
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
Returns 1 (true) always, because decNumbers always have canonical
encodings (the function is provided for compatibility with the IEEE
754 operation isCanonical).
This function may be implemented as a macro; no error is possible.
This function is used to test whether a number is finite.
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
Returns 1 (true) if the number is finite, or 0 (false) otherwise
(that is, it is an infinity or a NaN).
This function may be implemented as a macro; no error is possible.
decNumberIsInfinite(number)
This function is used to test whether a number is infinite.
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
Returns 1 (true) if the number is infinite, or 0 (false) otherwise
(that is, it is a finite number or a NaN).
This function may be implemented as a macro; no error is possible.
decNumberIsNaN(number)
This function is used to test whether a number is a NaN (quiet or
signaling).
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
Returns 1 (true) if the number is a NaN, or 0 (false) otherwise.
This function may be implemented as a macro; no error is possible.
decNumberIsNegative(number)
This function is used to test whether a number is negative (either
minus zero, less than zero, or a NaN with a sign of 1).
Note that in the decFloats packages, this is called (for example)
decQuadIsSigned, and decQuadIsNegative does not
include zeros or NaNs.
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
Returns 1 (true) if the number is negative, or 0 (false) otherwise.
This function may be implemented as a macro; no error is possible.
decNumberIsNormal(number)
This function is used to test whether a number is normal (that is,
finite, nonzero, and not subnormal).
The arguments are:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
 context
 (decContext *) Pointer to the context (the value of
emin is used to determine if a finite number is normal or
subnormal).
Returns 1 (true) if the number is normal, or 0 (false) otherwise.
This function may be implemented as a macro; no error is possible.
decNumberIsQNaN(number)
This function is used to test whether a number is a Quiet NaN.
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
Returns 1 (true) if the number is a Quiet NaN, or 0 (false) otherwise.
This function may be implemented as a macro; no error is possible.
decNumberIsSNaN(number)
This function is used to test whether a number is a Signaling NaN.
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
Returns 1 (true) if the number is a Signaling NaN, or 0 (false) otherwise.
This function may be implemented as a macro; no error is possible.
decNumberIsSpecial(number)
This function is used to test whether a number has a special value
(Infinity or NaN); it is the inversion of decNumberIsFinite.
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
Returns 1 (true) if the number is special, or 0 (false) otherwise.
This function may be implemented as a macro; no error is possible.
decNumberIsSubnormal(number)
This function is used to test whether a number is subnormal (that is,
finite, nonzero, and magnitude less than 10^{emin}).
The arguments are:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
 context
 (decContext *) Pointer to the context (the value of
emin is used to determine if a finite number is normal or
subnormal).
Returns 1 (true) if the number is subnormal, or 0 (false) otherwise.
This function may be implemented as a macro; no error is possible.
decNumberIsZero(number)
This function is used to test whether a number is a zero (either
positive or negative).
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
tested.
Returns 1 (true) if the number is zero, or 0 (false) otherwise.
This function may be implemented as a macro; no error is possible.
decNumberRadix()
This function returns the radix (number base) used by the decNumber
package. This always returns 10.
This function may be implemented as a macro; no error is possible.
This function has the same effect as decNumberPlus except that the final
result is set to its simplest (shortest) form without changing its
value.
That is, a nonzero number which has any trailing zeros in the
coefficient has those zeros removed by dividing the coefficient by the
appropriate power of ten and adjusting the exponent accordingly, and a
zero has its exponent set to 0.
The decNumberTrim function can be used to
remove only fractional trailing zeros.
This function was previously called decNumberNormalize (and is
still available under that name for compatibility).
decNumberSetBCD(number, bcd, n)
This function is used to set the coefficient of a decNumber from a
Binary Coded Decimal array which has one digit (value 0–9) per byte.
The arguments are:
 number
 (decNumber *) Pointer to the structure whose
coefficient is to be set.
 bcd
 (uint8_t *) Pointer to the byte array which
provides the coefficient; the most significant digit of
the coefficient is at bcd[0] and the least significant
is at bcd[n1].
 n
 (uint32_t *) Count of the BCD digits to be
converted.
number must have space for at least n digits.
If number is a NaN, or is Infinite, or is to become a zero,
n must be 1 and bcd[0] must be zero.
Returns number. No error is possible from this function.
decNumberToInt32(number, context)
This function is used to convert a decNumber to a signed (two’s
complement) 32bit binary integer.
The arguments are:
 number
 (decNumber *) Pointer to the structure that will have its
value converted.
 context
 (decContext *) Pointer to the context (used only for
reporting an error).
The DEC_Invalid_operation condition is
raised if number does not have an exponent of 0, or if
it is a NaN or Infinity, or if it is outofrange (cannot be represented).
In this case the result is 0.
Note that a –0 is not out of range (it is numerically equal to
zero and will be converted without raising the condition).
Returns the signed integer (int32_t).
decNumberToUInt32(number, context)
This function is used to convert a decNumber to an unsigned
32bit binary integer.
The arguments are:
 number
 (decNumber *) Pointer to the structure that will have its
value converted.
 context
 (decContext *) Pointer to the context (used only for
reporting an error).
The DEC_Invalid_operation condition is
raised if number does not have an exponent of 0, or if
it is a NaN or Infinity, or if it is outofrange (cannot be represented).
In this case the result is 0. Note that a –0 is not out of
range (but all values less than zero are).
Returns the unsigned integer (uint32_t).
This function is used to remove insignificant trailing zeros from a
number, uncoditionally. That is, if the number has any fractional
trailing zeros they are removed by dividing the coefficient by the
appropriate power of ten and adjusting the exponent accordingly.
The decNumberReduce function can be used to
remove all trailing zeros.
The argument is:
 number
 (decNumber *) Pointer to the structure whose value is to be
trimmed.
Returns number. No error is possible from this function.
decNumberVersion()
This function returns a pointer (char *) to a humanreadable
description of the version of the decNumber package being run. The
string pointed to will have at most 16 characters and will be a
constant, and will comprise two words (the name and a decimal number
identifying the version) separated by a blank.
For example:
decNumber 3.40
No error is possible from this function.
decNumberZero(number)
This function is used to set the value of a decNumber structure to zero.
The argument is:
 number
 (decNumber *) Pointer to the structure to be set to 0.
It must have space for one digit.
Returns number. No error is possible from this function.
Footnotes:
[1] 
The layout of an integer might be bigendian or littleendian, for
example.

[2] 
The nextAfter operation was dropped from the proposed standard during
the ballot process.

[3] 
This relaxation of the restrictions provides upwards compatibility
with an earlier version of the decNumberPower function which could
only handle an rhs with an integral value.

[4] 
This range is an implementation restriction and is smaller than that suggested
by the arithmetic specification. The restriction can be worked
around by calling the function more than once.

[previous  contents  next]