Context

Most operations are affected by context. Usually, a pointer to the context is passed as the last parameter to signaling functions or the last but one parameter to quiet functions.

Data Type

The context is defined as a C struct:

#include <mpdecimal.h>


typedef struct mpd_context_t {
        mpd_ssize_t prec;   // precision
        mpd_ssize_t emax;   // max positive exp
        mpd_ssize_t emin;   // min negative exp
        uint32_t traps;     // status events that should be trapped
        uint32_t status;    // status flags
        uint32_t newtrap;   // set by mpd_addstatus_raise()
        int      round;     // rounding mode
        int      clamp;     // clamp mode
        int      allcr;     // all functions correctly rounded
} mpd_context_t;

Constants

32-bit 64-bit

MPD_MAX_PREC 425000000 999999999999999999

MPD_MAX_EMAX 425000000 999999999999999999

MPD_MIN_EMIN -425000000 -999999999999999999

Precision and Exponents

prec [1, MPD_MAX_PREC]

emax [0, MPD_MAX_EMAX]

emin [MPD_MIN_EMIN, 0]

Apart from the limits, the following rules must be observed when setting the context manually:

prec <= emax

emin = 1 - emax or emin = -emax

The specification requires 5 x prec <= emax and recommends 10 x prec <= emax.

Rounding

The round field can take one of these values:

MPD_ROUND_UP round away from 0

MPD_ROUND_DOWN round toward 0 (truncate)

MPD_ROUND_CEILING round toward +infinity

MPD_ROUND_FLOOR round toward -infinity

MPD_ROUND_HALF_UP 0.5 is rounded up

MPD_ROUND_HALF_DOWN 0.5 is rounded down

MPD_ROUND_HALF_EVEN 0.5 is rounded to even

MPD_ROUND_05UP round zero or five away from 0

MPD_ROUND_TRUNC truncate, but set infinities

Signals and Conditions

The standard distinguishes between signals and conditions. In particular, the MPD_IEEE_Invalid_operation signal comprises several conditions.

In a signaling function, the status field of the context is updated with all conditions that occurred during the execution. It is never reset automatically, so at any point in a program it contains the cumulative status of all signaling functions.

The traps field determines which signals invoke the mpd_traphandler custom function. By default, this function raises SIGFPE.

If a trap occurs, the newtrap field is set to the value of the respective condition. This makes it possible to determine the latest error condition that occurred even when the status has already been “polluted” with previous error conditions.

Here are the possible signals and conditions:

Signals Conditions

MPD_IEEE_Invalid_operation MPD_Conversion_syntax

MPD_Division_impossible

MPD_Division_undefined

MPD_Invalid_context

MPD_Invalid_operation

MPD_Malloc_error

MPD_Clamped MPD_Clamped

MPD_Division_by_zero MPD_Division_by_zero

MPD_Fpu_error [1] MPD_Fpu_error

MPD_Inexact MPD_Inexact

MPD_Not_implemented [2] MPD_Not_implemented

MPD_Overflow MPD_Overflow

MPD_Rounded MPD_Rounded

MPD_Subnormal MPD_Subnormal

MPD_Underflow MPD_Underflow

[1] deprecated, might be renamed to a user-definable signal.

[2] unused, might be renamed to a user-definable signal.

Exponent Clamping

If the clamp field is set to 1, the maximum exponent is reduced to emax - prec + 1. This is compatible with the IEEE 754 decimal interchange formats.

Correct Rounding

Most functions are correctly-rounded by default. If allcr is set to 1, correct rounding is additionally enabled for mpd_exp, mpd_ln and mpd_log10.

In this case, all functions except mpd_pow and mpd_invroot return correctly rounded results.

Context Functions

Initialization

void mpd_init(mpd_context_t *ctx, mpd_ssize_t prec);

ctx is initialized by mpd_defaultcontext, using prec. At the same time, MPD_MINALLOC is initialized to the ideal value for the given precision. Note that memory usage increases by setting MPD_MINALLOC to higher values.

This function can only be used at program start.

void mpd_maxcontext(mpd_context_t *ctx);
void mpd_defaultcontext(mpd_context_t *ctx);
void mpd_basiccontext(mpd_context_t *ctx);

