Numeric.Decimal

This module provides a general-purpose number type supporting decimal arithmetic for both limited precision floating-point (IEEE 754-2008) and for arbitrary precision floating-point (following the same principles as IEEE 754 and IEEE 854-1987) as described in the General Decimal Arithmetic Specification by Mike Cowlishaw. In addition to floating-point arithmetic, integer and unrounded floating-point arithmetic are included as subsets.

Unlike the binary floating-point types Float and Double, decimal number types can perform decimal arithmetic exactly. Internally, decimal numbers are represented with an integral coefficient and base-10 exponent.

>>> 29.99 + 4.71 :: Double
34.699999999999996

>>> 29.99 + 4.71 :: BasicDecimal
34.70

>>> 0.1 + 0.2 == (0.3 :: Double)
False

>>> 0.1 + 0.2 == (0.3 :: BasicDecimal)
True

Decimal numbers support lossless conversion to and from a string representation via Show and Read instances. Note that there may be multiple representations of values that are numerically equal (e.g. 1 and 1.00) which are preserved by this conversion.

Usage

You should choose a decimal number type with appropriate precision and rounding to use in your application. There are several options:

• BasicDecimal is a number type with 9 decimal digits of precision that rounds half up.
• ExtendedDecimal is a number type constructor with selectable precision that rounds half even. For example, ExtendedDecimal P34 is a number type with 34 decimal digits of precision. There is a range of ready-made precisions available, including P1 through P50 on up to P2000 (the IEEE 754 smallest and basic formats correspond to precisions P7, P16, or P34). Alternatively, an arbitrary precision can be constructed through type application of PPlus1 and/or PTimes2 to any existing precision.
• GeneralDecimal is a number type with infinite precision. Note that not all operations support numbers with infinite precision.
• The most versatile Decimal type constructor is parameterized by both a precision and a rounding algorithm. For example, Decimal P20 RoundDown is a number type with 20 decimal digits of precision that rounds down (truncates). Several Rounding algorithms are available to choose from.

It is suggested to create an alias for the type of numbers you wish to support in your application. For example:

type Number = ExtendedDecimal P16

A decimal number type may be used in a default declaration, possibly replacing Double and/or Integer. For example:

default (Integer, BasicDecimal)

Advanced usage

Additional operations and control beyond what is provided by the basic numeric type classes are available through the use of Numeric.Decimal.Arithmetic and Numeric.Decimal.Operation. Advanced string conversion is also available through Numeric.Decimal.Conversion.

Arbitrary-precision decimal numbers

data Decimal p r

A decimal floating point number with selectable precision and rounding algorithm

Instances

(Precision p, Rounding r) => Enum (Decimal p r)

Unlike the instances for Float and Double, the lists returned by the enumFromTo and enumFromThenTo methods in this instance terminate with the last element strictly less than (greater than in the case of a negative increment) or equal to the given bound.

Eq (Decimal p r)

(FinitePrecision p, Rounding r) => Floating (Decimal p r)

The trigonometric and hyperbolic Floating methods (other than the precision-dependent constant pi) are not yet implemented.

(FinitePrecision p, Rounding r) => Fractional (Decimal p r)

(Precision p, Rounding r) => Num (Decimal p r)

(Precision p, Rounding r) => Ord (Decimal p r)

(Precision p, Rounding r) => Read (Decimal p r)

The Read instance uses the toNumber operation from Numeric.Decimal.Conversion and rounds the result to the required precision.

(Precision p, Rounding r) => Real (Decimal p r)

(FinitePrecision p, Rounding r) => RealFloat (Decimal p r)

(FinitePrecision p, Rounding r) => RealFrac (Decimal p r)

Show (Decimal p r)

The Show instance uses the toScientificString operation from Numeric.Decimal.Conversion.

FinitePrecision p => Bits (Decimal p r)

The Bits instance makes use of the logical operations from the General Decimal Arithmetic Specification using a digit-wise representation of bits where the sign is non-negative, the exponent is 0, and each decimal digit of the coefficient must be either 0 or 1.

FinitePrecision p => FiniteBits (Decimal p r)

Precision p => Precision (Decimal p r)

type BasicDecimal = Decimal P9 RoundHalfUp

A decimal floating point number with 9 digits of precision, rounding half up

type ExtendedDecimal p = Decimal p RoundHalfEven

A decimal floating point number with selectable precision, rounding half even

type GeneralDecimal = ExtendedDecimal PInfinite

A decimal floating point number with infinite precision

Precision types

class Precision p where

Precision indicates the maximum number of significant decimal digits a number may have.

Methods

precision :: p -> Maybe Int

Return the precision of the argument, or Nothing if the precision is infinite.

Instances

Precision P1

Precision PInfinite

Precision p => Precision (PTimes2 p)

Precision p => Precision (PPlus1 p)

Precision p => Precision (Decimal p r)

class Precision p => FinitePrecision p

A subclass of precisions that are finite

Instances

FinitePrecision P1

FinitePrecision p => FinitePrecision (PTimes2 p)

FinitePrecision p => FinitePrecision (PPlus1 p)

data P1

A precision of 1 significant digit

Instances

FinitePrecision P1

Precision P1

type P2 = PTimes2 P1

A precision of 2 significant digits

