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.

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)

Methods

succ :: Decimal p r -> Decimal p r

pred :: Decimal p r -> Decimal p r

toEnum :: Int -> Decimal p r

fromEnum :: Decimal p r -> Int

enumFrom :: Decimal p r -> [Decimal p r]

enumFromThen :: Decimal p r -> Decimal p r -> [Decimal p r]

enumFromTo :: Decimal p r -> Decimal p r -> [Decimal p r]

enumFromThenTo :: Decimal p r -> Decimal p r -> Decimal p r -> [Decimal p r]

Eq (Decimal p r)

Methods

(==) :: Decimal p r -> Decimal p r -> Bool

(/=) :: Decimal p r -> Decimal p r -> Bool

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

Methods

pi :: Decimal p r

exp :: Decimal p r -> Decimal p r

log :: Decimal p r -> Decimal p r

sqrt :: Decimal p r -> Decimal p r

(**) :: Decimal p r -> Decimal p r -> Decimal p r

logBase :: Decimal p r -> Decimal p r -> Decimal p r

sin :: Decimal p r -> Decimal p r

cos :: Decimal p r -> Decimal p r

tan :: Decimal p r -> Decimal p r

asin :: Decimal p r -> Decimal p r

acos :: Decimal p r -> Decimal p r

atan :: Decimal p r -> Decimal p r

sinh :: Decimal p r -> Decimal p r

cosh :: Decimal p r -> Decimal p r

tanh :: Decimal p r -> Decimal p r

asinh :: Decimal p r -> Decimal p r

acosh :: Decimal p r -> Decimal p r

atanh :: Decimal p r -> Decimal p r

log1p :: Decimal p r -> Decimal p r

expm1 :: Decimal p r -> Decimal p r

log1pexp :: Decimal p r -> Decimal p r

log1mexp :: Decimal p r -> Decimal p r

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

Methods

(/) :: Decimal p r -> Decimal p r -> Decimal p r

recip :: Decimal p r -> Decimal p r

fromRational :: Rational -> Decimal p r

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

Methods

(+) :: Decimal p r -> Decimal p r -> Decimal p r

(-) :: Decimal p r -> Decimal p r -> Decimal p r

(*) :: Decimal p r -> Decimal p r -> Decimal p r

negate :: Decimal p r -> Decimal p r

abs :: Decimal p r -> Decimal p r

signum :: Decimal p r -> Decimal p r

fromInteger :: Integer -> Decimal p r

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

Methods

compare :: Decimal p r -> Decimal p r -> Ordering

(<) :: Decimal p r -> Decimal p r -> Bool

(<=) :: Decimal p r -> Decimal p r -> Bool

(>) :: Decimal p r -> Decimal p r -> Bool

(>=) :: Decimal p r -> Decimal p r -> Bool

max :: Decimal p r -> Decimal p r -> Decimal p r

min :: Decimal p r -> Decimal p r -> Decimal p r

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

Methods

readsPrec :: Int -> ReadS (Decimal p r)

readList :: ReadS [Decimal p r]

readPrec :: ReadPrec (Decimal p r)

readListPrec :: ReadPrec [Decimal p r]

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

Methods

toRational :: Decimal p r -> Rational

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

Methods

floatRadix :: Decimal p r -> Integer

floatDigits :: Decimal p r -> Int

floatRange :: Decimal p r -> (Int, Int)

decodeFloat :: Decimal p r -> (Integer, Int)

encodeFloat :: Integer -> Int -> Decimal p r

exponent :: Decimal p r -> Int

significand :: Decimal p r -> Decimal p r

scaleFloat :: Int -> Decimal p r -> Decimal p r

isNaN :: Decimal p r -> Bool

isInfinite :: Decimal p r -> Bool

isDenormalized :: Decimal p r -> Bool

isNegativeZero :: Decimal p r -> Bool

isIEEE :: Decimal p r -> Bool

atan2 :: Decimal p r -> Decimal p r -> Decimal p r

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

Methods

properFraction :: Integral b => Decimal p r -> (b, Decimal p r)

truncate :: Integral b => Decimal p r -> b

round :: Integral b => Decimal p r -> b

ceiling :: Integral b => Decimal p r -> b

floor :: Integral b => Decimal p r -> b

Show (Decimal p r)

Methods

showsPrec :: Int -> Decimal p r -> ShowS

show :: Decimal p r -> String

showList :: [Decimal p r] -> ShowS

Precision p => Precision (Decimal p r)

Methods

precision :: Decimal p r -> Maybe Int

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.

Minimal complete definition

precision

Methods

precision :: p -> Maybe Int

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

Instances

Precision P1

Methods

precision :: P1 -> Maybe Int

Precision PInfinite

Methods

precision :: PInfinite -> Maybe Int

Precision p => Precision (Decimal p r)

Methods

precision :: Decimal p r -> Maybe Int

class Precision p => FinitePrecision p

A subclass of precisions that are finite

Instances

FinitePrecision P1

data P1

A precision of 1 significant digit

Instances

FinitePrecision P1

Precision P1

Methods

precision :: P1 -> Maybe Int

type P2 = PPlus1 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 = PPlus5 (PTimes10 P7)

type P100 = PTimes2 P50

type P150 = PTimes2 P75

type P200 = PTimes2 P100

type P250 = PTimes10 P25

type P300 = PTimes2 P150

type P400 = PTimes2 P200

type P500 = PTimes2 P250

