Data.Deka.Quad

Floating-point decimals.

This uses the decNumber C library, so you will want to read the documentation about it to fully understand this module:

http://speleotrove.com/decimal/decnumber.html

http://speleotrove.com/decimal/decarith.html

http://speleotrove.com/decimal/

Many of the comments on what these functions do are taken directly from the documentation for the decNumber C library.

In particular, this module implements the decQuad type. decQuad supports up to 34 digits of precision and exponents between -6176 and 6111. It doesn't silently round, overflow, or underflow; rather, the library will notify you if these things happen.

Many functions in this module clash with Prelude names, so you might want to do

 import qualified Data.Deka.Quad as Q

Quad

data Quad

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.

Instances

Eq Quad

The Eq instance depends on an IEEE 754 total ordering. In particular, note that, for example, 7.5 is not equal to 7.50. See

http://speleotrove.com/decimal/decifaq4.html#order

Ord Quad

Like the Eq instance, this uses an IEEE 754 total ordering.

Show Quad

The Show instance uses toByteString.

Rounding

For more on the rounding algorithms, see

http://speleotrove.com/decimal/damodel.html

data Round

Instances

Eq Round

Ord Round

Show Round

roundCeiling :: Round

Round toward positive infinity.

roundUp :: Round

Round away from zero.

roundHalfUp :: Round

0.5 rounds up

roundHalfEven :: Round

0.5 rounds to nearest even

roundHalfDown :: Round

0.5 rounds down

roundDown :: Round

Round toward zero - truncate

roundFloor :: Round

Round toward negative infinity.

round05Up :: Round

Round for reround

Flags

For more on possible flags, see

http://speleotrove.com/decimal/damodel.html

data Flag

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

Instances

Eq Flag

Ord Flag

Show Flag

divisionUndefined :: Flag

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

divisionByZero :: Flag

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

divisionImpossible :: Flag

Sometimes raised by divideInteger and remainder.

invalidOperation :: Flag

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

inexact :: Flag

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

underflow :: Flag

A result is both subnormal and inexact.

overflow :: Flag

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

conversionSyntax :: Flag

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

data Flags

A container for multiple Flag indicating which are set and which are not. An instance of Exception so you can throw it if you want (no functions in this module throw.)

Instances

Eq Flags

Ord Flags

Show Flags

Show gives you a comma-separated list of flags that are set, or an empty string if no flags are set.

Typeable Flags

Exception Flags

unFlags :: Flags -> [Flag]

setFlag :: Flag -> Flags -> Flags

clearFlag :: Flag -> Flags -> Flags

checkFlag :: Flag -> Flags -> Bool

Is this Flag set?

emptyFlags :: Flags

A Flags with no Flag set.

Ctx monad

data Ctx a

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.

Instances

Monad Ctx

Functor Ctx

Applicative Ctx

getStatus :: Ctx Flags

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

setStatus :: Flags -> Ctx ()

Set the current status to whatever you wish.

mapStatus :: (Flags -> Flags) -> Ctx ()

getRound :: Ctx Round

The current rounding method

setRound :: Round -> Ctx ()

Change the current rounding method

runCtx :: Ctx a -> (a, Flags)

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.

evalCtx :: Ctx a -> a

Like runCtx but does not return the final flags.

Class

data DecClass

Different categories of Quad.

Instances

Eq DecClass

Ord DecClass

Show DecClass

sNan :: DecClass

Signaling NaN

qNan :: DecClass

Quiet NaN

negInf :: DecClass

Negative infinity

negNormal :: DecClass

Negative normal number

negSubnormal :: DecClass

Negative subnormal number

negZero :: DecClass

The negative zero

posZero :: DecClass

The positive zero

posSubnormal :: DecClass

A positive subnormal number

posNormal :: DecClass

A positive normal number

posInf :: DecClass

Positive infinity

decClass :: Quad -> DecClass

More information about a particular Quad.

Converting to and from strings

fromByteString :: ByteString -> Ctx Quad

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.

toByteString :: Quad -> ByteString

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.

toEngByteString :: Quad -> ByteString

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.

Converting to and from integers

type C'int32_t = Int32

type C'uint32_t = Word32

fromInt32 :: C'int32_t -> Quad

fromUInt32 :: C'uint32_t -> Quad

toInt32 :: Round -> Quad -> Ctx C'int32_t

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.

toInt32Exact :: Round -> Quad -> Ctx C'int32_t

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

toUInt32 :: Round -> Quad -> Ctx C'uint32_t

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.

toUInt32Exact :: Round -> Quad -> Ctx C'uint32_t

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

