Copyright | © 2016–2017 Robert Leslie |
---|---|
License | BSD3 |
Maintainer | rob@mars.org |
Stability | experimental |
Safe Haskell | Trustworthy |
Language | Haskell2010 |
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.
Some decimal numbers also support encoding and decoding specific IEEE 754
interchange formats via a Binary
instance.
Synopsis
- data Decimal p r
- type BasicDecimal = Decimal P9 RoundHalfUp
- type ExtendedDecimal p = Decimal p RoundHalfEven
- type GeneralDecimal = ExtendedDecimal PInfinite
- type Decimal32 = ExtendedDecimal Pdecimal32
- type Decimal64 = ExtendedDecimal Pdecimal64
- type Decimal128 = ExtendedDecimal Pdecimal128
- class Precision p
- class Precision p => FinitePrecision p
- data P1
- type P2 = PTimes2 P1
- type P3 = PPlus1 P2
- type P4 = PTimes2 P2
- 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
- data PTimes2 p
- data PInfinite
- type Pdecimal32 = Format K32 DecimalCoefficient
- type Pdecimal64 = Format K64 DecimalCoefficient
- type Pdecimal128 = Format K128 DecimalCoefficient
- class Rounding r
- data RoundHalfUp
- data RoundHalfEven
- data RoundHalfDown
- data RoundCeiling
- data RoundFloor
- data RoundUp
- data Round05Up
- data RoundDown
- cast :: (Precision p, Rounding r) => Decimal a b -> Decimal p r
- fromBool :: Bool -> Decimal p r
- fromOrdering :: Ordering -> Decimal p r
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,
is a number type with 15 decimal digits of precision. There is a range of ready-made precisions available, includingExtendedDecimal
P15
P1
throughP50
on up toP2000
.GeneralDecimal
is a number type with infinite precision. Note that not all operations support numbers with infinite precision.Decimal32
,Decimal64
, andDecimal128
are specialized number types withBinary
instances that implement the decimal32, decimal64, and decimal128 interchange format encodings described in IEEE 754-2008. These types have precisions of 7, 16, and 34 decimal digits, respectively, and round half even.- The most versatile
Decimal
type constructor is parameterized by both a precision and a rounding algorithm. For example,
is a number type with 20 decimal digits of precision that rounds down (truncates). SeveralDecimal
P20
RoundDown
Rounding
algorithms are available to choose from.
A decimal number type may be used in a default
declaration, for example
replacing Double
:
default (Integer, BasicDecimal)
Advanced usage
Additional operations and control beyond what is provided by the standard 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 precisions can be constructed through type application of PPlus1
and/or PTimes2
to any existing precision.
It is possible to create arbitrary width interchange format encodings with the help of Numeric.Decimal.Encoding.
Arbitrary-precision decimal numbers
A decimal floating point number with selectable precision and rounding algorithm
Instances
(Precision p, Rounding r) => Enum (Decimal p r) Source # | Unlike the instances for |
Defined in Numeric.Decimal.Number 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) Source # | Note that NaN values are not equal to any value, including other NaNs. |
(FinitePrecision p, Rounding r) => Floating (Decimal p r) Source # | The constant |
Defined in Numeric.Decimal.Number 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 # | |
(FinitePrecision p, Rounding r) => Fractional (Decimal p r) Source # | |
(Precision p, Rounding r) => Num (Decimal p r) Source # | |
Defined in Numeric.Decimal.Number (+) :: 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 # | |
Ord (Decimal p r) Source # | Unlike the instances for |
Defined in Numeric.Decimal.Number | |
(Precision p, Rounding r) => Read (Decimal p r) Source # | The |
(Precision p, Rounding r) => Real (Decimal p r) Source # | |
Defined in Numeric.Decimal.Number toRational :: Decimal p r -> Rational # | |
(FinitePrecision p, Rounding r) => RealFloat (Decimal p r) Source # | |
Defined in Numeric.Decimal.Number 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 # | |
(FinitePrecision p, Rounding r) => RealFrac (Decimal p r) Source # | |
Show (Decimal p r) Source # | The |
FinitePrecision p => Bits (Decimal p r) Source # | The |
Defined in Numeric.Decimal.Number (.&.) :: Decimal p r -> Decimal p r -> Decimal p r # (.|.) :: Decimal p r -> Decimal p r -> Decimal p r # xor :: Decimal p r -> Decimal p r -> Decimal p r # complement :: Decimal p r -> Decimal p r # shift :: Decimal p r -> Int -> Decimal p r # rotate :: Decimal p r -> Int -> Decimal p r # setBit :: Decimal p r -> Int -> Decimal p r # clearBit :: Decimal p r -> Int -> Decimal p r # complementBit :: Decimal p r -> Int -> Decimal p r # testBit :: Decimal p r -> Int -> Bool # bitSizeMaybe :: Decimal p r -> Maybe Int # bitSize :: Decimal p r -> Int # isSigned :: Decimal p r -> Bool # shiftL :: Decimal p r -> Int -> Decimal p r # unsafeShiftL :: Decimal p r -> Int -> Decimal p r # shiftR :: Decimal p r -> Int -> Decimal p r # unsafeShiftR :: Decimal p r -> Int -> Decimal p r # rotateL :: Decimal p r -> Int -> Decimal p r # | |
FinitePrecision p => FiniteBits (Decimal p r) Source # | |
Defined in Numeric.Decimal.Number finiteBitSize :: Decimal p r -> Int # countLeadingZeros :: Decimal p r -> Int # countTrailingZeros :: Decimal p r -> Int # | |
Parameters k => Binary (Decimal (Format k DecimalCoefficient) r) # | A |
Defined in Numeric.Decimal.Encoding | |
NFData (Decimal p r) Source # | |
Defined in Numeric.Decimal.Number | |
Precision p => Precision (Decimal p r) Source # | |
type BasicDecimal = Decimal P9 RoundHalfUp Source #
A decimal floating point number with 9 digits of precision, rounding half up
type ExtendedDecimal p = Decimal p RoundHalfEven Source #
A decimal floating point number with selectable precision, rounding half even
type GeneralDecimal = ExtendedDecimal PInfinite Source #
A decimal floating point number with infinite precision
Number types with defined encodings
These decimal number types have a Binary
instance that
implements a specific interchange format encoding described in IEEE
754-2008. See Numeric.Decimal.Encoding for further details, including the
ability to create additional formats of arbitrary width.
Alternative rounding algorithms can be used through the more general Decimal
type constructor and the special precision types Pdecimal32
, Pdecimal64
,
or Pdecimal128
, e.g.
.Decimal
Pdecimal64
RoundCeiling
type Decimal32 = ExtendedDecimal Pdecimal32 Source #
A decimal floating point number with 7 digits of precision, rounding half even, and a 32-bit encoded representation using the decimal32 interchange format (with a decimal encoding for the coefficient)
type Decimal64 = ExtendedDecimal Pdecimal64 Source #
A decimal floating point number with 16 digits of precision, rounding half even, and a 64-bit encoded representation using the decimal64 interchange format (with a decimal encoding for the coefficient)
type Decimal128 = ExtendedDecimal Pdecimal128 Source #
A decimal floating point number with 34 digits of precision, rounding half even, and a 128-bit encoded representation using the decimal128 interchange format (with a decimal encoding for the coefficient)
Precision types
Precision indicates the maximum number of significant decimal digits a number may have.
precision
Instances
Precision P1 Source # | |
Precision PInfinite Source # | |
Precision p => Precision (PTimes2 p) Source # | |
Precision p => Precision (PPlus1 p) Source # | |
Precision p => Precision (Decimal p r) Source # | |
Parameters k => Precision (Format k c) Source # | This |
class Precision p => FinitePrecision p Source #
A subclass of precisions that are finite
Instances
FinitePrecision P1 Source # | |
Defined in Numeric.Decimal.Precision | |
FinitePrecision p => FinitePrecision (PTimes2 p) Source # | |
Defined in Numeric.Decimal.Precision | |
FinitePrecision p => FinitePrecision (PPlus1 p) Source # | |
Defined in Numeric.Decimal.Precision | |
Parameters k => FinitePrecision (Format k c) Source # | |
Defined in Numeric.Decimal.Encoding |
A precision of 1 significant digit
A precision of (p
+ 1) significant digits
A precision of (p
× 2) significant digits
A precision of unlimited significant digits
type Pdecimal32 = Format K32 DecimalCoefficient Source #
A type with Precision
instance specifying decimal32 interchange
format parameters (using a decimal encoding for the coefficient) having an
effective precision of 7 decimal digits
type Pdecimal64 = Format K64 DecimalCoefficient Source #
A type with Precision
instance specifying decimal64 interchange
format parameters (using a decimal encoding for the coefficient) having an
effective precision of 16 decimal digits
type Pdecimal128 = Format K128 DecimalCoefficient Source #
A type with Precision
instance specifying decimal128 interchange
format parameters (using a decimal encoding for the coefficient) having an
effective precision of 34 decimal digits
Rounding types
A rounding algorithm to use when the result of an arithmetic operation exceeds the precision of the result type
rounding, roundCoefficient
Instances
data RoundHalfUp Source #
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 Source # | |
Defined in Numeric.Decimal.Rounding rounding :: RoundHalfUp -> RoundingAlgorithm roundCoefficient :: RoundHalfUp -> Rounder |
data RoundHalfEven Source #
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 Source # | |
Defined in Numeric.Decimal.Rounding rounding :: RoundHalfEven -> RoundingAlgorithm roundCoefficient :: RoundHalfEven -> Rounder |
data RoundHalfDown Source #
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 Source # | |
Defined in Numeric.Decimal.Rounding rounding :: RoundHalfDown -> RoundingAlgorithm roundCoefficient :: RoundHalfDown -> Rounder |
data RoundCeiling Source #
(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 Source # | |
Defined in Numeric.Decimal.Rounding rounding :: RoundCeiling -> RoundingAlgorithm roundCoefficient :: RoundCeiling -> Rounder |
data RoundFloor Source #
(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 Source # | |
Defined in Numeric.Decimal.Rounding rounding :: RoundFloor -> RoundingAlgorithm roundCoefficient :: RoundFloor -> Rounder |
(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 Source # | |
Defined in Numeric.Decimal.Rounding rounding :: RoundUp -> RoundingAlgorithm roundCoefficient :: RoundUp -> Rounder |
(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 Source # | |
Defined in Numeric.Decimal.Rounding rounding :: Round05Up -> RoundingAlgorithm roundCoefficient :: Round05Up -> Rounder |
(Round toward 0; truncate.) The discarded digits are ignored; the result is unchanged.
Instances
Rounding RoundDown Source # | |
Defined in Numeric.Decimal.Rounding rounding :: RoundDown -> RoundingAlgorithm roundCoefficient :: RoundDown -> Rounder |
Functions
cast :: (Precision p, Rounding r) => Decimal a b -> Decimal p r Source #
Cast a Decimal
to another precision and/or rounding algorithm,
immediately rounding if necessary to the new precision using the new
algorithm.
fromOrdering :: Ordering -> Decimal p r Source #
Return -1
, 0
, or 1
if the argument is LT
, EQ
, or GT
,
respectively. This allows an all-decimal usage of the operations from
Numeric.Decimal.Operation that return an Ordering
.