The DFPAL Library, version 2.20 © Copyright IBM Corporation, 2007. All rights reserved. 

[previous  contents  next]  [printer friendly] 
Decimal floating point operations are classified into the following categories.
Programming NoteThis guide refers todecimalNN...() routines. However, it is highly recommended that application program to decNN...() macros for easy migration to compiler native decimal floating point using the DFPAL_USE_COMPILER_DFP compile time switch. Refer to How to compile DFPAL? for more information. The decNN...() macros are listed in square brackets.
Not all the facilities listed below is a part of the current Extension for the programming language C to support decimal floatingpoint arithmetic working draft technical report by the ISO/IEC JTC1 SC22 WG14 committee. The proposal for extension is continuously evolving. Refer to the current draft of the proposal for extension. Adhering to the facilities listed in the proposal for extension may simplify migration to compiler native decimal floating point usage later. 
rhs
from decimalNN to equivalent string representation, populate memory location pointed by the out
parameter. Returns same memory location as out
. Memory must be preallocated by application.
dfpstr
into decimalNN number. Exceptions are raised as discussed in General Decimal Arithmetic Specification.
rhs
to binary floating point double representation. There will be lost precision and/or slight inaccuracy converting between these representations. Input sNaN
is converted to NaN
, because double value of sNaN
is not portable.
rhs
in packed binary coded decimal (BCD) string. The bcdOutLen
is length of the input array bcdOut
. Then length must be at least 9 bytes (for decimal64
) or 18 bytes (for decimal128
), otherwise unchanged bcdOut
is returned. The scale
is output – scale of the rhs
. The output array will be populated in right aligned order. That is, highest array index will hold least significant digit nibble and a sign nibble. Application must preallocated enough memory for the bcdOut
, and clear the array content if necessary. Output sign is C
(for +ve number) or D
(for –ve number).
bcdIn
into decimalNN number, return decimalNN. The bcdInLen
is length of input array bcdIn
. The length must be at least 9 bytes (for decimal64) or 18 bytes (for decimal128), or NaN is returned. The input scale
is used to set exponent of the output number. The input bcdIn
is assumed to be right aligned. That is, highest array index will hold least significant nibble and a sign nibble. Input sign nibble must be present, and it is assumed to be C
(for +ve number) or D
(for –ve number). When the input array in larger than 9 bytes (for decimal64) or 18 bytes (for decimal128), no more than 16 digits (for decimal64) or 34 digits (for decimal128) shall be present. Application can preprocess input array before passing it to the decimalNNFromPackedBCD()
to ensure that above rules are observed. This rules are imposed to reconcile rounding effect between hardware and software implementations of the decimal floating point.
rhs
into decimal32 format. In case of lost precision INEXACT
exception is raised. Note: this function is intended to be used for decimal32 arithmetic emulation. The INVALID
exception is not raised on sNaN input to avoid any side effect.
rhs
into decimal64 format. No exceptions are possible. Note: this function is intended to be used for decimal32 arithmetic emulation. The INVALID
exception is not raised on sNaN input to avoid any side effect.
General integer conversion rulesFor conversion to integer, noINEXACT exception is raised even if there are lost digit(s). Conversion to integer is not performed with current rounding mode, rounding mode is always truncate. (Conversion to integer with desired rounding mode can be performed by using decimalNNToIntegralValue() function followed by either decimalNNToIntXX() or decimalNNToUintXX() conversion.).
For out of bound or Infinite input that cannot be represented in the destination format, an integer with largest magnitude in the direction of the sign with the same sign as source (input) is returned with INVALID exception raised. For example, converting decimalNN to 64bit signed integer, an input of +Infinite (or say 1E+100) will return 9223372036854775807 , Infinite (or say 1E+100) will return 9223372036854775808 , The INVALID exception is raised in either case.
For +/sNaN or +/NaN input smallest possible integer is returned, regardless of the source (input) sign. For example, converting decimalNN value +NaN to 64bit signed integer, return value is 9223372036854775808 regardless of the input sign. The INVALID exception raised.
Negative source (input) is considered out of bound value for unsigned integer conversion, largest magnitude in the direction of the –ve sign is 0 for the unsigned integer. Similarly, smallest possible integer, which is 0 is returned for +/NaN or +/sNaN input with INVALID exception raised.
In case of conversion from integer to decimalNN, current rounding mode is used and INEXACT exception may be raised, especially when converting 64bit integer to decimal64. Because maximum precision for decimal64 is 16 digits and integer may need up to 20 digits for exact representation. No other exceptions are possible.

