Numeric.Decimal.Operation

Eventually most or all of the arithmetic operations described in the General Decimal Arithmetic Specification will be provided here. For now, the operations are mostly limited to those exposed through various class methods.

It is suggested to import this module qualified to avoid Prelude name clashes:

import qualified Numeric.Decimal.Operation as Op

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.

Arithmetic operations

This section describes the arithmetic operations on, and some other functions of, numbers, including subnormal numbers, negative zeros, and special values (see also IEEE 754 §5 and §6).

abs :: (Precision p, Rounding r) => Decimal a b -> Arith p r (Decimal p r)

abs takes one operand. If the operand is negative, the result is the same as using the minus operation on the operand. Otherwise, the result is the same as using the plus operation on the operand.

Note that the result of this operation is affected by context and may set flags. The copyAbs operation may be used if this is not desired.

add :: (Precision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

add takes two operands. If either operand is a special value then the general rules apply.

Otherwise, the operands are added.

The result is then rounded to precision 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)

subtract takes two operands. If either operand is a special value then the general rules apply.

Otherwise, the operands are added after inverting the sign used for the second operand.

The result is then rounded to precision digits if necessary, counting from the most significant digit of the result.

compare :: (Precision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

compare takes two operands and compares their values numerically. If either operand is a special value then the general rules apply. No flags are set unless an operand is a signaling NaN.

Otherwise, the operands are compared, returning -1 if the first is less than the second, 0 if they are equal, or 1 if the first is greater than the second.

divide :: (FinitePrecision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

divide takes two operands. If either operand is a special value 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 precision digits, if necessary, according to the rounding algorithm and taking into account the remainder from the division.

max :: (Precision p, Rounding r) => Decimal a b -> Decimal a b -> Arith p r (Decimal a b)

max 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.

maxMagnitude :: (Precision p, Rounding r) => Decimal a b -> Decimal a b -> Arith p r (Decimal a b)

maxMagnitude takes two operands and compares their values numerically with their sign 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 max operation.

min :: (Precision p, Rounding r) => Decimal a b -> Decimal a b -> Arith p r (Decimal a b)

min 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.

minMagnitude :: (Precision p, Rounding r) => Decimal a b -> Decimal a b -> Arith p r (Decimal a b)

minMagnitude takes two operands and compares their values numerically with their sign 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 min operation.

minus :: (Precision p, Rounding r) => Decimal a b -> Arith p r (Decimal p r)

minus 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 flags. The copyNegate operation may be used instead of minus if this is not desired.

plus :: (Precision p, Rounding r) => Decimal a b -> Arith p r (Decimal p r)

plus 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 flags.

multiply :: (Precision p, Rounding r) => Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

multiply takes two operands. If either operand is a special value 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 precision digits if necessary, counting from the most significant digit of the result.

reduce :: (Precision p, Rounding r) => Decimal a b -> Arith p r (Decimal p r)

reduce takes one operand. It has the same semantics as the plus 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.

Miscellaneous operations

This section describes miscellaneous operations on decimal numbers, including non-numeric comparisons, sign and other manipulations, and logical operations.

canonical :: Decimal a b -> Arith p r (Decimal a b)

canonical takes one operand. The result has the same value as the operand but always uses a canonical encoding. The definition of canonical 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 canonical always returns the operand unchanged (that is, it has the same effect as copy). This operation is unaffected by context and is quiet – no flags are changed in the context.

class_ :: Precision a => Decimal a b -> Arith p r Class

class_ takes one operand. The result is an indication of the class of the operand, where the class is one of ten possibilities, corresponding to one of the strings "sNaN" (signaling NaN), "NaN" (quiet NaN), "-Infinity" (negative infinity), "-Normal" (negative normal finite number), "-Subnormal" (negative subnormal finite number), "-Zero" (negative zero), "+Zero" (non-negative zero), "+Subnormal" (positive subnormal finite number), "+Normal" (positive normal finite number), or "+Infinity" (positive infinity). This operation is quiet; no flags 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.

data Class

Constructors

Class Sign Subclass

Instances

Eq Class

Methods

(==) :: Class -> Class -> Bool

(/=) :: Class -> Class -> Bool

Show Class

Methods

showsPrec :: Int -> Class -> ShowS

show :: Class -> String

showList :: [Class] -> ShowS

data Sign

Constructors

Pos

Positive or non-negative

Neg

Negative

Instances

Enum Sign

Methods

succ :: Sign -> Sign

pred :: Sign -> Sign

toEnum :: Int -> Sign

fromEnum :: Sign -> Int

enumFrom :: Sign -> [Sign]

enumFromThen :: Sign -> Sign -> [Sign]

enumFromTo :: Sign -> Sign -> [Sign]

enumFromThenTo :: Sign -> Sign -> Sign -> [Sign]

Eq Sign

Methods

(==) :: Sign -> Sign -> Bool

(/=) :: Sign -> Sign -> Bool

data Subclass

Constructors

ZeroClass

Zero

NormalClass

Normal finite number

SubnormalClass

Subnormal finite number

InfinityClass

Infinity

NaNClass

Not a number (quiet or signaling)

Instances

Eq Subclass

Methods

(==) :: Subclass -> Subclass -> Bool

(/=) :: Subclass -> Subclass -> Bool

copy :: Decimal a b -> Arith p r (Decimal a b)

copy takes one operand. The result is a copy of the operand. This operation is unaffected by context and is quiet – no flags are changed in the context.

copyAbs :: Decimal a b -> Arith p r (Decimal a b)

copyAbs takes one operand. The result is a copy of the operand with the sign set to 0. Unlike the abs operation, this operation is unaffected by context and is quiet – no flags are changed in the context.

copyNegate :: Decimal a b -> Arith p r (Decimal a b)

copyNegate takes one operand. The result is a copy of the operand with the sign inverted (a sign of 0 becomes 1 and vice versa). Unlike the minus operation, this operation is unaffected by context and is quiet – no flags are changed in the context.

copySign :: Decimal a b -> Decimal c d -> Arith p r (Decimal a b)

copySign takes two operands. The result is a copy of the first operand with the sign set to be the same as the sign of the second operand. This operation is unaffected by context and is quiet – no flags are changed in the context.

isCanonical :: Decimal a b -> Arith p r (Decimal p r)

isCanonical takes one operand. The result is 1 if the operand is canonical; otherwise it is 0. The definition of canonical 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 isCanonical always returns 1. This operation is unaffected by context and is quiet – no flags are changed in the context.

isFinite :: Decimal a b -> Arith p r (Decimal p r)

isFinite 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 flags are changed in the context.

isInfinite :: Decimal a b -> Arith p r (Decimal p r)

isInfinite 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 flags are changed in the context.

isNaN :: Decimal a b -> Arith p r (Decimal p r)

isNaN 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 flags are changed in the context.

isNormal :: Precision a => Decimal a b -> Arith p r (Decimal p r)

isNormal takes one operand. The result is 1 if the operand is a positive or negative normal number; otherwise it is 0. This operation is quiet; no flags are changed in the context.

isQNaN :: Decimal a b -> Arith p r (Decimal p r)

isQNaN 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 flags are changed in the context.

isSigned :: Decimal a b -> Arith p r (Decimal p r)

isSigned takes one operand. The result is 1 if the sign of the operand is 1; otherwise it is 0. This operation is unaffected by context and is quiet – no flags are changed in the context.

isSNaN :: Decimal a b -> Arith p r (Decimal p r)

isSNaN 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 flags are changed in the context.

isSubnormal :: Precision a => Decimal a b -> Arith p r (Decimal p r)

isSubnormal takes one operand. The result is 1 if the operand is a positive or negative subnormal number; otherwise it is 0. This operation is quiet; no flags are changed in the context.

isZero :: Decimal a b -> Arith p r (Decimal p r)

isZero 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 flags are changed in the context.

radix :: Precision p => Arith p r (Decimal p r)

radix takes no operands. The result is the radix (base) in which arithmetic is effected; for this specification the result will have the value 10.

sameQuantum :: Decimal a b -> Decimal c d -> Arith p r (Decimal p r)

sameQuantum takes two operands, and returns 1 if the two operands have the same exponent or 0 otherwise. The result is never affected by either the sign or the coefficient of either operand.

If either operand is a special value, 1 is returned only if both operands are NaNs or both are infinities.

sameQuantum does not change any flags in the context.