Arithmetic

add :: Quad -> Quad -> Ctx Quad

subtract :: Quad -> Quad -> Ctx Quad

multiply :: Quad -> Quad -> Ctx Quad

fma :: Quad -> Quad -> Quad -> Ctx Quad

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.

divide :: Quad -> Quad -> Ctx Quad

divideInteger :: Quad -> Quad -> Ctx Quad

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.

remainder :: Quad -> Quad -> Ctx Quad

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

remainderNear :: Quad -> Quad -> Ctx Quad

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

Exponent and coefficient adjustment

quantize :: Quad -> Quad -> Ctx Quad

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.

reduce :: Quad -> Ctx Quad

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

Comparisons

compare :: Quad -> Quad -> Ctx 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.

compareOrd :: Quad -> Quad -> Maybe Ordering

Wrapper for compare that returns an Ordering rather than a Quad. Returns Just LT rather than -1, Just EQ rather than 0, and Just GT rather than 1, and Nothing rather than NaN. This is a pure function; it does not affect the Ctx.

compareSignal :: Quad -> Quad -> Ctx Quad

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

compareTotal :: Quad -> Quad -> Ordering

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.

compareTotalMag :: Quad -> Quad -> Ordering

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

max :: Quad -> Quad -> Ctx Quad

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.

maxMag :: Quad -> Quad -> Ctx Quad

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

min :: Quad -> Quad -> Ctx Quad

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.

minMag :: Quad -> Quad -> Ctx Quad

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

sameQuantum :: Quad -> Quad -> Bool

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

Tests

isFinite :: Quad -> Bool

True if x is neither infinite nor a NaN.

isInfinite :: Quad -> Bool

True for infinities.

isInteger :: Quad -> Bool

True if x is finite and has exponent of 0; False otherwise. This tests the exponent, not the adjusted exponent. This can lead to results you may not expect:

>>> isInteger . evalCtx . fromByteString . pack $ "3.00e2"
True

>>> isInteger . evalCtx . fromByteString . pack $ "3e2"
False

>>> isInteger . evalCtx . fromByteString . pack $ "3.00e0"
False

isLogical :: Quad -> Bool

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

isNaN :: Quad -> Bool

True for NaNs.

isNegative :: Quad -> Bool

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

isNormal :: Quad -> Bool

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

isPositive :: Quad -> Bool

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

isSignaling :: Quad -> Bool

True only if x is a signaling NaN.

isSigned :: Quad -> Bool

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

isSubnormal :: Quad -> Bool

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

isZero :: Quad -> Bool

True only if x is a zero.

Signs

plus :: Quad -> Ctx Quad

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.

minus :: Quad -> Ctx Quad

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.

abs :: Quad -> Ctx Quad

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

copySign :: Quad -> Quad -> Quad

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

Increment and decrement

nextMinus :: Quad -> Ctx Quad

Decrements toward negative infinity.

nextPlus :: Quad -> Ctx Quad

Increments toward positive infinity.

nextToward :: Quad -> Quad -> Ctx Quad

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

Digit-wise

and :: Quad -> Quad -> Ctx Quad

Digit-wise logical and. Operands must be:

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

If not, invalidOperation is set.

or :: Quad -> Quad -> Ctx Quad

Digit wise logical inclusive Or. Operands must be:

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

If not, invalidOperation is set.

xor :: Quad -> Quad -> Ctx Quad

Digit-wise logical exclusive or. Operands must be:

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

If not, invalidOperation is set.

invert :: Quad -> Ctx Quad

Digit-wise logical inversion. The operand must be:

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

If not, invalidOperation is set.

shift :: Quad -> Quad -> Ctx Quad

shift x y shifts digits 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. Any digits shifted 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.

rotate :: Quad -> Quad -> Ctx Quad

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.

log and scale

logB :: Quad -> Ctx Quad

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.

scaleB :: Quad -> Quad -> Ctx Quad

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.

Attributes

digits :: Quad -> Int

Number of significant digits. If zero or infinite, returns 1. If NaN, returns number of digits in the payload.

Integral rounding

If you want to round but not to an integral value (e.g. round to two decimal places), see quantize.

toIntegralExact :: Quad -> Ctx Quad

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 :: Round -> Quad -> Ctx Quad

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.

Constants

zero :: Quad

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

one :: Quad

A Quad with coefficient D1, exponent 0, and sign Sign0.

version :: ByteString

Identifies the version of the decNumber C library.

Complete encoding and decoding

These convert a Quad to a Decoded, which is a pure Haskell type containing all the information in the Quad.

