decNumber module

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+digits-1.

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ⁿ-1, where n is the number of digits in a unit, set by the compile-time 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 machine-dependent.^[1] 

Examples:

If DECDPUN were 4, the value -1234.50 would be encoded with:

Definitions

• 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 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

decNumberFromString(number, string, context)

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)

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 non-numeric strings (one of +Infinity, –Infinity, NaN, or sNaN) are possible, and NaNs may have a – sign and/or diagnostic information.

decNumberToEngString(number, string)

The arguments and result are the same as for the decNumberToString function, and similarly no error is possible from this function.

Arithmetic and logical functions

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⁶, context.emin must be > –10⁶, and context.digits must be < 10⁶. Non-zero 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)

decNumberAdd(number, lhs, rhs, context)

decNumberAnd(number, lhs, rhs, context)

decNumberCompare(number, lhs, rhs, context)

decNumberCompareSignal(number, lhs, rhs, context)

decNumberCompareTotal(number, lhs, rhs, context)

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)

decNumberDivide(number, lhs, rhs, context)

decNumberDivideInteger(number, lhs, rhs, context)

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)

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⁶ restrictions on precision and range apply as described above.

decNumberFMA(number, lhs, rhs, fhs, context)

This is a mathematical function; the 10⁶ restrictions on precision and range apply as described above.

decNumberInvert(number, rhs, context)

decNumberLn(number, rhs, context)

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⁶ restrictions on precision and range apply as described above.

decNumberLogB(number, rhs, context)

decNumberLog10(number, rhs, context)

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⁶ restrictions on precision and range apply as described above.

decNumberMax(number, lhs, rhs, context)

decNumberMaxMag(number, lhs, rhs, context)

decNumberMin(number, lhs, rhs, context)

decNumberMinMag(number, lhs, rhs, context)

decNumberMinus(number, rhs, context)

decNumberMultiply(number, lhs, rhs, context)

decNumberNextMinus(number, rhs, context)

This function is a generalization of the IEEE 754 nextDown operation.

decNumberNextPlus(number, rhs, context)

This function is a generalization of the IEEE 754 nextUp operation.

decNumberNextToward(number, lhs, rhs, context)

This function is a generalization of the proposed IEEE 754 nextAfter operation.^[2] 

decNumberOr(number, lhs, rhs, context)

decNumberPlus(number, rhs, context)

decNumberPower(number, lhs, rhs, 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⁶ 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] 

decNumberQuantize(number, lhs, rhs, context)

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)

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

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)

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

decNumberRescale(number, lhs, rhs, context)

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.

decNumberRotate(number, lhs, rhs, context)

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.

decNumberSameQuantum(number, lhs, rhs)

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)

decNumberShift(number, lhs, rhs, context)

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)

decNumberSubtract(number, lhs, rhs, context)

decNumberToIntegralExact(number, rhs, 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)

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)

Utility functions

decNumberClass(number, context)

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)

class

(enum decClass) The enumeration to be converted.

decNumberCopy(number, source)

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)

Returns number. No error is possible from this function.

decNumberCopyNegate(number, source)

Returns number. No error is possible from this function.

decNumberCopySign(number, source, pattern)

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)

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)

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)

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)

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.

decNumberIsFinite(number)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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()

decNumberReduce(number, rhs, context)

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)

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[n-1].

n

(uint32_t *) Count of the BCD digits to be converted.

Returns number. No error is possible from this function.

decNumberToInt32(number, context)

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 out-of-range (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)

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 out-of-range (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).

decNumberTrim(number)

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()

  decNumber 3.40

decNumberZero(number)

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.