Documentation

The Ctx monad

The General Decimal Arithmetic specification states that most computations occur within a context, which affects the manner in which computations are done (for instance, the context determines the rounding algorithm). The context also carries the flags that computations can set (for instance, a computation might set a flag to indicate that the result is rounded or inexact or was a division by zero.) The Ctx monad carries this context.

Decimal number. As indicated in the General Decimal Arithmetic specification, a Quad might be a finite number (perhaps the most common type) or it might be infinite or a not-a-number. decClass will tell you a little more about a particular Quad.

Round toward negative infinity.

Round away from zero.

Round away from zero, but only if the discarded digits are greater than or equal to half of the value of a one in the next left position.

Round away from zero if discarded digits are greater than half of the value of a one in the next left position. If discarded digits are less than half, ignore the discarded digits. If they represent exactly half, do not alter result coefficient if its rightmost digit is even, or increment it by one if its rightmost digit is odd (to make an even digit).

If the discarded digits represent greater than half of the value of a one in the next left position then the result coefficient is incremented by one (that is, rounded away from zero). Otherwise the discarded digits are ignored.

Round toward zero; the discarded digits are ignored.

Round toward negative infinity. If all discarded digits are zero or if the sign is zero, the result is unchanged. Otherwise, the sign is 1 and the result coefficient is incremented by 1.

Round zero or five away from zero. The same as roundUp, except that rounding up occurs only if the digit to be rounded up is 0 or 5, and after overflow the result is the same as for roundDown.

A single error or warning condition that may be set in the Ctx.

0/0 is undefined. It sets this flag and returns a quiet NaN.

A non-zero dividend is divided by zero. Unlike 0/0, it has a defined result (a signed Infinity).

Sometimes raised by divideInteger and remainder.

Raised on a variety of invalid operations, such as an attempt to use compareSignal on an operand that is an NaN.

One or more non-zero coefficient digits were discarded during rounding.

A result is both subnormal and inexact.

The exponent of a result is too large to be represented.

A source string (for instance, in fromByteString) contained errors.

A container for multiple Flag indicating which are set and which are not.

Is this Flag set?

A Flags with no Flag set.

Gives a list of strings, one for each flag that is set.

The current status flags, which indicate results from previous computations.

Set the current status to whatever you wish.

The current rounding method

Change the current rounding method

By default, rounding is set to roundHalfEven. No status flags are set initially. Returns the final status flags along with the result of the computation.

Like runCtx but does not return the final flags.

Different categories of Quad.

Signaling NaN

Quiet NaN

Negative infinity

Negative normal number

Negative subnormal number

The negative zero

The positive zero

A positive subnormal number

A positive normal number

Positive infinity

Creates a new Quad. Uninitialized.

