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


-- | An implementation of the 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.4.0.0


-- | The functions in this module implement conversions between
--   <a>Decimal</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 :: Decimal p r -> ShowS

-- | Convert a number to a string, using engineering notation if an
--   exponent is needed.
toEngineeringString :: Decimal 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 :: ReadP (Decimal PInfinite r)


-- | It is not usually necessary to import this module unless you want to
--   use the arithmetic operations from <a>Numeric.Decimal.Operation</a> or
--   you need precise control over the handling of exceptional conditions
--   in an arithmetic computation.
module Numeric.Decimal.Arithmetic

-- | A context for decimal arithmetic, carrying signal flags, trap enabler
--   state, and a trap handler, parameterized by precision <tt>p</tt> and
--   rounding algorithm <tt>r</tt>
data Context p r

-- | Return a new context with all signal flags cleared and all traps
--   disabled.
newContext :: Context p r

-- | The current signal flags of the context
flags :: Context p r -> Signals

-- | Return the precision of the arithmetic context (or <a>Nothing</a> if
--   the precision is infinite).
getPrecision :: Precision p => Arith p r (Maybe Int)

-- | Return the rounding algorithm of the arithmetic context.
getRounding :: Rounding r => Arith p r RoundingAlgorithm

-- | A value representation of a rounding algorithm (cf. <a>Rounding</a>).
data RoundingAlgorithm
RoundDown :: RoundingAlgorithm
RoundHalfUp :: RoundingAlgorithm
RoundHalfEven :: RoundingAlgorithm
RoundCeiling :: RoundingAlgorithm
RoundFloor :: RoundingAlgorithm
RoundHalfDown :: RoundingAlgorithm
RoundUp :: RoundingAlgorithm
Round05Up :: RoundingAlgorithm

-- | Return a new context with all signal flags cleared, all traps enabled
--   except for <a>Inexact</a>, <a>Rounded</a>, and <a>Subnormal</a>, using
--   a precision of 9 significant decimal digits, and rounding half up.
--   Trapped signals simply call <a>throwError</a> with the corresponding
--   <a>Exception</a>, and can be caught using <a>catchError</a>.
basicDefaultContext :: Context P9 RoundHalfUp

-- | Return a new context with all signal flags cleared, all traps disabled
--   (IEEE 854 §7), using selectable precision (the IEEE 754 smallest and
--   basic formats correspond to precisions <a>P7</a>, <a>P16</a>, or
--   <a>P34</a>), and rounding half even (IEEE 754 §4.3.3).
extendedDefaultContext :: Context p RoundHalfEven

-- | A decimal arithmetic monad parameterized by the precision <tt>p</tt>
--   and rounding algorithm <tt>r</tt>
data Arith p r a

-- | Evaluate an arithmetic computation in the given context and return the
--   final value (or exception) and resulting context.
runArith :: Arith p r a -> Context p r -> (Either (Exception p r) a, Context p r)

-- | Evaluate an arithmetic computation in the given context and return the
--   final value or exception, discarding the resulting context.
evalArith :: Arith p r a -> Context p r -> Either (Exception p r) a

-- | Perform a subcomputation using a different precision and/or rounding
--   algorithm. The subcomputation is evaluated within a new context with
--   all flags cleared and all traps disabled. Any flags set in the context
--   of the subcomputation are ignored, but if an exception is returned it
--   will be re-raised within the current context.
subArith :: Arith a b (Decimal a b) -> Arith p r (Decimal a b)

-- | A representation of an exceptional condition
data Exception p r

-- | The signal raised by the exceptional condition
exceptionSignal :: Exception p r -> Signal

-- | The defined result for the exceptional condition
exceptionResult :: Exception p r -> Decimal p r
data Signal

-- | Raised when the exponent of a result has been altered or constrained
--   in order to fit the constraints of a specific concrete representation
Clamped :: Signal

-- | Raised when a non-zero dividend is divided by zero
DivisionByZero :: Signal

-- | Raised when a result is not exact (one or more non-zero coefficient
--   digits were discarded during rounding)
Inexact :: Signal

-- | Raised when a result would be undefined or impossible
InvalidOperation :: Signal

-- | Raised when the exponent of a result is too large to be represented
Overflow :: Signal

