Safe Haskell	Safe
Language	Haskell2010

Deka.Context

Contents

Integer type
Ctx
Flags
- Individual flags
Traps
Status
Digits
Rounding
- Rounding types
- Getting and setting
Emax and Emin
- Emax
- Emin
Trio
Clamp
Correct rounding
Initializers
Running a Ctx

Synopsis

Integer type

type Signed = Int64 Source

A signed integer. Its size is platform dependent.

Ctx

data Ctx a Source

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

Flags

data Flag Source

Indicates error conditions. This type serves two purposes: computations set flags to indicate errors, and flags indicate which errors you want to have raise a signal. See getStatus, setStatus, getTraps, and setTraps.

Flag is an instance of Exception so that you can throw it if you want; however, none of the functions in the deka package throw.

Instances

Eq Flag
Ord Flag
Show Flag
Exception Flag
Typeable * Flag

data Flags Source

A container of Flag.

Instances

Eq Flags
Show Flags
Exception Flags
Typeable * Flags

allFlag :: [Flag] Source

A list of all possible Flag, in order.

fullFlags :: Flags Source

All possible Flag are set.

emptyFlags :: Flags Source

No Flag are set.

packFlags :: [Flag] -> Flags Source

unpackFlags :: Flags -> [Flag] Source

Flags will always be unpacked in order.

Individual flags

clamped :: Flag Source

conversionSyntax :: Flag Source

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

divisionByZero :: Flag Source

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

divisionImpossible :: Flag Source

Sometimes raised by divideInteger and remainder.

divisionUndefined :: Flag Source

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

fpuError :: Flag Source

inexact :: Flag Source

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

invalidContext :: Flag Source

The Context for computations was invalid; this error should never occur because deka keeps you from setting an invalid context.

invalidOperation :: Flag Source

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

mallocError :: Flag Source

notImplemented :: Flag Source

overflow :: Flag Source

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

rounded :: Flag Source

subnormal :: Flag Source

underflow :: Flag Source

A result is both subnormal and inexact.

Traps

getTraps :: Ctx Flags Source

Gets all currently set traps.

setTraps :: Flags -> Ctx () Source

If you set a trap, a computation will immediately raise SIGFPE if the corresponding error arises. (Currently this behavior cannot be configured to do something else.) setTraps clears all existing traps and sets them to the new ones you specify.

By setting a flag here, SIGFPE is raised if any subsequent computations raise the corresponding error condition. Setting a flag with this function or with setTrap never, by itself, causes SIGFPE to be raised; it is raised only by a subsequent computation. So, if you set a flag using this function or setTrap and the corresponding status flag is already set, SIGFPE will be raised only if a subsequent computation raises that error condition.

Status

getStatus :: Ctx Flags Source

All currently set status flags.

setStatus :: Flags -> Ctx () Source

Sets status flags. All existing status flags are cleared and replaced with the ones you indicate here.

Digits

data Precision Source

Sets the precision to be used for all operations. The result of an operation is rounded to this length if necessary.

Instances

Bounded Precision
Eq Precision
Ord Precision
Show Precision

precision :: Signed -> Maybe Precision Source

Creates a Precision that you can then set with setTrio. Returns Nothing if the argument is out of range. The minimum possible value is always 1; the maximum possible value is platform dependent and is revealed by maxBound.

unPrecision :: Precision -> Signed Source

getPrecision :: Ctx Precision Source

setMaxPrecision :: Ctx Precision Source

Sets the precision to the maximum possible, respecting that Emax > 5 * Precision. Returns the new Precision.

Rounding

Rounding types

data Round Source

Instances

Eq Round
Ord Round
Show Round

roundCeiling :: Round Source

Round toward positive infinity.

roundUp :: Round Source

Round away from zero.

roundHalfUp :: Round Source

0.5 rounds up

roundHalfEven :: Round Source

0.5 rounds to nearest even

roundHalfDown :: Round Source

0.5 rounds down

roundDown :: Round Source

Round toward zero - truncate

roundFloor :: Round Source

Round toward negative infinity.

round05Up :: Round Source

Round for reround

roundTruncate :: Round Source

Truncate, but set infinities.

Getting and setting

getRound :: Ctx Round Source

setRound :: Round -> Ctx () Source

Emax and Emin

Emax

data Emax Source

Maximum adjusted exponent. The adjusted exponent is calculated as though the number were expressed in scientific notation. If the adjusted exponent would be larger than Emax then an overflow results.

The minimum possible value is always 0; the maximum possible value is platform dependent and is revealed by maxBound.

Instances

Bounded Emax
Eq Emax
Ord Emax
Show Emax

unEmax :: Emax -> Signed Source

emax :: Signed -> Maybe Emax Source

Returns an Emax for use in setTrio. Fails if argument is out of range.

getEmax :: Ctx Emax Source

Emin

data Emin Source

Minimum adjusted exponent. The adjusted exponent is calculated as though the number were expressed in scientific notation. If the adjusted exponent would be smaller than Emin then the result is subnormal. If the result is also inexact, an underflow results. If subnormal results are allowed (see setClamp) the smallest possible exponent is Emin minus Precision plus 1.