type P1000 = PTimes2 P500

type P2000 = PTimes2 P1000

type PPlus1 p

Arguments

 = PPlus p P1

A precision of (p + 1) significant digits

type PPlus2 p

Arguments

 = PPlus p P2

A precision of (p + 2) significant digits

type PPlus3 p

Arguments

 = PPlus p P3

A precision of (p + 3) significant digits

type PPlus4 p

Arguments

 = PPlus p P4

A precision of (p + 4) significant digits

type PPlus5 p

Arguments

 = PPlus p P5

A precision of (p + 5) significant digits

type PPlus6 p

Arguments

 = PPlus p P6

A precision of (p + 6) significant digits

type PPlus7 p

Arguments

 = PPlus p P7

A precision of (p + 7) significant digits

type PPlus8 p

Arguments

 = PPlus p P8

A precision of (p + 8) significant digits

type PPlus9 p

Arguments

 = PPlus p P9

A precision of (p + 9) significant digits

type PTimes2 = PTimes P2

type PTimes10 = PTimes P10

data PInfinite

A precision of unlimited significant digits

Instances

Precision PInfinite

Methods

precision :: PInfinite -> Maybe Int

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, round

Instances

Rounding Round05Up

Methods

rounding :: Round05Up -> RoundingAlgorithm

round :: Precision p => Decimal p Round05Up -> Arith p Round05Up (Decimal p Round05Up)

Rounding RoundUp

Methods

rounding :: RoundUp -> RoundingAlgorithm

round :: Precision p => Decimal p RoundUp -> Arith p RoundUp (Decimal p RoundUp)

Rounding RoundHalfDown

Methods

rounding :: RoundHalfDown -> RoundingAlgorithm

round :: Precision p => Decimal p RoundHalfDown -> Arith p RoundHalfDown (Decimal p RoundHalfDown)

Rounding RoundFloor

Methods

rounding :: RoundFloor -> RoundingAlgorithm

round :: Precision p => Decimal p RoundFloor -> Arith p RoundFloor (Decimal p RoundFloor)

Rounding RoundCeiling

Methods

rounding :: RoundCeiling -> RoundingAlgorithm

round :: Precision p => Decimal p RoundCeiling -> Arith p RoundCeiling (Decimal p RoundCeiling)

Rounding RoundHalfEven

Methods

rounding :: RoundHalfEven -> RoundingAlgorithm

round :: Precision p => Decimal p RoundHalfEven -> Arith p RoundHalfEven (Decimal p RoundHalfEven)

Rounding RoundHalfUp

Methods

rounding :: RoundHalfUp -> RoundingAlgorithm

round :: Precision p => Decimal p RoundHalfUp -> Arith p RoundHalfUp (Decimal p RoundHalfUp)

Rounding RoundDown

Methods

rounding :: RoundDown -> RoundingAlgorithm

round :: Precision p => Decimal p RoundDown -> Arith p RoundDown (Decimal p 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 value is rounded up. If they represent less than half, the value is rounded down.

Instances

Rounding RoundHalfUp

Methods

rounding :: RoundHalfUp -> RoundingAlgorithm

round :: Precision p => Decimal p RoundHalfUp -> Arith p RoundHalfUp (Decimal p RoundHalfUp)

data RoundHalfEven

If the discarded digits represent greater than half (0.5) of the value of a one in the next left position then the value is rounded up. If they represent less than half, the value is rounded down. If they represent exactly half, the value is rounded to make its rightmost digit even.

Instances

Rounding RoundHalfEven

Methods

rounding :: RoundHalfEven -> RoundingAlgorithm

round :: Precision p => Decimal p RoundHalfEven -> Arith p RoundHalfEven (Decimal p 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 value is rounded up. If they represent less than half or exactly half, the value is rounded down.

Instances

Rounding RoundHalfDown

Methods

rounding :: RoundHalfDown -> RoundingAlgorithm

round :: Precision p => Decimal p RoundHalfDown -> Arith p RoundHalfDown (Decimal p RoundHalfDown)

data RoundCeiling

Round toward +∞

Instances

Rounding RoundCeiling

Methods

rounding :: RoundCeiling -> RoundingAlgorithm

round :: Precision p => Decimal p RoundCeiling -> Arith p RoundCeiling (Decimal p RoundCeiling)

data RoundFloor

Round toward −∞

Instances

Rounding RoundFloor

Methods

rounding :: RoundFloor -> RoundingAlgorithm

round :: Precision p => Decimal p RoundFloor -> Arith p RoundFloor (Decimal p RoundFloor)

data RoundUp

Round away from 0

Instances

Rounding RoundUp

Methods

rounding :: RoundUp -> RoundingAlgorithm

round :: Precision p => Decimal p RoundUp -> Arith p RoundUp (Decimal p RoundUp)

data Round05Up

Round zero or five away from 0

Instances

Rounding Round05Up

Methods

rounding :: Round05Up -> RoundingAlgorithm

round :: Precision p => Decimal p Round05Up -> Arith p Round05Up (Decimal p Round05Up)

data RoundDown

Round toward 0 (truncate)

Instances

Rounding RoundDown

Methods

rounding :: RoundDown -> RoundingAlgorithm

round :: Precision p => Decimal p RoundDown -> Arith p RoundDown (Decimal p 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.

toBool :: Decimal p r -> Bool

Return False if the argument is zero or NaN, and True otherwise.