Absolute value. NaNs are handled normally (the sign of an NaN is not affected, and an sNaN sets invalidOperation.

Digit-wise logical and. Operands must be:

• zero or positive
• integers
• comprise only zeroes and/or ones

If not, invalidOperation is set.

More information about a particular Quad.

Compares two Quad numerically. The result might be -1, 0, 1, or NaN, where -1 means x is less than y, 0 indicates numerical equality, 1 means y is greater than x. NaN is returned only if x or y is an NaN.

Thus, this function does not return an Ordering because the result might be an NaN.

Same as compare, but a quietNaN is treated like a signaling NaN (sets invalidOperation).

Compares using an IEEE 754 total ordering, which takes into account the exponent. IEEE 754 says that this function might return different results depending upon whether the operands are canonical; Quad are always canonical so you don't need to worry about that here.

Same as compareTotal but compares the absolute value of the two arguments.

copySign x y returns z, which is a copy of x but has the sign of y. This function never raises any signals.

Number of significant digits.

divideInteger x y returns the integer part of the result (rounded toward zero), with an exponent of 0. If the the result would not fit because it has too many digits, divisionImpossible is set.

Fused multiply add; fma x y z calculates x * y + z. The multiply is carried out first and is exact, so the result has only one final rounding.

Reads a ByteString, which can be in scientific, engineering, or "regular" decimal notation. Also reads NaN, Infinity, etc. Will return a signaling NaN and set invalidOperation if the string given is invalid.

In the decNumber C library, this function was called fromString; the name was changed here because it doesn't take a regular Haskell String.

Digit-wise logical inversion. The operand must be:

• zero or positive
• integers
• comprise only zeroes and/or ones

If not, invalidOperation is set.

True if x is neither infinite nor a NaN.

True for infinities.

True if x is finite and has exponent of 0; False otherwise. This can lead to unexpected results; for instance, 3 x 10 ^ 2 is 300, but this function will return False.

True only if x is zero or positive, an integer (finite with exponent of 0), and the coefficient is only zeroes and/or ones.

True for NaNs.

True only if x is less than zero and is not an NaN.

True only if x is finite, non-zero, and not subnormal.

True only if x is greater than zero and is not an NaN.

True only if x is a signaling NaN.

True only if x has a sign of 1. Note that zeroes and NaNs may have sign of 1.

True only if x is subnormal - that is, finite, non-zero, and with a magnitude less than 10 ^ emin.

True only if x is a zero.

logB x Returns the adjusted exponent of x, according to IEEE 754 rules. If x is infinite, returns +Infinity. If x is zero, the result is -Infinity, and divisionByZero is set. If x is less than zero, the absolute value of x is used. If x is one, the result is 0. NaNs are propagated as for arithmetic operations.

max x y returns the larger argument; if either (but not both) x or y is a quiet NaN then the other argument is the result; otherwise, NaNs, are handled as for arithmetic operations.

Like max but the absolute values of the arguments are used.

min x y returns the smaller argument; if either (but not both) x or y is a quiet NaN then the other argument is the result; otherwise, NaNs, are handled as for arithmetic operations.

Like min but the absolute values of the arguments are used.

Negation. Result has the same effect as 0 - x when the exponent of the zero is the same as that of x, if x is finite.

Decrements toward negative infinity.

Increments toward positive infinity.

nextToward x y returns the next Quad in the direction of y.

Digit wise logical inclusive Or. Operands must be:

• zero or positive
• integers
• comprise only zeroes and/or ones

If not, invalidOperation is set.

Same effect as 0 + x where the exponent of the zero is the same as that of x if x is finite). NaNs are handled as for arithmetic operations.

quantize x y returns z which is x set to have the same quantum as y; that is, numerically the same value but rounded or padded if necessary to have the same exponent as y. Useful for rounding monetary quantities.

Reduces coefficient to its shortest possible form without changing the value of the result by removing all possible trailing zeroes.

Remainder from integer division. If the intermediate integer does not fit within a Quad, divisionImpossible is raised.

Like remainder but the nearest integer is used for for the intermediate result instead of the result from divideInteger.

rotate x y rotates the digits of x to the left (if y is positive) or right (if y is negative) without adjusting the exponent or sign of x. y is the number of positions to rotate and must be in the range negate coefficientLen to coefficentLen.

NaNs are propagated as usual. No status is set unless y is invalid or an operand is an NaN.

True only if both operands have the same exponent or are both NaNs (quiet or signaling) or both infinite.

scaleB x y calculates x * 10 ^ y. y must be an integer (finite with exponent of 0) in the range of plus or minus 2 * coefficientLen + coefficientLen), typically resulting from logB. Underflow and overflow might occur; NaNs propagate as usual.

shift x y shifts digits to the left (if y is positive) or right (if y is negative) without adjusting the exponent or sign of y. Any digits shiften in from the left or right will be 0.

y is a count of positions to shift; it must be a finite integer in the range negate coefficientLen to coefficientLen. NaNs propagate as usual. If x is infinite the result is an infinity of the same sign. No status is set unless y is invalid or the operand is an NaN.

Converts a Quad to a string. May use non-scientific notation, but only if that's unambiguous; otherwise, uses scientific notation.

In the decNumber C library, this is called toString; the name was changed here because this function doesn't return a Haskell String.