-- | Raised when a result has been rounded (that is, some zero or non-zero
--   coefficient digits were discarded)
Rounded :: Signal

-- | Raised when a result is subnormal (its adjusted exponent is less than
--   E<i>min</i>), before any rounding
Subnormal :: Signal

-- | Raised when a result is both subnormal and inexact
Underflow :: Signal

-- | A group of signals can be manipulated as a set.
data Signals

-- | Create a set of signals from a singleton.
signal :: Signal -> Signals

-- | Create a set of signals from a list.
signals :: [Signal] -> Signals

-- | A set containing every signal
allSignals :: Signals

-- | Determine whether a signal is a member of a set.
signalMember :: Signal -> Signals -> Bool

-- | Set the given signal flag in the context of the current arithmetic
--   computation, and call the trap handler if the trap for this signal is
--   currently enabled.
raiseSignal :: Signal -> Decimal p r -> Arith p r (Decimal p r)

-- | Clear the given signal flags from the context of the current
--   arithmetic computation.
clearFlags :: Signals -> Arith p r ()

-- | A trap handler function may return a substitute result for the
--   operation that caused the exceptional condition, or it may call
--   <a>throwError</a> to pass control to an enclosing <a>catchError</a>
--   handler (or abort the arithmetic computation).
type TrapHandler p r = Exception p r -> Arith p r (Decimal p r)

-- | Evaluate an arithmetic computation within a modified context that
--   enables the given signals to be trapped by the given handler. The
--   previous trap handler (and enabler state) will be restored during any
--   trap, as well as upon completion. Any existing trap handlers for
--   signals not mentioned remain in effect.
trap :: Signals -> TrapHandler p r -> Arith p r a -> Arith p r a
instance GHC.Show.Show (Numeric.Decimal.Arithmetic.Exception p r)
instance GHC.Show.Show Numeric.Decimal.Arithmetic.Signal
instance GHC.Enum.Bounded Numeric.Decimal.Arithmetic.Signal
instance GHC.Enum.Enum Numeric.Decimal.Arithmetic.Signal
instance GHC.Classes.Eq Numeric.Decimal.Arithmetic.Signal
instance GHC.Classes.Eq Numeric.Decimal.Arithmetic.Signals
instance GHC.Base.Functor (Numeric.Decimal.Arithmetic.Arith p r)
instance GHC.Base.Applicative (Numeric.Decimal.Arithmetic.Arith p r)
instance GHC.Base.Monad (Numeric.Decimal.Arithmetic.Arith p r)
instance Control.Monad.Error.Class.MonadError (Numeric.Decimal.Arithmetic.Exception p r) (Numeric.Decimal.Arithmetic.Arith p r)
instance Control.Monad.State.Class.MonadState (Numeric.Decimal.Arithmetic.Context p r) (Numeric.Decimal.Arithmetic.Arith p r)
instance GHC.Show.Show Numeric.Decimal.Arithmetic.Signals
instance GHC.Base.Monoid Numeric.Decimal.Arithmetic.Signals


-- | The operations described in the <i>General Decimal Arithmetic
--   Specification</i> are provided here.
--   
--   It is suggested to import this module qualified to avoid
--   <a>Prelude</a> name clashes:
--   
--   <pre>
--   import qualified Numeric.Decimal.Operation as Op
--   </pre>
--   
--   Note that it is not usually necessary to import this module unless you
--   want to use operations unavailable through class methods, or you need
--   precise control over the handling of exceptional conditions. (See also
--   <a>Numeric.Decimal.Arithmetic</a>.)
module Numeric.Decimal.Operation

-- | <a>abs</a> takes one operand. 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.
--   
--   Note that the result of this operation is affected by context and may
--   set <i>flags</i>. The <a>copyAbs</a> operation may be used if this is
--   not desired.
abs :: (Precision p, Rounding r) => Decimal a b -> Arith p r (Decimal p r)

