## decContext module

The decContext module defines the data structure used for providing the context for operations and for managing exceptional conditions. The decNumber module uses all of these fields for full control of arbitrary-precision arithmetic; the decFloats modules (decQuad, etc.) are fixed-size and fixed-format and use only the round and status fields.

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 is usually set to –emax or to –(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.

DEC_ROUND_05UP
The same as DEC_ROUND_UP, except that rounding up only occurs if the digit to be rounded up is 0 or 5 and after Overflow the result is the same as for DEC_ROUND_DOWN.

DEC_ROUND_DEFAULT
The same as DEC_ROUND_HALF_EVEN.

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 and decContextSetStatus is called (which happens automatically at the end of any operation which sets a status bit).

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 controls 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 a maximum of emax and a minimum of emin (for example, the exponent of a zero result will be clamped to be in this range). When 1, a result exponent has the same minimum but is limited to a maximum of 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.

Also when 1, clamp limits the length of NaN payloads to digits–1 (rather than digits) when constructing a NaN by conversion from a string.

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 754 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:
• The enumeration of the rounding modes supported by this implementation (for the round field of the decContext).
• The decClass enumeration (and corresponding strings) which is used to classify numbers with the decNumberClass function or the equivalent functions in decQuad, etc.
• The exceptional condition flags, used in the status and traps fields. The flags used can be modified by the DECEXTFLAG tuning parameter.
• Constants describing the range of precision and adjusted exponent supported by the decNumber package.
• Groupings for the exceptional conditions flags, indicating how they correspond to the named conditions defined in IEEE 754, which are usually considered errors (DEC_Errors), etc.
• A character constant naming each of the exceptional conditions (intended for human-readable error reporting).
• Constants used for selecting initialization schemes.
• Definitions of the public functions in the decContext module.

Several of the exceptional condition flags merit special attention:

• The DEC_Clamped flag is set whenever the exponent of a result is clamped to an extreme value, derived from emax or emin and possibly modified by clamp.
• The DEC_Inexact flag is set whenever a result is inexact (non-zero digits were discarded) due to rounding of input operands or the result.
• The DEC_Lost_digits flag is set when an input operand is made inexact through rounding (which can only occur if extended is 0).
• The DEC_Rounded flag is set whenever a result or input operand is rounded (even if only zero digits were discarded).
• The DEC_Subnormal flag is set whenever a result is a subnormal value.

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.

Note that of the above only the DEC_Inexact flag is set by the decFloats modules. The other informational flags are only set by the decNumber module.

### Functions

The decContext.c source file contains the public functions defined in the header file, as follows. In all these functions, only status bits (etc.) that are defined in the decContext.h header file should be used.[2]

#### decContextClearStatus(context, status)

This function is used to clear (set to zero) one or more status bits in the status field of a decContext.

The arguments are:

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

status
(uint32_t) Any 1 (set) bit in this argument will cause the corresponding bit to be cleared in the context status field.
Returns context.

#### 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 or DEC_INIT_DECSINGLE, defaults for a decimal32 number using IEEE 754 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 or DEC_INIT_DECDOUBLE, defaults for a decimal64 number using IEEE 754 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 or DEC_INIT_DECQUAD, defaults for a decimal128 number using IEEE 754 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.

#### decContextGetRounding(context)

This function is used to return the round (rounding mode) field of a decContext.

The argument is:

context
(decContext *) Pointer to the structure whose rounding mode is to be returned.
Returns the enum rounding rounding mode.

#### decContextGetStatus(context)

This function is used to return the status field of a decContext.

The argument is:

context
(decContext *) Pointer to the structure whose status is to be returned.
Returns the uint32_t status field.

This function is used to restore one or more status bits in the status field of a decContext from a saved status field.

The arguments are:

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

status
(uint32_t) A saved status field (as saved by decContextSaveStatus or retrieved by decContextGetStatus).

(uint32_t) Any 1 (set) bit in this argument will cause the corresponding bit to be restored (set to 0 or 1, taken from the corresponding bit in status) in the context status field.
Returns context.

Note that setting a bit using this function does not cause a trap (use the decContextSetStatus function can be used to raise a trap, if desired).

This function is used to save one or more status bits from the status field of a decContext.

The arguments are:

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

(uint32_t) Any 1 (set) bit in this argument will cause the corresponding bit to be saved from the context status field.
Returns the uint32_t which is the logical And of the context status field and the mask.

#### decContextSetRounding(context, rounding)

This function is used to set the rounding mode in the round field of a decContext.

The arguments are:

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

rounding
(enum rounding) The rounding mode to be copied to the context round field.
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.
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.

#### decContextSetStatusFromStringQuiet(context, string)

This function is identical to decContextSetStatusFromString except that the context traps field is ignored (i.e., no trap is raised).

#### decContextSetStatusQuiet(context, status)

This function is identical to decContextSetStatus except that the context traps field is ignored (i.e., no trap is raised).

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

#### decContextTestEndian(quiet)

This function checks that the DECLITEND tuning parameter is set correctly.

The argument is:

quiet
(uint8 t) If 0, a warning message is displayed (using printf) if DECLITEND is set incorrectly. If 1, no message is displayed.
Returns 0 if the DECLITEND parameter is correct, 1 if it is incorrect and should be set to 1, and –1 if it is incorrect and should be set to 0.

This function is used to test one or more status bits in a saved status field.

The arguments are:

status
(uint32_t) A saved status field (as saved by decContextSaveStatus or retrieved by decContextGetStatus).

(uint32_t) Any 1 (set) bit in this argument will cause the corresponding bit in status to be included in the test.
Returns the uint32_t which is the logical And of status and mask.

This function is used to test one or more status bits in a context.

The arguments are:

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

(uint32_t) Any 1 (set) bit in this argument will cause the corresponding bit in context status field to be included in the test.
Returns the uint32_t which is the logical And of the context status field and mask.

#### decContextZeroStatus(context)

This function is used to clear (set to zero) all the status bits in the status field of a decContext.

The argument is:

context
(decContext *) Pointer to the structure whose status is to be zeroed.
Returns context.
Footnotes:
 [1] See http://speleotrove.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]