type P3 = PPlus1 P2

A precision of 3 significant digits

type P4 = PTimes2 P2

Et cetera

type P5 = PPlus1 P4

type P6 = PTimes2 P3

type P7 = PPlus1 P6

type P8 = PTimes2 P4

type P9 = PPlus1 P8

type P10 = PTimes2 P5

type P11 = PPlus1 P10

type P12 = PTimes2 P6

type P13 = PPlus1 P12

type P14 = PTimes2 P7

type P15 = PPlus1 P14

type P16 = PTimes2 P8

type P17 = PPlus1 P16

type P18 = PTimes2 P9

type P19 = PPlus1 P18

type P20 = PTimes2 P10

type P21 = PPlus1 P20

type P22 = PTimes2 P11

type P23 = PPlus1 P22

type P24 = PTimes2 P12

type P25 = PPlus1 P24

type P26 = PTimes2 P13

type P27 = PPlus1 P26

type P28 = PTimes2 P14

type P29 = PPlus1 P28

type P30 = PTimes2 P15

type P31 = PPlus1 P30

type P32 = PTimes2 P16

type P33 = PPlus1 P32

type P34 = PTimes2 P17

type P35 = PPlus1 P34

type P36 = PTimes2 P18

type P37 = PPlus1 P36

type P38 = PTimes2 P19

type P39 = PPlus1 P38

type P40 = PTimes2 P20

type P41 = PPlus1 P40

type P42 = PTimes2 P21

type P43 = PPlus1 P42

type P44 = PTimes2 P22

type P45 = PPlus1 P44

type P46 = PTimes2 P23

type P47 = PPlus1 P46

type P48 = PTimes2 P24

type P49 = PPlus1 P48

type P50 = PTimes2 P25

type P75 = PPlus1 P74

type P100 = PTimes2 P50

type P150 = PTimes2 P75

type P200 = PTimes2 P100

type P250 = PTimes2 P125

type P300 = PTimes2 P150

type P400 = PTimes2 P200

type P500 = PTimes2 P250

type P1000 = PTimes2 P500

type P2000 = PTimes2 P1000

data PPlus1 p

A precision of (p + 1) significant digits

Instances

FinitePrecision p => FinitePrecision (PPlus1 p)

Precision p => Precision (PPlus1 p)

data PTimes2 p

A precision of (p × 2) significant digits

Instances

FinitePrecision p => FinitePrecision (PTimes2 p)

Precision p => Precision (PTimes2 p)

data PInfinite

A precision of unlimited significant digits

Instances

Precision PInfinite

Rounding types

class Rounding r

A rounding algorithm to use when the result of an arithmetic operation exceeds the precision of the result type

Minimal complete definition

rounding, roundCoefficient

Instances

Rounding Round05Up

Rounding RoundUp

Rounding RoundHalfDown

Rounding RoundFloor

Rounding RoundCeiling

Rounding RoundHalfEven

Rounding RoundHalfUp

Rounding RoundDown

data RoundHalfUp

If the discarded digits represent greater than or equal to half (0.5) of the value of a one in the next left position then the result coefficient should be incremented by 1 (rounded up). Otherwise the discarded digits are ignored.

Instances

Rounding RoundHalfUp

data RoundHalfEven

If the discarded digits represent greater than half (0.5) the value of a one in the next left position then the result coefficient should be incremented by 1 (rounded up). If they represent less than half, then the result coefficient is not adjusted (that is, the discarded digits are ignored).

Otherwise (they represent exactly half) the result coefficient is unaltered if its rightmost digit is even, or incremented by 1 (rounded up) if its rightmost digit is odd (to make an even digit).

Instances

Rounding RoundHalfEven

data RoundHalfDown

If the discarded digits represent greater than half (0.5) of the value of a one in the next left position then the result coefficient should be incremented by 1 (rounded up). Otherwise (the discarded digits are 0.5 or less) the discarded digits are ignored.

Instances

Rounding RoundHalfDown

data RoundCeiling

(Round toward +∞.) If all of the discarded digits are zero or if the sign is 1 the result is unchanged. Otherwise, the result coefficient should be incremented by 1 (rounded up).

Instances

Rounding RoundCeiling

data RoundFloor

(Round toward −∞.) If all of the discarded digits are zero or if the sign is 0 the result is unchanged. Otherwise, the sign is 1 and the result coefficient should be incremented by 1.

Instances

Rounding RoundFloor

data RoundUp

(Round away from 0.) If all of the discarded digits are zero the result is unchanged. Otherwise, the result coefficient should be incremented by 1 (rounded up).

Instances

Rounding RoundUp

data Round05Up

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

Instances

Rounding Round05Up

data RoundDown

(Round toward 0; truncate.) The discarded digits are ignored; the result is unchanged.

Instances

Rounding RoundDown

Functions

cast :: (Precision p, Rounding r) => Decimal a b -> Decimal p r

Cast a Decimal to another precision and/or rounding algorithm, immediately rounding if necessary to the new precision using the new algorithm.

fromBool :: Bool -> Decimal p r

If the argument is False, return a Decimal value zero; if True, return the value one. This is basically an optimized toEnum . fromEnum to support an all-decimal usage of the operations from Numeric.Decimal.Operation that return a Bool.