rhs
to equivalent 64bit signed integer value. The general integer conversion rules apply. The output 64bit signed integer is in range [9223372036854775808, 9223372036854775807]
.
rhs
to equivalent 64bit unsigned integer value. The general integer conversion rules apply. The output 64bit unsigned integer is in range [0, 18446744073709551615]
.
rhs
to equivalent 32bit signed integer value. The general integer conversion rules apply. The output 32bit signed integer is in range [2147483648, 2147483647]
.
rhs
to equivalent 32bit unsigned integer value. The general integer conversion rules apply. The output 32bit unsigned integer is in range [0, 4294967295]
.
rhs
to equivalent decimalNN format. The general integer conversion rules apply.
rhs
to equivalent decimalNN format. The general integer conversion rules apply.
rhs
to equivalent decimalNN format. The general integer conversion rules apply.
rhs
to equivalent decimalNN format. The general integer conversion rules apply.
rhs
. Returns integer nonzero value (boolean 1) if rhs
is –ve, 0 otherwise.
rhs
.
rhs
.
rhs
is +/Infinite, 0 otherwise.
rhs
is either +/qNaN or +/sNaN, 0 otherwise.
rhs
is +/qNaN, 0 otherwise.
rhs
is +/sNaN, 0 otherwise.
rhs
is –ve number, 0 otherwise. This function is similar to the decNNSign()
.
rhs
numeric value is +/0, 0 otherwise.
rhs
. 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.
rhs
.
rhs
.
rhs
.
lsh
and rhs
, return result of the add operation.
lsh
and rhs
, return decmimalNN –1 if lsh
is less than rhs
, decimalNN 0 if lsh
is equal to rhs
, and decmimalNN +1 if lsh
is greater than rhs
.
lsh
and rhs
, return boolean 1 if lsh
is less than rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompare()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
, return boolean 1 if lsh
is less than or equal to rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompare()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
, return boolean 1 if lsh
is equal to rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompare()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
, return boolean 1 if lsh
is not equal to rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompare()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
, return boolean 1 if lsh
is greater than rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompare()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
, return boolean 1 if lsh
is greater than or equal to rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompare()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
, return decmimalNN –1 if lsh
is less than rhs
, decimalNN 0 if lsh
is equal to rhs
, and decmimalNN +1 if lsh
is greater than rhs
. Unlike, regular compare, compare Total compares numbers using abstract representation. Refer to Decimal Arithmetic Specification for more details.
lsh
and rhs
using total order, return boolean 1 if lsh
is less than rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompareTotal()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
using total order, return boolean 1 if lsh
is less than or equal to rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompareTotal()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
using total order, return boolean 1 if lsh
is equal to rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompareTotal()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
using total order, return boolean 1 if lsh
is not equal to rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompareTotal()
for use in programming language conditional constructs such as if
, for
or while
statement.
lsh
and rhs
using total order, return boolean 1 if lsh
is greater than rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompareTotal()
for use in programming language conditional constructs such such as if
, for
or while
statement.
lsh
and rhs
using total order, return boolean 1 if lsh
is greater than or equal to rhs
. This macro is convenient, fast and it is recommended over the decimalNNCompareTotal()
for use in programming language conditional constructs such such as if
, for
or while
statement.
lsh
with rhs
, return result.
lsh
with rhs
, return integer part of the quotient.
rhs
. Refer to decNumber module for more information.
rhs
. Refer to decNumber module for more information.
rhs
. Refer to decNumber module for more information.
lsh
and rhs
. Note that regular numeric comparison operation is used.
lsh
and rhs
. Note that regular numeric comparison operation is used.
rhs
. This can be used as unary negate operation.
lsh
and rhs
, return result of the multiply operation.
rhs
, derived from the rhs
by removing trailing zeros in the coefficient. Zeros removed by dividing the coefficient by the appropriate power of ten and adjusting the exponent accordingly.
rhs
. This function essentially noop, provided for identity with the decimalNNMinus()
.
lhs
to the power of the rhs
. Refer to decNumber module for more information.
decimalNNPower()
, however the second argument rhs
is integer. Useful for square, or cube of the lhs
.
lhs
so that its exponent has a specific value, equal to that of the rhs
. The decimalNNRescale()
function may also be used for this purpose, but requires the exponent to be given as a decimal number.
lhs
is divided by the rhs
.
lhs
is divided by the rhs, using the rules defined in IEEE 854. This follows the same definition as decimalNNRemainder()
, except that the nearest integer (or the nearest even integer if the remainder is equidistant from two) is used for the quotient instead of the result from decimalNNDivideInteger()
.
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).
decimalNNQuantize()
, however, the second argument rhs
specifies new exponent. The rhs
must be a whole number (before any rounding); that is, any digits in the fractional part of the number must be zero. decimalNNQuantize()
is faster and it is recommended over decimalNNRescale()
. This function may be removed from the future release.
lhs
and rhs
have equal exponent. Return 0, otherwise.
rhs
.
lsh
and rhs
, return result of the subtract operation.
decimalNNToInt...()
, the result may have a positive exponent.
rhs
. No exceptions, not even INEXACT
, are raised (unless the operand is sNaN). The result may have a positive exponent.
rhs
. No exceptions, not even INEXACT
, are raised (unless the operand is sNaN). The result may have a positive exponent.
DFPAL is authored by Punit Shah (punit@us.ibm.com).
Please send any corrections, comments or questions to dfpall@austin.ibm.com.
This page was updated on 21 Dec 2007. 