Initialize the given context. The values for each function:

	maxcontext	defaultcontext [3]	basiccontext [4]
prec	`MPD_MAX_PREC`	`2*MPD_RDIGITS`	`9`
emax	`MPD_MAX_EMAX`	`MPD_MAX_EMAX`	`MPD_MAX_EMAX`
emin	`MPD_MIN_EMIN`	`MPD_MIN_EMIN`	`MPD_MIN_EMIN`
round	`MPD_ROUND_HALF_EVEN`	`MPD_ROUND_HALF_UP`	`MPD_ROUND_HALF_UP`
traps	`MPD_Traps`	`MPD_Traps`	`MPD_Traps\|MPD_Clamped`
status	`0`	`0`	`0`
newtrap	`0`	`0`	`0`
clamp	`0`	`0`	`0`
allcr	`1`	`1`	`1`

[3]	libmpdec’s default context

[4]	the specification’s basic default context

IEEE Interchange Formats

MPD_IEEE_CONTEXT_MAX_BITS
MPD_DECIMAL32
MPD_DECIMAL64
MPD_DECIMAL128

int mpd_ieee_context(mpd_context_t *ctx, int bits);

Initialize the context to the proper values for one of the IEEE interchange formats. The argument must be a multiple of 32 and less than IEEE_CONTEXT_MAX_BITS.

For the most common values, the following constants are provided:

	`MPD_DECIMAL32`	`MPD_DECIMAL64`	`MPD_DECIMAL128`
prec	`7`	`16`	`34`
emax	`96`	`384`	`6144`
emin	`-95`	`-383`	`-6143`
round	`MPD_ROUND_HALF_EVEN`	`MPD_ROUND_HALF_EVEN`	`MPD_ROUND_HALF_EVEN`
traps	`0`	`0`	`0`
status	`0`	`0`	`0`
newtrap	`0`	`0`	`0`
clamp	`1`	`1`	`1`
allcr	`1`	`1`	`1`

Getters and Setters

size_t mpd_getprec(const mpd_context_t *ctx);
mpd_ssize_t mpd_getemax(const mpd_context_t *ctx);
mpd_ssize_t mpd_getemin(const mpd_context_t *ctx);
int mpd_getround(const mpd_context_t *ctx);
uint32_t mpd_gettraps(const mpd_context_t *ctx);
uint32_t mpd_getstatus(const mpd_context_t *ctx);
int mpd_getclamp(const mpd_context_t *ctx);
int mpd_getcr(const mpd_context_t *ctx);

Get the individual values.

mpd_ssize_t mpd_etiny(const mpd_context_t *ctx);

Return the lowest possible exponent of a subnormal number: emin - prec + 1

mpd_ssize_t mpd_etop(const mpd_context_t *ctx);

Return the highest possible exponent of a normal number: emax - prec + 1

Only relevant if clamp is set to 1.

int mpd_qsetprec(mpd_context_t *ctx, mpd_ssize_t prec);
int mpd_qsetemax(mpd_context_t *ctx, mpd_ssize_t emax);
int mpd_qsetemin(mpd_context_t *ctx, mpd_ssize_t emin);
int mpd_qsetround(mpd_context_t *ctx, int newround);
int mpd_qsettraps(mpd_context_t *ctx, uint32_t flags);
int mpd_qsetstatus(mpd_context_t *ctx, uint32_t flags);
int mpd_qsetclamp(mpd_context_t *ctx, int c);
int mpd_qsetcr(mpd_context_t *ctx, int c);

Quietly set the individual values. These functions check the limits, but they are not foolproof: For example, they still allow setting a prec that does not agree with emax. The functions return 1 on success and 0 on failure. They are quiet since raising an MPD_Invalid_context condition would not make sense in most cases.

Calling the Trap Handler

extern void (* mpd_traphandler)(mpd_context_t *);
void mpd_dflt_traphandler(mpd_context_t *);

void mpd_addstatus_raise(mpd_context_t *ctx, uint32_t flags);

Add flags to the status field of ctx. If a condition is trapped, set newtrap to the condition and call mpd_traphandler. By default, mpd_traphandler is points to mpd_dflt_traphandler, which raises SIGFPE.

Table of Contents

Previous topic

Next topic