## decNumber module

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 × 10exponent.

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 10n-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.

Examples:

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

• digits = 6
• exponent = -2
• bits = 0x80
• lsu = {3450, 12}
• the value 0 would be:
• digits = 1
• exponent = 0
• bits = 0x00
• lsu = {0}
• and –¥ (minus infinity) would be:
• digits = 1
• exponent = 0
• bits = 0xC0
• lsu = {0}

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

#### decNumberFromString(number, string, context)

This function is used to convert a character string to decNumber format. It implements the to-number 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 to-scientific-string 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 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)

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 to-engineering-string conversion.

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

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 < 106, context.emin must be > –106, and context.digits must be < 106. 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)

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.

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 digit-wise 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 (non-negative).

#### 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 round-half-even 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 106 restrictions on precision and range apply as described above.

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

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

#### decNumberInvert(number, rhs, context)

The number is set to the result of the digit-wise 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 round-half-even 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 106 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 round-half-even 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 106 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 (non-negative).

#### 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 (non-negative).

#### 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, non-zero, and not subnormal) no flags are set.

This function is a generalization of the proposed IEEE 754 nextAfter operation.

#### decNumberOr(number, lhs, rhs, context)

The number is set to the result of the digit-wise 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.

#### decNumberPower(number, lhs, rhs, context)

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

#### decNumberQuantize(number, lhs, rhs, context)

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)

Integer-divides 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

• lhs = (i × rhs) + r
• 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).

#### decNumberRescale(number, lhs, rhs, context)

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.

#### decNumberRotate(number, lhs, rhs, context)

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 most-significant digit were connected to its least-significant 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.

#### decNumberSameQuantum(number, lhs, rhs)

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.

#### decNumberShift(number, lhs, rhs, context)

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 round-half-even 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 digit-wise logical exclusive or of lhs and rhs.

### Utility functions

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.

#### decNumberClass(number, context)

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

#### decNumberIsFinite(number)

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, non-zero, 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, non-zero, and magnitude less than 10emin).

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.

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.

#### decNumberReduce(number, rhs, context)

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 non-zero 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 and the least significant is at bcd[n-1].

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 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) 32-bit 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 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)

This function is used to convert a decNumber to an unsigned 32-bit 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 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)

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 human-readable 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:
  The layout of an integer might be big-endian or little-endian, for example.  The nextAfter operation was dropped from the proposed standard during the ballot process.  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.  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]