-- | <a>add</a> takes two operands. If either operand is a <i>special
--   value</i> then the general rules apply.
--   
--   Otherwise, the operands are added.
--   
--   The result is then rounded to <i>precision</i> digits if necessary,
--   counting from the most significant digit of the result.
add :: (Precision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>subtract</a> takes two operands. If either operand is a <i>special
--   value</i> then the general rules apply.
--   
--   Otherwise, the operands are added after inverting the <i>sign</i> used
--   for the second operand.
--   
--   The result is then rounded to <i>precision</i> digits if necessary,
--   counting from the most significant digit of the result.
subtract :: (Precision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>compare</a> takes two operands and compares their values
--   numerically. If either operand is a <i>special value</i> then the
--   general rules apply. No flags are set unless an operand is a signaling
--   NaN.
--   
--   Otherwise, the operands are compared, 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) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>compareSignal</a> takes two operands and compares their values
--   numerically. This operation is identical to <a>compare</a>, except
--   that if neither operand is a signaling NaN then any quiet NaN operand
--   is treated as though it were a signaling NaN. (That is, all NaNs
--   signal, with signaling NaNs taking precedence over quiet NaNs.)
compareSignal :: (Precision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>divide</a> takes two operands. If either operand is a <i>special
--   value</i> then the general rules apply.
--   
--   Otherwise, if the divisor is zero then either the Division undefined
--   condition is raised (if the dividend is zero) and the result is NaN,
--   or the Division by zero condition is raised and the result is an
--   Infinity with a sign which is the exclusive or of the signs of the
--   operands.
--   
--   Otherwise, a “long division” is effected.
--   
--   The result is then rounded to <i>precision</i> digits, if necessary,
--   according to the <i>rounding</i> algorithm and taking into account the
--   remainder from the division.
divide :: (FinitePrecision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>exp</a> takes one operand. If the operand is a NaN then the general
--   rules for special values apply.
--   
--   Otherwise, the result is <i>e</i> raised to the power of the operand,
--   with the following cases:
--   
--   <ul>
--   <li>If the operand is −Infinity, the result is 0 and exact.</li>
--   <li>If the operand is a zero, the result is 1 and exact.</li>
--   <li>If the operand is +Infinity, the result is +Infinity and
--   exact.</li>
--   <li>Otherwise the result is inexact and will be rounded using the
--   <i>round-half-even</i> algorithm. The coefficient will have exactly
--   <i>precision</i> digits (unless the result is subnormal). These
--   inexact results should be correctly rounded, but may be up to 1 ulp
--   (unit in last place) in error.</li>
--   </ul>
exp :: FinitePrecision p => Decimal a b -> Arith p r (Decimal p RoundHalfEven)

-- | <a>fusedMultiplyAdd</a> takes three operands; the first two are
--   multiplied together, using <a>multiply</a>, with sufficient precision
--   and exponent range that the result is exact and unrounded. No
--   <i>flags</i> are set by the multiplication unless one of the first two
--   operands is a signaling NaN or one is a zero and the other is an
--   infinity.
--   
--   Unless the multiplication failed, the third operand is then added to
--   the result of that multiplication, using <a>add</a>, under the current
--   context.
--   
--   In other words, <tt>fusedMultiplyAdd x y z</tt> delivers a result
--   which is <tt>(x × y) + z</tt> with only the one, final, rounding.
fusedMultiplyAdd :: (Precision p, Rounding r) => Decimal a b -> Decimal c d -> Decimal e f -> Arith p r (Decimal p r)

-- | <a>ln</a> takes one operand. If the operand is a NaN then the general
--   rules for special values apply.
--   
--   Otherwise, the operand must be a zero or positive, and the result is
--   the natural (base <i>e</i>) logarithm of the operand, with the
--   following cases:
--   
--   <ul>
--   <li>If the operand is a zero, the result is −Infinity and exact.</li>
--   <li>If the operand is +Infinity, the result is +Infinity and
--   exact.</li>
--   <li>If the operand equals one, the result is 0 and exact.</li>
--   <li>Otherwise the result is inexact and will be rounded using the
--   <i>round-half-even</i> algorithm. The coefficient will have exactly
--   <i>precision</i> digits (unless the result is subnormal). These
--   inexact results should be correctly rounded, but may be up to 1 ulp
--   (unit in last place) in error.</li>
--   </ul>
ln :: FinitePrecision p => Decimal a b -> Arith p r (Decimal p RoundHalfEven)

-- | <a>log10</a> takes one operand. If the operand is a NaN then the
--   general rules for special values apply.
--   
--   Otherwise, the operand must be a zero or positive, and the result is
--   the base 10 logarithm of the operand, with the following cases:
--   
--   <ul>
--   <li>If the operand is a zero, the result is −Infinity and exact.</li>
--   <li>If the operand is +Infinity, the result is +Infinity and
--   exact.</li>
--   <li>If the operand equals an integral power of ten (including 10^0 and
--   negative powers) and there is sufficient <i>precision</i> to hold the
--   integral part of the result, the result is an integer (with an
--   exponent of 0) and exact.</li>
--   <li>Otherwise the result is inexact and will be rounded using the
--   <i>round-half-even</i> algorithm. The coefficient will have exactly
--   <i>precision</i> digits (unless the result is subnormal). These
--   inexact results should be correctly rounded, but may be up to 1 ulp
--   (unit in last place) in error.</li>
--   </ul>
log10 :: FinitePrecision p => Decimal a b -> Arith p r (Decimal p RoundHalfEven)

-- | <a>max</a> takes two operands, compares their values numerically, and
--   returns the maximum. If either operand is a NaN then the general rules
--   apply, unless one is a quiet NaN and the other is numeric, in which
--   case the numeric operand is returned.
max :: (Precision p, Rounding r) => Decimal a b -> Decimal a b -> Arith p r (Decimal a b)

-- | <a>maxMagnitude</a> takes two operands and compares their values
--   numerically with their <i>sign</i> ignored and assumed to be 0.
--   
--   If, without signs, the first operand is the larger then the original
--   first operand is returned (that is, with the original sign). If,
--   without signs, the second operand is the larger then the original
--   second operand is returned. Otherwise the result is the same as from
--   the <a>max</a> operation.
maxMagnitude :: (Precision p, Rounding r) => Decimal a b -> Decimal a b -> Arith p r (Decimal a b)

-- | <a>min</a> takes two operands, compares their values numerically, and
--   returns the minimum. If either operand is a NaN then the general rules
--   apply, unless one is a quiet NaN and the other is numeric, in which
--   case the numeric operand is returned.
min :: (Precision p, Rounding r) => Decimal a b -> Decimal a b -> Arith p r (Decimal a b)

-- | <a>minMagnitude</a> takes two operands and compares their values
--   numerically with their <i>sign</i> ignored and assumed to be 0.
--   
--   If, without signs, the first operand is the smaller then the original
--   first operand is returned (that is, with the original sign). If,
--   without signs, the second operand is the smaller then the original
--   second operand is returned. Otherwise the result is the same as from
--   the <a>min</a> operation.
minMagnitude :: (Precision p, Rounding r) => Decimal a b -> Decimal a b -> Arith p r (Decimal a b)

-- | <a>minus</a> takes one operand, and corresponds to the prefix minus
--   operator in programming languages.
--   
--   Note that the result of this operation is affected by context and may
--   set <i>flags</i>. The <a>copyNegate</a> operation may be used instead
--   of <a>minus</a> if this is not desired.
minus :: (Precision p, Rounding r) => Decimal a b -> Arith p r (Decimal p r)

-- | <a>plus</a> takes one operand, and corresponds to the prefix plus
--   operator in programming languages.
--   
--   Note that the result of this operation is affected by context and may
--   set <i>flags</i>.
plus :: (Precision p, Rounding r) => Decimal a b -> Arith p r (Decimal p r)

-- | <a>multiply</a> takes two operands. If either operand is a <i>special
--   value</i> then the general rules apply. Otherwise, the operands are
--   multiplied together (“long multiplication”), resulting in a number
--   which may be as long as the sum of the lengths of the two operands.
--   
--   The result is then rounded to <i>precision</i> digits if necessary,
--   counting from the most significant digit of the result.
multiply :: (Precision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>power</a> takes two operands, and raises a number (the left-hand
--   operand) to a power (the right-hand operand). If either operand is a
--   <i>special value</i> then the general rules apply, except in certain
--   cases.
power :: (FinitePrecision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>quantize</a> takes two operands. If either operand is a <i>special
--   value</i> then the general rules apply, except that if either operand
--   is infinite and the other is finite an Invalid operation condition is
--   raised and the result is NaN, or if both are infinite then the result
--   is the first operand.
--   
--   Otherwise (both operands are finite), <a>quantize</a> returns the
--   number which is equal in value (except for any rounding) and sign to
--   the first (left-hand) operand and which has an <i>exponent</i> set to
--   be equal to the exponent of the second (right-hand) operand.
--   
--   The <i>coefficient</i> of the result is derived from that of the
--   left-hand operand. It may be rounded using the current <i>rounding</i>
--   setting (if the <i>exponent</i> is being increased), multiplied by a
--   positive power of ten (if the <i>exponent</i> is being decreased), or
--   is unchanged (if the <i>exponent</i> is already equal to that of the
--   right-hand operand).
--   
--   Unlike other operations, if the length of the <i>coefficient</i> after
--   the quantize operation would be greater than <i>precision</i> then an
--   Invalid operation condition is raised. This guarantees that, unless
--   there is an error condition, the <i>exponent</i> of the result of a
--   quantize is always equal to that of the right-hand operand.
--   
--   Also unlike other operations, quantize will never raise Underflow,
--   even if the result is subnormal and inexact.
quantize :: (Precision p, Rounding r) => Decimal p r -> Decimal a b -> Arith p r (Decimal p r)

-- | <a>reduce</a> takes one operand. It has the same semantics as the
--   <a>plus</a> operation, except that if the final result is finite it is
--   reduced to its simplest form, with all trailing zeros removed and its
--   sign preserved.
reduce :: (Precision p, Rounding r) => Decimal a b -> Arith p r (Decimal p r)

-- | <a>squareRoot</a> takes one operand. If the operand is a <i>special
--   value</i> then the general rules apply.
--   
--   Otherwise, the ideal exponent of the result is defined to be half the
--   exponent of the operand (rounded to an integer, towards −Infinity, if
--   necessary) and then:
--   
--   If the operand is less than zero an Invalid operation condition is
--   raised.
--   
--   If the operand is greater than zero, the result is the square root of
--   the operand. If no rounding is necessary (the exact result requires
--   <i>precision</i> digits or fewer) then the coefficient and exponent
--   giving the correct value and with the exponent closest to the ideal
--   exponent is used. If the result must be inexact, it is rounded using
--   the <i>round-half-even</i> algorithm and the coefficient will have
--   exactly <i>precision</i> digits (unless the result is subnormal), and
--   the exponent will be set to maintain the correct value.
--   
--   Otherwise (the operand is equal to zero), the result will be the zero
--   with the same sign as the operand and with the ideal exponent.
squareRoot :: FinitePrecision p => Decimal a b -> Arith p r (Decimal p RoundHalfEven)

-- | <a>and</a> is a logical operation which takes two logical operands.
--   The result is the digit-wise <i>and</i> of the two operands; each
--   digit of the result is the logical and of the corresponding digits of
--   the operands, aligned at the least-significant digit. A result digit
--   is 1 if both of the corresponding operand digits are 1; otherwise it
--   is 0.
and :: Precision p => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>canonical</a> takes one operand. The result has the same value as
--   the operand but always uses a <i>canonical</i> encoding. The
--   definition of <i>canonical</i> is implementation-defined; if more than
--   one internal encoding for a given NaN, Infinity, or finite number is
--   possible then one “preferred” encoding is deemed canonical. This
--   operation then returns the value using that preferred encoding.
--   
--   If all possible operands have just one internal encoding each, then
--   <a>canonical</a> always returns the operand unchanged (that is, it has
--   the same effect as <a>copy</a>). This operation is unaffected by
--   context and is quiet — no <i>flags</i> are changed in the context.
canonical :: Decimal a b -> Arith p r (Decimal a b)

-- | <a>class_</a> takes one operand. The result is an indication of the
--   <i>class</i> of the operand, where the class is one of ten
--   possibilities, corresponding to one of the strings <tt>"sNaN"</tt>
--   (signaling NaN), <tt>"NaN"</tt> (quiet NaN), <tt>"-Infinity"</tt>
--   (negative infinity), <tt>"-Normal"</tt> (negative normal finite
--   number), <tt>"-Subnormal"</tt> (negative subnormal finite number),
--   <tt>"-Zero"</tt> (negative zero), <tt>"+Zero"</tt> (non-negative
--   zero), <tt>"+Subnormal"</tt> (positive subnormal finite number),
--   <tt>"+Normal"</tt> (positive normal finite number), or
--   <tt>"+Infinity"</tt> (positive infinity). This operation is quiet; no
--   <i>flags</i> are changed in the context.
--   
--   Note that unlike the special values in the model, the sign of any NaN
--   is ignored in the classification, as required by IEEE 754.
class_ :: Precision a => Decimal a b -> Arith p r Class
data Class

-- | Number (finite or infinite)
NumberClass :: Sign -> NumberClass -> Class

-- | Not a number (quiet or signaling)
NaNClass :: NaNClass -> Class
data Sign

-- | Positive or non-negative
Pos :: Sign

-- | Negative
Neg :: Sign
data NumberClass

-- | Zero
ZeroClass :: NumberClass

-- | Subnormal finite number
SubnormalClass :: NumberClass

-- | Normal finite number
NormalClass :: NumberClass

-- | Infinity
InfinityClass :: NumberClass
data NaNClass

-- | Not a number (quiet)
QNaNClass :: NaNClass

-- | Not a number (signaling)
SNaNClass :: NaNClass

-- | <a>copy</a> takes one operand. The result is a copy of the operand.
--   This operation is unaffected by context and is quiet — no <i>flags</i>
--   are changed in the context.
copy :: Decimal a b -> Arith p r (Decimal a b)

-- | <a>copyAbs</a> takes one operand. The result is a copy of the operand
--   with the <i>sign</i> set to 0. Unlike the <a>abs</a> operation, this
--   operation is unaffected by context and is quiet — no <i>flags</i> are
--   changed in the context.
copyAbs :: Decimal a b -> Arith p r (Decimal a b)

-- | <a>copyNegate</a> takes one operand. The result is a copy of the
--   operand with the <i>sign</i> inverted (a <i>sign</i> of 0 becomes 1
--   and vice versa). Unlike the <a>minus</a> operation, this operation is
--   unaffected by context and is quiet — no <i>flags</i> are changed in
--   the context.
copyNegate :: Decimal a b -> Arith p r (Decimal a b)

-- | <a>copySign</a> takes two operands. The result is a copy of the first
--   operand with the <i>sign</i> set to be the same as the <i>sign</i> of
--   the second operand. This operation is unaffected by context and is
--   quiet — no <i>flags</i> are changed in the context.
copySign :: Decimal a b -> Decimal c d -> Arith p r (Decimal a b)

-- | <a>invert</a> is a logical operation which takes one logical operand.
--   The result is the digit-wise <i>inversion</i> of the operand; each
--   digit of the result is the inverse of the corresponding digit of the
--   operand. A result digit is 1 if the corresponding operand digit is 0;
--   otherwise it is 0.
invert :: FinitePrecision p => Decimal a b -> Arith p r (Decimal p r)

-- | <a>isCanonical</a> takes one operand. The result is 1 if the operand
--   is <i>canonical</i>; otherwise it is 0. The definition of
--   <i>canonical</i> is implementation-defined; if more than one internal
--   encoding for a given NaN, Infinity, or finite number is possible then
--   one “preferred” encoding is deemed canonical. This operation then
--   tests whether the internal encoding is that preferred encoding.
--   
--   If all possible operands have just one internal encoding each, then
--   <a>isCanonical</a> always returns 1. This operation is unaffected by
--   context and is quiet — no <i>flags</i> are changed in the context.
isCanonical :: Decimal a b -> Arith p r Bool

-- | <a>isFinite</a> takes one operand. The result is 1 if the operand is
--   neither infinite nor a NaN (that is, it is a normal number, a
--   subnormal number, or a zero); otherwise it is 0. This operation is
--   unaffected by context and is quiet — no <i>flags</i> are changed in
--   the context.
isFinite :: Decimal a b -> Arith p r Bool

-- | <a>isInfinite</a> takes one operand. The result is 1 if the operand is
--   an Infinity; otherwise it is 0. This operation is unaffected by
--   context and is quiet — no <i>flags</i> are changed in the context.
isInfinite :: Decimal a b -> Arith p r Bool

-- | <a>isNaN</a> takes one operand. The result is 1 if the operand is a
--   NaN (quiet or signaling); otherwise it is 0. This operation is
--   unaffected by context and is quiet — no <i>flags</i> are changed in
--   the context.
isNaN :: Decimal a b -> Arith p r Bool

-- | <a>isNormal</a> takes one operand. The result is 1 if the operand is a
--   positive or negative <i>normal number</i>; otherwise it is 0. This
--   operation is quiet; no <i>flags</i> are changed in the context.
isNormal :: Precision a => Decimal a b -> Arith p r Bool

-- | <a>isQNaN</a> takes one operand. The result is 1 if the operand is a
--   quiet NaN; otherwise it is 0. This operation is unaffected by context
--   and is quiet — no <i>flags</i> are changed in the context.
isQNaN :: Decimal a b -> Arith p r Bool

-- | <a>isSigned</a> takes one operand. The result is 1 if the <i>sign</i>
--   of the operand is 1; otherwise it is 0. This operation is unaffected
--   by context and is quiet — no <i>flags</i> are changed in the context.
isSigned :: Decimal a b -> Arith p r Bool

-- | <a>isSNaN</a> takes one operand. The result is 1 if the operand is a
--   signaling NaN; otherwise it is 0. This operation is unaffected by
--   context and is quiet — no <i>flags</i> are changed in the context.
isSNaN :: Decimal a b -> Arith p r Bool

-- | <a>isSubnormal</a> takes one operand. The result is 1 if the operand
--   is a positive or negative <i>subnormal number</i>; otherwise it is 0.
--   This operation is quiet; no <i>flags</i> are changed in the context.
isSubnormal :: Precision a => Decimal a b -> Arith p r Bool

-- | <a>isZero</a> takes one operand. The result is 1 if the operand is a
--   zero; otherwise it is 0. This operation is unaffected by context and
--   is quiet — no <i>flags</i> are changed in the context.
isZero :: Decimal a b -> Arith p r Bool

-- | <a>logb</a> takes one operand. If the operand is a NaN then the
--   general arithmetic rules apply. If the operand is infinite then
--   +Infinity is returned. If the operand is a zero, then −Infinity is
--   returned and the Division by zero exceptional condition is raised.
--   
--   Otherwise, the result is the integer which is the exponent of the
--   magnitude of the most significant digit of the operand (as though the
--   operand were truncated to a single digit while maintaining the value
--   of that digit and without limiting the resulting exponent). All
--   results are exact unless an integer result does not fit in the
--   available <i>precision</i>.
logb :: (Precision p, Rounding r) => Decimal a b -> Arith p r (Decimal p r)

-- | <a>or</a> is a logical operation which takes two logical operands. The
--   result is the digit-wise <i>inclusive or</i> of the two operands; each
--   digit of the result is the logical or of the corresponding digits of
--   the operands, aligned at the least-significant digit. A result digit
--   is 1 if either or both of the corresponding operand digits is 1;
--   otherwise it is 0.
or :: Precision p => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>radix</a> takes no operands. The result is the radix (base) in
--   which arithmetic is effected; for this specification the result will
--   have the value 10.
radix :: Precision p => Arith p r (Decimal p r)

-- | <a>rotate</a> takes two operands. The second operand must be an
--   integer (with an <i>exponent</i> of 0) in the range <i>−precision</i>
--   through <i>precision</i>. If the first operand is a NaN then the
--   general arithmetic rules apply, and if it is infinite then the result
--   is the Infinity unchanged.
--   
--   Otherwise (the first operand is finite) the result has the same
--   <i>sign</i> and <i>exponent</i> as the first operand, and a
--   <i>coefficient</i> which is a rotated copy of the digits in the
--   coefficient of the first operand. The number of places of rotation is
--   taken from the absolute value of the second operand, with the rotation
--   being to the left if the second operand is positive or to the right
--   otherwise.
--   
--   If the coefficient of the first operand has fewer than
--   <i>precision</i> digits, it is treated as though it were padded on the
--   left with zeros to length <i>precision</i> before the rotation.
--   Similarly, if the coefficient of the first operand has more than
--   <i>precision</i> digits, it is truncated on the left before use.
--   
--   The only <i>flag</i> that might be set is <i>invalid-operation</i>
--   (set if the first operand is an sNaN or the second is not valid).
--   
--   The <a>shift</a> operation can be used to shift rather than rotate a
--   coefficient.
rotate :: FinitePrecision p => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>sameQuantum</a> takes two operands, and returns 1 if the two
--   operands have the same <i>exponent</i> or 0 otherwise. The result is
--   never affected by either the sign or the coefficient of either
--   operand.
--   
--   If either operand is a <i>special value</i>, 1 is returned only if
--   both operands are NaNs or both are infinities.
--   
--   <a>sameQuantum</a> does not change any <i>flags</i> in the context.
sameQuantum :: Decimal a b -> Decimal c d -> Arith p r Bool

-- | <a>shift</a> takes two operands. The second operand must be an integer
--   (with an <i>exponent</i> of 0) in the range <i>−precision</i> through
--   <i>precision</i>. If the first operand is a NaN then the general
--   arithmetic rules apply, and if it is infinite then the result is the
--   Infinity unchanged.
--   
--   Otherwise (the first operand is finite) the result has the same
--   <i>sign</i> and <i>exponent</i> as the first operand, and a
--   <i>coefficient</i> which is a shifted copy of the digits in the
--   coefficient of the first operand. The number of places to shift is
--   taken from the absolute value of the second operand, with the shift
--   being to the left if the second operand is positive or to the right
--   otherwise. Digits shifted into the coefficient are zeros.
--   
--   The only <i>flag</i> that might be set is <i>invalid-operation</i>
--   (set if the first operand is an sNaN or the second is not valid).
--   
--   The <a>rotate</a> operation can be used to rotate rather than shift a
--   coefficient.
shift :: Precision p => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

-- | <a>xor</a> is a logical operation which takes two logical operands.
--   The result is the digit-wise <i>exclusive or</i> of the two operands;
--   each digit of the result is the logical exclusive-or of the
--   corresponding digits of the operands, aligned at the least-significant
--   digit. A result digit is 1 if one of the corresponding operand digits
--   is 1 and the other is 0; otherwise it is 0.
xor :: Precision p => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)
instance GHC.Classes.Eq Numeric.Decimal.Operation.Class
instance GHC.Classes.Eq Numeric.Decimal.Operation.NaNClass
instance GHC.Classes.Eq Numeric.Decimal.Operation.NumberClass
instance GHC.Show.Show Numeric.Decimal.Operation.Class


-- | 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
--   <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>,
--   decimal number types can perform decimal arithmetic exactly.
--   Internally, decimal numbers are represented with an integral
--   coefficient and base-10 exponent.
--   
--   <pre>
--   <tt>&gt;&gt;&gt;</tt> <b>29.99 + 4.71 :: Double</b>
--   34.699999999999996
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 29.99 + 4.71 :: BasicDecimal
--   34.70
--   </pre>
--   
--   <pre>
--   <tt>&gt;&gt;&gt;</tt> <b>0.1 + 0.2 == (0.3 :: Double)</b>
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 0.1 + 0.2 == (0.3 :: BasicDecimal)
--   True
--   </pre>
--   
--   Decimal numbers support lossless conversion to and from a string
--   representation via <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 Decimal p r

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

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

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

-- | Precision indicates the maximum number of significant decimal 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 that 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

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

-- | 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).
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 result coefficient should
--   be incremented by 1 (rounded up). Otherwise (the discarded digits are
--   0.5 or less) the discarded digits are ignored.
data RoundHalfDown

-- | (Round toward +∞.) If all of the discarded digits are zero or if the
--   <i>sign</i> is 1 the result is unchanged. Otherwise, the result
--   coefficient should be incremented by 1 (rounded up).
data RoundCeiling

-- | (Round toward −∞.) If all of the discarded digits are zero or if the
--   <i>sign</i> is 0 the result is unchanged. Otherwise, the sign is 1 and
--   the result coefficient should be incremented by 1.
data RoundFloor

-- | (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).
data RoundUp

-- | (Round zero or five away from 0.) The same as <a>RoundUp</a>, 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 <a>RoundDown</a>.
data Round05Up

-- | (Round toward 0; truncate.) The discarded digits are ignored; the
--   result is unchanged.
data RoundDown

-- | Cast a <a>Decimal</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) => Decimal a b -> Decimal p r

-- | If the argument is <a>False</a>, return a <a>Decimal</a> value zero;
--   if <a>True</a>, return the value one. This is basically an optimized
--   <tt>toEnum . fromEnum</tt> to support an all-decimal usage of the
--   operations from <a>Numeric.Decimal.Operation</a> that return a
--   <a>Bool</a>.
fromBool :: Bool -> Decimal p r