The decNumber Library, version 3.36
Copyright (c) IBM Corporation, 2006. All rights reserved. ©
6 Jul 2006
[previous | contents | next]

decContext module

The decContext module defines the data structure used for providing the context for operations and for managing exceptional conditions.

The decContext structure comprises the following fields:

digits
The digits field is used to set the precision to be used for an operation. The result of an operation will be rounded to this length if necessary, and hence the space needed for the result decNumber structure is limited by this field.

digits is of type int32_t, and must have a value in the range 1 through 999,999,999.

emax
The emax field is used to set the magnitude of the largest adjusted exponent that is permitted. The adjusted exponent is calculated as though the number were expressed in scientific notation (that is, except for 0, expressed with one non-zero digit before the decimal point).

If the adjusted exponent for a result or conversion would be larger than emax then an overflow results.

emax is of type int32_t, and must have a value in the range 0 through 999,999,999.

emin
The emin field is used to set the smallest adjusted exponent that is permitted for normal numbers. The adjusted exponent is calculated as though the number were expressed in scientific notation (that is, except for 0, expressed with one non-zero digit before the decimal point).

If the adjusted exponent for a result or conversion would be smaller than –emin then the result is subnormal. If the result is also inexact, an underflow results. The exponent of the smallest possible number (closest to zero) will be emindigits+1.[1] 

emin will usually equal –emax, but when a compressed format is used it will be –(emax–1).

emin is of type int32_t, and must have a value in the range –999,999,999 through 0.

round
The round field is used to select the rounding algorithm to be used if rounding is necessary during an operation. It must be one of the values in the rounding enumeration:

DEC_ROUND_CEILING
Round towards +Infinity.

DEC_ROUND_DOWN
Round towards 0 (truncation).

DEC_ROUND_FLOOR
Round towards –Infinity.

DEC_ROUND_HALF_DOWN
Round to nearest; if equidistant, round down.

DEC_ROUND_HALF_EVEN
Round to nearest; if equidistant, round so that the final digit is even.

DEC_ROUND_HALF_UP
Round to nearest; if equidistant, round up.

DEC_ROUND_UP
Round away from 0.

status
The status field comprises one bit for each of the exceptional conditions described in the specifications (for example, Division by zero is indicated by the bit defined as DEC_Division_by_zero). Once set, a bit remains set until cleared by the user, so more than one condition can be recorded.

status is of type uint32_t (unsigned integer). Bits in the field must only be set if they are defined in the decContext header file. In use, bits are set by the decNumber library modules when exceptional conditions occur, but are never reset. The library user should clear the bits when appropriate (for example, after handling the exceptional condition), but should never set them.

traps
The traps field is used to indicate which of the exceptional conditions should cause a trap. That is, if an exceptional condition bit is set in the traps field, then a trap event occurs when the corresponding bit in the status field is set.

In this implementation, a trap is indicated by raising the signal SIGFPE (defined in signal.h), the Floating-Point Exception signal.

Applications may ignore traps, or may use them to recover from failed operations. Alternatively, applications can prevent all traps by clearing the traps field, and inspect the status field directly to determine if errors have occurred.

traps is of type uint32_t. Bits in the field must only be set if they are defined in the decContext header file.

Note that the result of an operation is always a valid number, but after an exceptional condition has been detected its value may be one of the special values (NaN or infinite). These values can then propagate through other operations without further conditions being raised.

clamp
The clamp field adds explicit exponent clamping, as is applied when a result is encoded in one of the compressed formats. When 0, a result exponent is limited to emax (for example, the exponent of a zero result will be clamped to this value). When 1, a result exponent is limited to emax–(digits–1). As well as clamping zeros, this may cause the coefficient of a result to be padded with zeros on the right in order to bring the exponent within range.

For example, if emax is +96 and digits is 7, the result 1.23E+96 would have a [sign, coefficient, exponent] of [0, 123, 94] if clamp were 0, but would give [0, 1230000, 90] if clamp were 1.

clamp is of type uint8_t (an unsigned byte).

extended
The extended field controls the level of arithmetic supported. When 1, special values are possible, some extra checking required for IEEE 854 conformance is enabled, and subnormal numbers can result from operations (that is, results whose adjusted exponent is as low as emin–(digits–1) are possible). When 0, the X3.274 subset is supported; in particular, –0 is not possible, operands are rounded, and the exponent range is balanced.

If extended will always be 1, then the DECSUBSET tuning parameter may be set to 0 in decContext.h. This will remove the extended field from the structure, and also remove all code that refers to it. This gives a 10%–20% speed improvement for many operations.

extended is of type uint8_t (an unsigned byte).

Please see the arithmetic specification for further details on the meaning of specific settings (for example, the rounding mode).


Definitions

