-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Decimal numbers with variable precision
--   
--   A decimal number has an integer mantissa and a negative exponent. The
--   exponent can be interpreted as the number of decimal places in the
--   value.
@package Decimal
@version 0.3.1


-- | Decimal numbers are represented as <tt>m*10^(-e)</tt> where <tt>m</tt>
--   and <tt>e</tt> are integers. The exponent <tt>e</tt> is an unsigned
--   Word8. Hence the smallest value that can be represented is
--   <tt>10^-255</tt>.
--   
--   Unary arithmetic results have the exponent of the argument. Binary
--   arithmetic results have an exponent equal to the maximum of the
--   exponents of the arguments.
--   
--   Decimal numbers are defined as instances of <tt>Real</tt>. This means
--   that conventional division is not defined. Instead the functions
--   <tt>divide</tt> and <tt>allocate</tt> will split a decimal amount into
--   lists of results. These results 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 <tt>Integer</tt>,
--   regardless of the type of <tt>DecimalRaw</tt> being manipulated. In
--   practice it is recommended that <tt>Decimal</tt> be used, with other
--   types being used only where necessary (e.g. to conform to a network
--   protocol).
module Data.Decimal

-- | 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 <tt>Decimal d</tt>
--   is therefore equal to:
--   
--   <pre>
--   decimalMantissa d / (10 ^ decimalPlaces d)
--   </pre>
--   
--   The <a>Show</a> instance will add trailing zeros, so <tt>show $
--   Decimal 3 1500</tt> will return "1.500". Conversely the <a>Read</a>
--   instance will use the decimal places to determine the precision.
--   
--   Arithmetic and comparision operators convert their arguments to the
--   greater of the two precisions, and return a result of that precision.
--   Regardless of the type of the arguments, all mantissa arithmetic is
--   done using <tt>Integer</tt> 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.
data Integral i => DecimalRaw i
Decimal :: !Word8 -> !i -> DecimalRaw i
decimalPlaces :: DecimalRaw i -> !Word8
decimalMantissa :: DecimalRaw i -> !i

-- | Arbitrary precision decimal type. As a rule programs should do decimal
--   arithmetic with this type and only convert to other instances of
--   <a>DecimalRaw</a> where required by an external interface.
--   
--   Using this type is also faster because it avoids repeated conversions
--   to and from <tt>Integer</tt>.
type Decimal = DecimalRaw Integer

-- | Convert a real fractional value into a Decimal of the appropriate
--   precision.
realFracToDecimal :: (Integral i, RealFrac r) => Word8 -> r -> DecimalRaw i

-- | Convert a <tt>DecimalRaw</tt> from one base representation to another.
--   Does not check for overflow in the new representation.
decimalConvert :: (Integral a, Integral b) => DecimalRaw a -> DecimalRaw b

-- | Round a <tt>DecimalRaw</tt> to a specified number of decimal places.
roundTo :: Integral i => Word8 -> DecimalRaw i -> DecimalRaw Integer

-- | Multiply a <tt>DecimalRaw</tt> by a <tt>RealFrac</tt> value.
(*.) :: (Integral i, RealFrac r) => DecimalRaw i -> r -> DecimalRaw i

-- | Divide a <tt>DecimalRaw</tt> 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 <tt>[(2,
--   3.33), (1, 3.34)]</tt>.
divide :: Integral i => DecimalRaw i -> Int -> [(Int, DecimalRaw i)]

-- | Allocate a <tt>DecimalRaw</tt> 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:
--   
--   <pre>
--   let result = allocate d parts
--   in all (== d / sum parts) $ zipWith (/) result parts
--   </pre>
allocate :: Integral i => DecimalRaw i -> [Integer] -> [DecimalRaw i]

-- | Try to convert Rational to Decimal with absolute precision return
--   string with fail description if not converted
eitherFromRational :: Integral i => Rational -> Either String (DecimalRaw i)

-- | Reduce the exponent of the decimal numer to the minimal posible value
normalizeDecimal :: Integral i => (DecimalRaw i) -> (DecimalRaw i)
instance Typeable1 DecimalRaw
instance Integral i => RealFrac (DecimalRaw i)
instance Integral i => Fractional (DecimalRaw i)
instance Integral i => Real (DecimalRaw i)
instance Integral i => Num (DecimalRaw i)
instance Integral i => Ord (DecimalRaw i)
instance Integral i => Eq (DecimalRaw i)
instance (Integral i, Read i) => Read (DecimalRaw i)
instance (Integral i, Show i) => Show (DecimalRaw i)
instance (Integral i, NFData i) => NFData (DecimalRaw i)