Digits

data Digit

A single decimal digit.

Constructors

D0

D1

D2

D3

D4

D5

D6

D7

D8

D9

Instances

Bounded Digit

Enum Digit

Eq Digit

Ord Digit

Show Digit

digitToInt :: Integral a => Digit -> a

intToDigit :: Integral a => a -> Digit

digitToChar :: Digit -> Char

digitsToInteger :: [Digit] -> Integer

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

integralToDigits :: Integral a => a -> [Digit]

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

Coefficients

coefficientLen :: Int

Maximum number of digits in a coefficient.

payloadLen :: Int

Maximum number of digits in a payload.

data Coefficient

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

Instances

Bounded Coefficient

Enum Coefficient

Eq Coefficient

Ord Coefficient

Show Coefficient

coefficient :: [Digit] -> Maybe Coefficient

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

unCoefficient :: Coefficient -> [Digit]

zeroCoefficient :: Coefficient

Coefficient of D0

oneCoefficient :: Coefficient

Coefficient of D1

data Payload

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

Instances

Bounded Payload

Enum Payload

Eq Payload

Ord Payload

Show Payload

payload :: [Digit] -> Maybe Payload

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

unPayload :: Payload -> [Digit]

zeroPayload :: Payload

Payload of [D0]

Exponents

data Exponent

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

Instances

Bounded Exponent

Enum Exponent

Eq Exponent

Ord Exponent

Show Exponent

exponent :: Int -> Maybe Exponent

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

unExponent :: Exponent -> Int

zeroExponent :: Exponent

An Exponent whose value is 0.

minMaxExp :: (Int, Int)

The minimum and maximum possible exponent.

data AdjustedExp

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

Instances

Bounded AdjustedExp

Enum AdjustedExp

Eq AdjustedExp

Ord AdjustedExp

Show AdjustedExp

adjustedExp :: Coefficient -> Exponent -> AdjustedExp

unAdjustedExp :: AdjustedExp -> Int

minNormalAdj :: AdjustedExp

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

minNormalExp :: Coefficient -> Exponent

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

adjustedToExponent :: Coefficient -> AdjustedExp -> Exponent

Sign, NaN, Value, Decoded

data Sign

Constructors

Sign0

The number is positive or is zero

Sign1

The number is negative or the negative zero

Instances

Bounded Sign

Enum Sign

Eq Sign

Ord Sign

Show Sign

data NaN

Constructors

Quiet

Signaling

Instances

Bounded NaN

Enum NaN

Eq NaN

Ord NaN

Show NaN

data Value

Constructors

Finite Coefficient Exponent

Infinite

NaN NaN Payload

Instances

Eq Value

Ord Value

Show Value

data Decoded

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

Constructors

Decoded

Fields

dSign :: Sign

dValue :: Value

Instances

Eq Decoded

Ord Decoded

Show Decoded

fromBCD :: Decoded -> Quad

Encodes a new Quad.

toBCD :: Quad -> Decoded

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

scientific :: Decoded -> String

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.

ordinary :: Decoded -> String

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.

decodedToRational :: Decoded -> Maybe Rational

Converts a Decoded to a Rational. Returns Nothing if the Decoded is not finite.

Decoded predicates

Duplicates of Quad tests that return Bool

These duplicate the tests that are available for the Quad type directly.

dIsFinite :: Decoded -> Bool

dIsInfinite :: Decoded -> Bool

dIsInteger :: Decoded -> Bool

dIsLogical :: Decoded -> Bool

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

dIsNaN :: Decoded -> Bool

dIsNegative :: Decoded -> Bool

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.

dIsNormal :: Decoded -> Bool

dIsPositive :: Decoded -> Bool

dIsSignaling :: Decoded -> Bool

dIsSigned :: Decoded -> Bool

dIsSubnormal :: Decoded -> Bool

dIsZero :: Decoded -> Bool

True for any zero (negative or positive zero).

dDigits :: Coefficient -> Int

The number of significant digits. Zero returns 1.

Duplicates of Quad tests that return DecClass

dIsSNaN :: Decoded -> Bool

dIsQNaN :: Decoded -> Bool

dIsNegInf :: Decoded -> Bool

dIsNegNormal :: Decoded -> Bool

dIsNegSubnormal :: Decoded -> Bool

dIsNegZero :: Decoded -> Bool

dIsPosZero :: Decoded -> Bool

dIsPosSubnormal :: Decoded -> Bool

dIsPosNormal :: Decoded -> Bool

dIsPosInf :: Decoded -> Bool