The decNumber Library, version 3.68
Copyright (c) IBM Corporation, 2010. All rights reserved. ©
| 23 Jan 2010 |
| [previous | contents | next]
|
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
emin–digits+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).
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.
decContextRestoreStatus(context, status, mask)
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).
- mask
- (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).
decContextSaveStatus(context, mask)
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.
- mask
- (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.
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.
decContextTestSavedStatus(status, mask)
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).
- mask
- (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.
decContextTestStatus(context, 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.
- mask
- (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:
[previous | contents | next]