The minimum possible value is platform dependent and is revealed by minBound; the maximum possible value is always 0.

Instances

Bounded Emin
Eq Emin
Ord Emin
Show Emin

unEmin :: Emin -> Signed Source

emin :: Signed -> Maybe Emin Source

Returns an Emin for use in setTrio. Fails if argument is out of range.

getEmin :: Ctx Emin Source

Trio

data Trio Source

In addition to the limits on Precision, Emax, and Emin, there are also requirements on the relationship between these three variables:

```
Emax > 5 * Precision
```
either Emin == 1 - Emax or Emin == -Emax

The Trio enforces this relationship.

It is also recommended that Emax > 10 * Precision, but since this is not required the Trio does not enforce it.

Instances

Show Trio

trioPrecision :: Trio -> Precision Source

trioEmax :: Trio -> Emax Source

trioEmin :: Trio -> Emin Source

trio :: Precision -> Emax -> Emin -> Maybe Trio Source

Make a new Trio. Fails if the values are out of range.

setTrio :: Trio -> Ctx () Source

getTrio :: Ctx Trio Source

Clamp

getClamp :: Ctx Bool Source

setClamp :: Bool -> Ctx () Source

Controls explicit exponent clamping. When False, a result exponent is limited to a maximum of emax and a minimum of emin (for example, the exponent of a zero result will be clamped to be in this range). When True, a result exponent has the same minimum but is limited to a maximum of emax-(digits-1). As well as clamping zeros, this may cause the coefficient of a result to be padded with zeros on the right in order to bring the exponent within range.

Also when True, this limits the length of NaN payloads to Precision - 1 when constructing a NaN by conversion from a string.

Correct rounding

getAllCorrectRound :: Ctx Bool Source

By default, most functions are correctly rounded. By setting allCorrectRound, correct rounding is additionally enabled for exp, ln, and log10. In this case, all functions except pow and invroot return correctly rounded results.

setAllCorrectRound :: Bool -> Ctx () Source

Initializers

data Initializer Source

Before running computations in a context. the context must be initialized with certain settings, such as the rounding mode, precision, and maximum adjusted exponent. An Initializer contains all these settings.

On 64-bit platforms, the maximums are:

Precision of ((1 * 10 ^ 18) - 1)
Emax of ((1 * 10 ^ 18) - 1)
Emin of -((1 * 10 ^ 18) - 1)

On 32-bit platforms, the maximums are:

Precision of 4.25 * 10 ^ 8
Emax of 4.25 * 10 ^ 8
Emin of -4.25 * 10 ^ 8

Constructors

Max	Sets: `Precision` to the maximum available `Emax` to the maximum available `Emin` to the minimum available `Round` to `roundHalfEven` Traps to `invalidOperation`, `divisionByZero`, `overflow`, `underflow` No status flags are set No newtrap is set `setClamp` is False `setAllCorrectRound` is True As noted in the documentation for `Trio`, the specification requires that `Emax > 5 * Precision`; `Max` does not respect this.
Default	Same as `Max`, except: Precision is `2 * MPD_RDIGITS`
Basic	Same as `Max`, except: `Precision` is 9 Traps to `invalidOperation`, `divisionByZero`, `overflow`, `underflow`, and `clamped`
Pedantic	Sets the maximum allowable figures, while respecting the restriction that stated in the specification and the `mpdecimal` documentation, which is that `Emax > 5 * Precision`. Also, sets no traps. This sets: `Emax` to the maximum available `Emin` to the minimum available `Precision` is set to `Emax div 5`. On 64-bit platforms, this is ((2 * 10 ^ 17) - 1); on 32-bit platforms, this is 8.5 * 10 ^ 8. `Round` to `roundHalfEven` No traps are set No status flags are set No newtrap is set `setClamp` is False `setAllCorrectRound` is True
Decimal32	Sets: `Precision` to `7` `Emax` to `96` `Emin` to `-95` Rounding to `roundHalfEven` No traps are enabled No status flags are set `newTrap` is clear `setClamp` is True `setAllCorrectRound` is True
Decimal64	Same as `Decimal32`, except: `Precision` is `16` `Emax` is `384` `Emin` is `-383`
Decimal128	Same as `Decimal32`, except: `Precision` is `34` `Emax` is `6144` `Emin` is `-6143`

initCtx :: Initializer -> Ctx () Source

Re-initialize a Ctx using the given Initializer.

Running a Ctx

runCtxInit :: Initializer -> Ctx a -> a Source

Runs a Ctx computation; begins with the given Initializer to set up the context.

runCtx :: Ctx a -> a Source

Runs a Ctx computation using the Pedantic Initializer.

runCtxStatus :: Ctx a -> (a, Flags) Source

Like runCtx but also returns any status flags resulting from the computation.

local Source

Arguments

:: Ctx a	Run this computation. It is initialized with the current Ctx, but does not affect the current Ctx.
-> Ctx a	Returns the result of the child computation.

Runs a Ctx computation within the existing Ctx. The existing Ctx is copied to form a new Ctx; then the child computation is run without affecting the parent Ctx.