Safe Haskell | Trustworthy |
---|---|
Language | Haskell2010 |
It is not usually necessary to import this module unless you want to use the arithmetic operations from Numeric.Decimal.Operation or you need precise control over the handling of exceptional conditions in an arithmetic computation.
Synopsis
- data Context p r
- newContext :: Context p r
- flags :: Context p r -> Signals
- getPrecision :: Precision p => Arith p r (Maybe Int)
- getRounding :: Rounding r => Arith p r RoundingAlgorithm
- data RoundingAlgorithm
- basicDefaultContext :: Context P9 RoundHalfUp
- extendedDefaultContext :: Context p RoundHalfEven
- data Arith p r a
- runArith :: Arith p r a -> Context p r -> (Either (Exception p r) a, Context p r)
- evalArith :: Arith p r a -> Context p r -> Either (Exception p r) a
- subArith :: Arith a b (Decimal a b) -> Arith p r (Decimal a b)
- data Exception p r
- exceptionSignal :: Exception p r -> Signal
- exceptionResult :: Exception p r -> Decimal p r
- data Signal
- data Signals
- signal :: Signal -> Signals
- signals :: [Signal] -> Signals
- allSignals :: Signals
- signalMember :: Signal -> Signals -> Bool
- raiseSignal :: Signal -> Decimal p r -> Arith p r (Decimal p r)
- clearFlags :: Signals -> Arith p r ()
- type TrapHandler p r = Exception p r -> Arith p r (Decimal p r)
- trap :: Signals -> TrapHandler p r -> Arith p r a -> Arith p r a
Decimal arithmetic
Decimal arithmetic is performed within a context that maintains state to
handle exceptional conditions such as underflow, rounding, or division by
zero (cf. Signal
). The Arith
monad provides a means to evaluate an
arithmetic computation and manipulate its Context
.
Context
A context for decimal arithmetic, carrying signal flags, trap enabler
state, and a trap handler, parameterized by precision p
and rounding mode
r
newContext :: Context p r Source #
Return a new context with all signal flags cleared and all traps disabled.
getPrecision :: Precision p => Arith p r (Maybe Int) Source #
Return the precision of the arithmetic context (or Nothing
if the
precision is infinite).
getRounding :: Rounding r => Arith p r RoundingAlgorithm Source #
Return the rounding mode of the arithmetic context.
data RoundingAlgorithm Source #
A value representation of a rounding algorithm (cf. Rounding
).
Instances
Eq RoundingAlgorithm Source # | |
Defined in Numeric.Decimal.Rounding (==) :: RoundingAlgorithm -> RoundingAlgorithm -> Bool # (/=) :: RoundingAlgorithm -> RoundingAlgorithm -> Bool # |
Default contexts
The General Decimal Arithmetic specification defines optional default contexts, which define suitable settings for basic arithmetic and for the extended arithmetic defined by IEEE 854 and IEEE 754.
basicDefaultContext :: Context P9 RoundHalfUp Source #
Return a new context with all signal flags cleared, all traps enabled
except for Inexact
, Rounded
, and Subnormal
, using a precision of 9
significant decimal digits, and rounding half up. Trapped signals simply
call throwError
with the corresponding Exception
, and can be caught
using catchError
.
extendedDefaultContext :: Context p RoundHalfEven Source #
Return a new context with all signal flags cleared, all traps disabled (IEEE 854 §7), using selectable precision, and rounding half even (IEEE 754 §4.3.3).
The Arith monad
A decimal arithmetic monad parameterized by the precision p
and
rounding mode r
Instances
Monad (Arith p r) Source # | |
Functor (Arith p r) Source # | |
Applicative (Arith p r) Source # | |
MonadState (Context p r) (Arith p r) Source # | The |
MonadError (Exception p r) (Arith p r) Source # | Traps (vis-à-vis |
Defined in Numeric.Decimal.Arithmetic throwError :: Exception p r -> Arith p r a # catchError :: Arith p r a -> (Exception p r -> Arith p r a) -> Arith p r a # |
runArith :: Arith p r a -> Context p r -> (Either (Exception p r) a, Context p r) Source #
Evaluate an arithmetic computation in the given context and return the final value (or exception) and resulting context.
evalArith :: Arith p r a -> Context p r -> Either (Exception p r) a Source #
Evaluate an arithmetic computation in the given context and return the final value or exception, discarding the resulting context.
subArith :: Arith a b (Decimal a b) -> Arith p r (Decimal a b) Source #
Perform a subcomputation using a different precision and/or rounding mode. The subcomputation is evaluated within a new context with all flags cleared and all traps disabled. Any flags set in the context of the subcomputation are ignored, but if an exception is returned it will be re-raised within the current context.
Exceptional conditions
Exceptional conditions are grouped into signals, which can be controlled
individually. A Context
contains a flag and a trap enabler (i.e. enabled
or disabled) for each Signal
.
A representation of an exceptional condition
Instances
Show (Exception p r) Source # | |
MonadError (Exception p r) (Arith p r) Source # | Traps (vis-à-vis |
Defined in Numeric.Decimal.Arithmetic throwError :: Exception p r -> Arith p r a # catchError :: Arith p r a -> (Exception p r -> Arith p r a) -> Arith p r a # |
exceptionSignal :: Exception p r -> Signal Source #
The signal raised by the exceptional condition
exceptionResult :: Exception p r -> Decimal p r Source #
The defined result for the exceptional condition
Signals
Clamped | Raised when the exponent of a result has been altered or constrained in order to fit the constraints of a specific concrete representation |
DivisionByZero | Raised when a non-zero dividend is divided by zero |
Inexact | Raised when a result is not exact (one or more non-zero coefficient digits were discarded during rounding) |
InvalidOperation | Raised when a result would be undefined or impossible |
Overflow | Raised when the exponent of a result is too large to be represented |
Rounded | Raised when a result has been rounded (that is, some zero or non-zero coefficient digits were discarded) |
Subnormal | Raised when a result is subnormal (its adjusted exponent is less than Emin), before any rounding |
Underflow | Raised when a result is both subnormal and inexact |
A group of signals can be manipulated as a set.
allSignals :: Signals Source #
A set containing every signal
raiseSignal :: Signal -> Decimal p r -> Arith p r (Decimal p r) Source #
Set the given signal flag in the context of the current arithmetic computation, and call the trap handler if the trap for this signal is currently enabled.
clearFlags :: Signals -> Arith p r () Source #
Clear the given signal flags from the context of the current arithmetic computation.
Traps
type TrapHandler p r = Exception p r -> Arith p r (Decimal p r) Source #
A trap handler function may return a substitute result for the operation
that caused the exceptional condition, or it may call throwError
to pass
control to an enclosing catchError
handler (or abort the arithmetic
computation).
trap :: Signals -> TrapHandler p r -> Arith p r a -> Arith p r a Source #
Evaluate an arithmetic computation within a modified context that enables the given signals to be trapped by the given handler. The previous trap handler (and enabler state) will be restored during any trap, as well as upon completion. Any existing trap handlers for signals not mentioned remain in effect.