The decContext.h header file defines the context used by most functions in the decNumber module; it is therefore automatically included by decNumber.h. In addition to defining the decContext data structure described above, it also includes:

Several of the exceptional condition flags merit special attention:

Unlike the other status flags, which indicate error conditions, execution continues normally when these events occur and the result is a number (unless an error condition also occurs). As usual, any or all of the conditions can be enabled for traps and in this case the operation is completed before the trap takes place.


Functions

The decContext.c source file contains the public functions defined in the header file, as follows.

decContextDefault(context, kind)

This function is used to initialize a decContext structure to default values. It is stongly recommended that this function always be used to initialize a decContext structure, even if most or all of the fields are to be set explicitly (in case new fields are added to a later version of the structure).

The arguments are:

context
(decContext *) Pointer to the structure to be initialized.

kind
(int32_t) The kind of initialization to be performed. Only the values defined in the decContext header file are permitted (any other value will initialize the structure to a valid condition, but with the DEC_Invalid_operation status bit set).

When kind is DEC_INIT_BASE, the defaults for the ANSI X3.274 arithmetic subset are set. That is, the digits field is set to 9, the emax field is set to 999999999, the round field is set to ROUND_HALF_UP, the status field is cleared (all bits zero), the traps field has all the DEC_Errors bits set (DEC_Rounded, DEC_Inexact, DEC_Lost_digits, and DEC_Subnormal are 0), clamp is set to 0, and extended (if present) is set to 0.

When kind is DEC_INIT_DECIMAL32, defaults for a decimal32 number using IEEE 854 rules are set. That is, the digits field is set to 7, the emax field is set to 96, the emin field is set to –95, the round field is set to DEC_ROUND_HALF_EVEN, the status field is cleared (all bits zero), the traps field is cleared (no traps are enabled), clamp is set to 1, and extended (if present) is set to 1.

When kind is DEC_INIT_DECIMAL64, defaults for a decimal64 number using IEEE 854 rules are set. That is, the digits field is set to 16, the emax field is set to 384, the emin field is set to –383, and the other fields are set as for DEC_INIT_DECIMAL32.

When kind is DEC_INIT_DECIMAL128, defaults for a decimal128 number using IEEE 854 rules are set. That is, the digits field is set to 34, the emax field is set to 6144, the emin field is set to –6143, and the other fields are set as for DEC_INIT_DECIMAL32.

Returns context.

decContextSetStatus(context, status)

This function is used to set one or more status bits in the status field of a decContext. If any of the bits being set have the corresponding bit set in the traps field, a trap is raised (regardless of whether the bit is already set in the status field). Only one trap is raised even if more than one bit is being set.

The arguments are:

context
(decContext *) Pointer to the structure whose status is to be set.

status
(uint32_t) Any 1 (set) bit in this argument will cause the corresponding bit to be set in the context status field. Only bits defined in the decContext header file should be set; the effect of setting other bits is undefined.[2] 
Returns context.

Normally, only library modules use this function. Applications may clear status bits but should not set them (except, perhaps, for testing).

Note that a signal handler which handles a trap raised by this function may execute a C long jump, and hence control may not return from the function. It should therefore only be invoked when any state and resources used (such as allocated memory) are clean.

decContextSetStatusFromString(context, string)

This function is used to set a status bit in the status field of a decContext, using the name of the bit as returned by the decContextStatusToString function. If the bit being set has the corresponding bit set in the traps field, a trap is raised (regardless of whether the bit is already set in the status field).

The arguments are:

context
(decContext *) Pointer to the structure whose status is to be set.

string
(char *) A string which must be exactly equal to one that might be returned by decContextStatusToString. If the string is ‘No status’, the status is not changed and no trap is raised. If the string is ‘Multiple status’, or is not recognized, then the call is in error.
Returns context unless the string is in error, in which case NULL is returned.

Normally, only library and test modules use this function. Applications may clear status bits but should not set them (except, perhaps, for testing).

Note that a signal handler which handles a trap raised by this function may execute a C long jump, and hence control may not return from the function. It should therefore only be invoked when any state and resources used (such as allocated memory) are clean.

decContextStatusToString(context)

This function returns a pointer (char *) to a human-readable description of a status bit. The string pointed to will be a constant.

The argument is:

context
(decContext *) Pointer to the structure whose status is to be returned as a string. The bits set in the status field must comprise only bits defined in the header file.

If no bits are set in the status field, a pointer to the string ‘No status’ is returned. If more than one bit is set, a pointer to the string ‘Multiple status’ is returned.

Note that the content of the string pointed to is a programming interface (it is understood by the decContextSetStatusFromString function) and is therefore not language- or locale-dependent.


Footnotes:
[1] See http://www2.hursley.ibm.com/decimal/decarith.html for details.
[2] If ‘private’ bits were allowed, future extension of the library with other conditions would be impossible.

[previous | contents | next]