Returns a string in engineering notation.

In the decNumber C library, this is called toEngString; the name is changed here because the function does not return a regular Haskell String.

Uses the rounding method given rather than the one in the Ctx. If the operand is infinite, an NaN, or if the result of rounding is outside the range of a C'int32_t, then invalidOperation is set. inexact is not set even if rounding occurred.

Like toInt32 but if rounding removes non-zero digits then inexact is set.

Rounds to an integral using the rounding mode set in the Ctx. If the operand is infinite, an infinity of the same sign is returned. If the operand is an NaN, the result is the same as for other arithmetic operations. If rounding removes non-zero digits then inexact is set.

toIntegralValue r x returns an integral value of x using the rounding mode r rather than the one specified in the Ctx. If the operand is an NaN, the result is the same as for other arithmetic operations. inexact is not set even if rounding occurred.

toUInt32 r x returns the value of x, rounded to an integer if necessary using the rounding mode r rather than the one given in the Ctx. If x is infinite, or outside of the range of a C'uint32_t, then invalidOperation is set. inexact is not set even if rounding occurs.

The negative zero converts to 0 and is valid, but negative numbers are not valid.

Same as toUInt32 but if rounding removes non-zero digits then inexact is set.

Identifies the version of the decNumber C library.

Digit-wise logical exclusive or. Operands must be:

• zero or positive
• integers
• comprise only zeroes and/or ones

If not, invalidOperation is set.

A Quad whose coefficient, exponent, and sign are all 0.

The minimum and maximum possible exponent.

The smallest possible adjusted exponent that is still normal. Adjusted exponents smaller than this are subnormal.

Like minNormalAdj, but returns the size of the regular exponent rather than the adjusted exponent.

The signed integer which indicates the power of ten by which the coefficient is multiplied.

Ensures that the exponent is within the range allowed by minMaxExp.

An Exponent whose value is 0.

A pure Haskell type which holds information identical to that in a Quad.

Decodes a Quad to a pure Haskell type which holds identical information.

Encodes a new Quad.

Converts a Decoded to scientific notation. Unlike toByteString this will always use scientific notation. For NaNs and infinities, the notation is identical to that of decNumber (see Decimal Arithmetic Specification page 19). This means that a quiet NaN is NaN while a signaling NaN is sNaN, and infinity is Infinity.

Like decQuadToString, the payload of an NaN is not shown if it is zero.

Converts Decoded to ordinary decimal notation. For NaNs and infinities, the notation is identical to that of scientific. Unlike scientific, though the result can always be converted back to a Quad using fromByteString, the number of significant digits might change. For example, though 1.2E3 has two significant digits, using ordinary on this value and then reading it back in with fromByteString will give you 1200E0, which has four significant digits.

A single decimal digit.

A list of digits, less than or equal to coefficientLen long. Corresponds only to finite numbers.

Creates a Coefficient. Checks to ensure it is not null and that it is not longer than coefficientLen and that it does not have leading zeroes (if it is 0, a single D0 is allowed).

A list of digits, less than or equal to payloadLen long. Accompanies an NaN, potentially with diagnostic information (I do not know if decNumber actually makes use of this.)

Creates a Payload. Checks to ensure it is not null, not longer than payloadLen and that it does not have leading zeroes (if it is 0, a single D0 is allowed).

The most significant digit is at the head of the list.

The most significant digit is at the head of the list. Sign of number is not relevant.

Maximum number of digits in a coefficient.

Maximum number of digits in a payload.

True only if x is zero or positive, an integer (finite with exponent of 0), and the coefficient is only zeroes and/or ones. The sign must be Sign0 (that is, you cannot have a negative zero.)

True only if x is less than zero and is not an NaN. It's not enough for the sign to be Sign1; the coefficient (if finite) must be greater than zero.

True for any zero (negative or positive zero).

The number of significant digits. Zero returns 1.

An adjusted exponent is the value of an exponent of a number when that number is expressed as though in scientific notation with one digit before any decimal point. This is the finite exponent + (number of significant digits - 1).