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


-- | An implementation of Mike Cowlishaw's
--   General Decimal Arithmetic Specification
--   
--   This package provides an implementation of the General Decimal
--   Arithmetic Specification by Mike Cowlishaw.
--   
--   For details, see: <a>http://speleotrove.com/decimal/</a>
@package decimal-arithmetic
@version 0.1.0.0


-- | Eventually most or all of the arithmetic operations described in the
--   <i>General Decimal Arithmetic Specification</i> will be provided here.
--   For now, the operations are mostly limited to those exposed through
--   various class methods.
--   
--   It is not usually necessary to import this module.
module Numeric.Decimal.Operation

-- | If the operand is negative, the result is the same as using the
--   <a>minus</a> operation on the operand. Otherwise, the result is the
--   same as using the <a>plus</a> operation on the operand.
abs :: (Precision p, Rounding r) => Number p r -> Number p r

-- | Add two operands.
add :: (Precision p, Rounding r) => Number p r -> Number p r -> Number p r

-- | Subtract the second operand from the first.
subtract :: (Precision p, Rounding r) => Number p r -> Number p r -> Number p r

-- | Multiply two operands.
multiply :: (Precision p, Rounding r) => Number p r -> Number p r -> Number p r

-- | Divide the first dividend operand by the second divisor using long
--   division.
divide :: (FinitePrecision p, Rounding r) => Number p r -> Number p r -> Number p r

-- | Unary plus
plus :: (Precision p, Rounding r) => Number p r -> Number p r

-- | Unary minus (negation)
minus :: (Precision p, Rounding r) => Number p r -> Number p r

-- | Compare the values of two operands numerically, returning <tt>-1</tt>
--   if the first is less than the second, <tt>0</tt> if they are equal, or
--   <tt>1</tt> if the first is greater than the second.
compare :: (Precision p, Rounding r) => Number p r -> Number p r -> Number p r


-- | The functions in this module implement conversions between
--   <a>Number</a> and <a>String</a> as described in the <i>General Decimal
--   Arithmetic Specification</i>.
--   
--   Because these functions are also used to implement <a>Show</a> and
--   <a>Read</a> class methods, it is not usually necessary to import this
--   module except to use the <a>toEngineeringString</a> function.
module Numeric.Decimal.Conversion

-- | Convert a number to a string, using scientific notation if an exponent
--   is needed.
toScientificString :: Number p r -> ShowS

-- | Convert a number to a string, using engineering notation if an
--   exponent is needed.
toEngineeringString :: Number p r -> ShowS

-- | Convert a string to a number, as defined by its abstract
--   representation. The string is expected to conform to the numeric
--   string syntax described here.
toNumber :: (Precision p, Rounding r) => ReadP (Number p r)


-- | This module provides a general-purpose <a>Number</a> 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
--   <a>General Decimal Arithmetic Specification</a> 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 <a>Float</a> and <a>Double</a>,
--   the <a>Number</a> type can represent and perform arithmetic with
--   decimal numbers exactly. Internally, a <a>Number</a> is represented
--   with an integral coefficient and base-10 exponent.
--   
--   The <a>Number</a> type supports lossless conversion to and from a
--   string representation via the <a>Show</a> and <a>Read</a> 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.
module Numeric.Decimal

-- | A decimal floating point number with selectable precision and rounding
--   algorithm
data Number p r

-- | A basic decimal floating point number with 9 digits of precision,
--   rounding half up
type BasicDecimal = Number P9 RoundHalfUp

-- | A decimal floating point number with selectable precision, rounding
--   half even
type ExtendedDecimal p = Number p RoundHalfEven

-- | A decimal floating point number with infinite precision
type GeneralDecimal = ExtendedDecimal PInfinite

-- | Precision indicates the maximum number of significant digits a number
--   may have.
class Precision p

-- | Return the precision of the argument, or <a>Nothing</a> if the
--   precision is infinite.
precision :: Precision p => p -> Maybe Int

-- | A subclass of precisions which are finite
class Precision p => FinitePrecision p

-- | A precision of 1 significant digit
data P1

-- | A precision of 2 significant digits
type P2 = PTimes2 P1

-- | A precision of 3 significant digits
type P3 = PPlus1 P2

-- | Et cetera
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

-- | A precision of (<tt>p</tt> + 1) significant digits
data PPlus1 p

-- | A precision of (<tt>p</tt> × 2) significant digits
data PTimes2 p

-- | A precision of unlimited significant digits
data PInfinite

-- | A rounding algorithm to use when the result of an arithmetic operation
--   exceeds the precision of the result type
class Rounding r where isRoundFloor _ = False

-- | 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.
data RoundHalfUp

-- | 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.
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 or exactly half, the value is rounded
--   down.
data RoundHalfDown

-- | Round toward +∞
data RoundCeiling

-- | Round toward −∞
data RoundFloor

-- | Round away from 0
data RoundUp

-- | Round zero or five away from 0
data Round05Up

-- | Round toward 0 (truncate)
data RoundDown

-- | Cast a <a>Number</a> to another precision and/or rounding algorithm,
--   immediately rounding if necessary to the new precision using the new
--   algorithm.
cast :: (Precision p, Rounding r) => Number a b -> Number p r