Data.Deka.IO

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/

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

Every function in this module returns canonical Quad (contrast the decNumber library which will, under limited circumstances, return non-canonical decimals). I am not certain that canonical vs. non-canonical matters in typical use, though it may matter when using compareTotal.

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

 import qualified Data.Deka.Pure as D

Quad

data Quad

Decimal number. This is immutable, like any Haskell value you would ordinarily work with. (Actually, that is a bit of a lie. Under the covers it is a pointer to a C struct, which is in fact mutable like anything in C. However, no function exposed in this API mutates a Quad's pointee after the Quad is created.)

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.

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

roundUp :: Round

roundHalfUp :: Round

roundHalfEven :: Round

roundHalfDown :: Round

roundDown :: Round

roundFloor :: Round

round05Up :: Round

roundMax :: Round

Flags

For more on possible flags, see

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

data Flag

Instances

Eq Flag

Ord Flag

Show Flag

divisionUndefined :: Flag

divisionByZero :: Flag

divisionImpossible :: Flag

invalidOperation :: Flag

inexact :: Flag

invalidContext :: Flag

underflow :: Flag

overflow :: Flag

conversionSyntax :: Flag

data Flags

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

Instances

Eq Flags

Ord Flags

Show Flags

setFlag :: Flag -> Flags -> Flags

clearFlag :: Flag -> Flags -> Flags

checkFlag :: Flag -> Flags -> Bool

Is this Flag set?

emptyFlags :: Flags

A Flags with no Flag set.

flagList :: Flags -> [String]

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

Env monad

data Env a

The Env monad

Since Deka is a binding to a C library, all the work happens in the mutable land of C pointers. That means that everything happens in the IO monad. The Env monad is simply a wrapper of the IO monad. Since the Env data constructor is not exported, you can't do arbitrary IO computations in the monad; you can only do the computations from this module. Because all the computations in this module do not create observable side effects, it is safe to use unsafePerformIO to perform Env computations in a pure function. This module does not have such a function so that this module can stay Safe for Safe Haskell purposes; however, the Data.Deka.Pure module does have such a function.

Instances

Monad Env

Functor Env

Applicative Env

runEnvIO :: Env a -> IO a

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 some results from computations (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.

Conceptually the Ctx monad includes the Env monad. Any Env computation can be lifted into a Ctx computation with a liftEnv. You will do most computations in the Ctx monad; however, on occasion it is useful to do computations entirely in the Env monad. You know that computations entirely in the Env monad are unaffected by, and cannot affect, the context.

The Ctx monad captures both the context and the IO. Because Quad is exposed only as an immutable type, and because there is no way to do arbitrary IO in the Ctx monad (which is why it is not an instance of the MonadIO class), it is safe to put an unsafePerformIO on Ctx computations so they can be done in pure functions.

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.

getRound :: Ctx Round

The current rounding method

setRound :: Round -> Ctx ()

Change the current rounding method

runCtxIO :: Ctx a -> IO (a, Flags)

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

liftEnv :: Env a -> Ctx a

Lifts an Env computation into a Ctx.

Class

data DecClass

Different categories of Quad.

Instances

Eq DecClass

Ord DecClass

Show DecClass

sNan :: DecClass

qNan :: DecClass

negInf :: DecClass

negNormal :: DecClass

negSubnormal :: DecClass

negZero :: DecClass

posZero :: DecClass

posSubnormal :: DecClass

posNormal :: DecClass

posInf :: DecClass

decClass :: Quad -> Env DecClass

More information about a particular Quad.

Conversions

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

digitsToIntegral :: [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.

Complete encoding and decoding

Coefficients

coefficientLen :: Int

payloadDigitsLen :: Int

data Coefficient

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

Instances

Eq Coefficient

Ord Coefficient

Show Coefficient

coefficient :: [Digit] -> Maybe Coefficient

unCoefficient :: Coefficient -> [Digit]

data Payload

A list of digits, less than or equal to payloadDigitsLen long.

Instances

Eq Payload

Ord Payload

Show Payload

payloadDigits :: [Digit] -> Maybe Payload

unPayload :: Payload -> [Digit]

Exponents

data Exponent

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

Instances

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

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

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

Constructors

Decoded

Fields

dSign :: Sign

dValue :: Value

Instances

Eq Decoded

Ord Decoded

Show Decoded

fromBCD :: Decoded -> Env Quad

Encodes a new Quad. The result is always canonical. However, the function does not signal if the result is an sNaN.

toBCD :: Quad -> Env Decoded

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 the Invalid flag 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 -> Env 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 -> Env 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.

Integers

fromInt32 :: C'int32_t -> Env Quad

fromUInt32 :: C'uint32_t -> Env Quad

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

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

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

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

Other Quad

toIntegralExact :: Quad -> Ctx Quad

toIntegralValue :: Round -> Quad -> Ctx Quad

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.

divide :: Quad -> Quad -> Ctx Quad

divideInteger :: Quad -> Quad -> Ctx Quad

remainder :: Quad -> Quad -> Ctx Quad

remainderNear :: Quad -> Quad -> Ctx Quad

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

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.

compareSignal :: Quad -> Quad -> Ctx Quad

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

compareTotal :: Quad -> Quad -> Env Quad

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 -> Env Quad

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

max :: Quad -> Quad -> Ctx Quad

maxMag :: Quad -> Quad -> Ctx Quad

min :: Quad -> Quad -> Ctx Quad

minMag :: Quad -> Quad -> Ctx Quad

sameQuantum :: Quad -> Quad -> Env Bool

Tests

isFinite :: Quad -> Env Bool

isInfinite :: Quad -> Env Bool

isInteger :: Quad -> Env Bool

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.

isLogical :: Quad -> Env 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 -> Env Bool

isNegative :: Quad -> Env Bool

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

isNormal :: Quad -> Env Bool

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

isPositive :: Quad -> Env Bool

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

isSignaling :: Quad -> Env Bool

True only if x is a signaling NaN.

isSigned :: Quad -> Env Bool

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

isSubnormal :: Quad -> Env Bool

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

isZero :: Quad -> Env 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

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 -> Env Quad

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

Increment and decrement

nextMinus :: Quad -> Ctx Quad

nextPlus :: Quad -> Ctx Quad

nextToward :: Quad -> Quad -> Ctx Quad

Logical, bitwise, digit shifting

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.

shift :: Quad -> Quad -> Ctx Quad

xor :: Quad -> Quad -> Ctx Quad

rotate :: Quad -> Quad -> Ctx Quad

invert :: Quad -> Ctx Quad

Transcendental

logB :: Quad -> Ctx Quad

scaleB :: Quad -> Quad -> Ctx Quad

Attributes

digits :: Quad -> Env Int

Constants

zero :: Env Quad

Library info

version :: Env ByteString

Decoded predicates

These duplicate the tests that are available in the Env monad.

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.