| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Data.Decimal
Contents
Description
Decimal numbers are represented as m*10^(-e) where
m and e are integers. The exponent e is an unsigned Word8. Hence
the smallest value that can be represented is 10^-255.
Unary arithmetic results have the exponent of the argument. Addition and subtraction results have an exponent equal to the maximum of the exponents of the arguments. Other operators have exponents sufficient to show the exact result, up to a limit of 255:
0.15 * 0.15 :: Decimal = 0.0225 (1/3) :: Decimal = 0.33333333333333... decimalPlaces (1/3) = 255
While (/) is defined, you don't normally want to use it. Instead
The functions "divide" and "allocate" will split a decimal amount
into lists of results which are guaranteed to sum to the original
number. This is a useful property when doing financial arithmetic.
The arithmetic on mantissas is always done using Integer, regardless of
the type of DecimalRaw being manipulated. In practice it is strongly
recommended that Decimal be used, with other types being used only where
necessary (e.g. to conform to a network protocol). For instance
(1/3) :: DecimalRaw Int does not give the right answer.
- data DecimalRaw i = Decimal {
- decimalPlaces :: !Word8
- decimalMantissa :: !i
- type Decimal = DecimalRaw Integer
- realFracToDecimal :: (Integral i, RealFrac r) => Word8 -> r -> DecimalRaw i
- decimalConvert :: (Integral a, Integral b, Bounded b) => DecimalRaw a -> Maybe (DecimalRaw b)
- unsafeDecimalConvert :: (Integral a, Integral b) => DecimalRaw a -> DecimalRaw b
- roundTo :: Integral i => Word8 -> DecimalRaw i -> DecimalRaw i
- (*.) :: (Integral i, RealFrac r) => DecimalRaw i -> r -> DecimalRaw i
- divide :: Decimal -> Int -> [(Int, Decimal)]
- allocate :: Decimal -> [Integer] -> [Decimal]
- eitherFromRational :: Integral i => Rational -> Either String (DecimalRaw i)
- normalizeDecimal :: Integral i => DecimalRaw i -> DecimalRaw i
Decimal Values
data DecimalRaw i Source
Raw decimal arithmetic type constructor. A decimal value consists of an
integer mantissa and a negative exponent which is interpreted as the number
of decimal places. The value stored in a Decimal d is therefore equal to:
decimalMantissa d / (10 ^ decimalPlaces d)
The Show instance will add trailing zeros, so show $ Decimal 3 1500
will return "1.500". Conversely the Read instance will use the decimal
places to determine the precision.
Regardless of the type of the arguments, all mantissa arithmetic is done
using Integer types, so application developers do not need to worry about
overflow in the internal algorithms. However the result of each operator
will be converted to the mantissa type without checking for overflow.
Constructors
| Decimal | |
Fields
| |
Instances
| Integral i => Enum (DecimalRaw i) | |
| Integral i => Eq (DecimalRaw i) | |
| Integral i => Fractional (DecimalRaw i) | |
| Integral i => Num (DecimalRaw i) | |
| Integral i => Ord (DecimalRaw i) | |
| (Integral i, Read i) => Read (DecimalRaw i) | |
| Integral i => Real (DecimalRaw i) | |
| Integral i => RealFrac (DecimalRaw i) | |
| (Integral i, Show i) => Show (DecimalRaw i) | |
| NFData i => NFData (DecimalRaw i) | |
| Typeable (* -> *) DecimalRaw |
type Decimal = DecimalRaw Integer Source
Arbitrary precision decimal type. Programs should do decimal arithmetic with this type and only convert to other instances of DecimalRaw where required by an external interface.
Using this type is also faster because it avoids repeated conversions
to and from Integer.
realFracToDecimal :: (Integral i, RealFrac r) => Word8 -> r -> DecimalRaw i Source
Convert a real fractional value into a Decimal of the appropriate precision.
decimalConvert :: (Integral a, Integral b, Bounded b) => DecimalRaw a -> Maybe (DecimalRaw b) Source
Convert a DecimalRaw from one base to another. Returns Nothing if
this would cause arithmetic overflow.
unsafeDecimalConvert :: (Integral a, Integral b) => DecimalRaw a -> DecimalRaw b Source
Convert a DecimalRaw from one base representation to another. Does
not check for overflow in the new representation. Only use after
using "roundTo" to put an upper value on the exponent, or to convert
to a larger representation.
roundTo :: Integral i => Word8 -> DecimalRaw i -> DecimalRaw i Source
Round a DecimalRaw to a specified number of decimal places.
If the value ends in 5 then it is rounded away from zero.
(*.) :: (Integral i, RealFrac r) => DecimalRaw i -> r -> DecimalRaw i Source
Multiply a DecimalRaw by a RealFrac value.
divide :: Decimal -> Int -> [(Int, Decimal)] Source
Divide a DecimalRaw value into one or more portions. The portions
will be approximately equal, and the sum of the portions is guaranteed to
be the original value.
The portions are represented as a list of pairs. The first part of each
pair is the number of portions, and the second part is the portion value.
Hence 10 dollars divided 3 ways will produce [(2, 3.33), (1, 3.34)].
allocate :: Decimal -> [Integer] -> [Decimal] Source
Allocate a DecimalRaw value proportionately with the values in a list.
The allocated portions are guaranteed to add up to the original value.
Some of the allocations may be zero or negative, but the sum of the list must not be zero. The allocation is intended to be as close as possible to the following:
let result = allocate d parts in all (== d / sum parts) $ zipWith (/) result parts
eitherFromRational :: Integral i => Rational -> Either String (DecimalRaw i) Source
Try to convert Rational to Decimal with absolute precision return string with fail description if not converted
normalizeDecimal :: Integral i => DecimalRaw i -> DecimalRaw i Source
Reduce the exponent of the decimal number to the minimal possible value