-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Decimal floating point arithmetic -- -- deka provides decimal floating point arithmetic. It is based on -- mpdecimal, the C library used to provide support for the Decimal -- module in Python 3. -- -- You will need to install mpdecimal to use deka; otherwise your -- executables will not link. It is available at -- -- http://www.bytereef.org/mpdecimal/ -- -- mpdecimal has also been packaged for some Linux distributions, such as -- Debian (libmpdec-dev - available in Jessie and later) and Arch -- (mpdecimal). -- -- mpdecimal, in turn, implements the General Decimal Arithmetic -- Specification, which is available at -- -- http://speleotrove.com/decimal/ -- -- For more on deka, please see the Github home page at -- -- https://github.com/massysett/deka -- -- Tests are packaged separately in the deka-tests package. @package deka @version 0.6.0.2 -- | Documentation for Deka. -- -- At the moment, documentation is scattered about. Some of it is in the -- main README.md, which is in the source code tree and is viewable in -- Github at -- -- http://github.com/massysett/deka/blob/master/README.md -- -- Of course much of it is in the Haddock comments in the source code -- itself. -- -- There is also a module here, Deka.Docs.Examples. It is in -- literate Haskell and has many comments. Unfortunately Haddock does not -- play well with Literate Haskell. However, the style of the file would -- not play well with Haddock anyway so I'm not sure I would ever switch -- back to regular Haskell for that file. -- -- So if you link to the file from the Haddock docs, you will just get a -- blank page. Fortunately it is easily readable in Github: -- -- -- http://github.com/massysett/deka/blob/master/lib/Deka/Docs/Examples.hs module Deka.Docs module Deka.Context -- | A signed integer. Its size is platform dependent. type Signed = Int64 -- | The Ctx monad -- -- The General Decimal Arithmetic specification states that most -- computations occur within a context, which affects the manner -- in which computations are done (for instance, the context determines -- the rounding algorithm). The context also carries the flags that -- computations can set (for instance, a computation might set a flag to -- indicate that the result is rounded or inexact or was a division by -- zero.) The Ctx monad carries this context. data Ctx a -- | Indicates error conditions. This type serves two purposes: -- computations set flags to indicate errors, and flags indicate which -- errors you want to have raise a signal. See getStatus, -- setStatus, getTraps, and setTraps. -- -- Flag is an instance of Exception so that you can throw -- it if you want; however, none of the functions in the deka -- package throw. data Flag -- | A container of Flag. data Flags -- | A list of all possible Flag, in order. allFlag :: [Flag] -- | All possible Flag are set. fullFlags :: Flags -- | No Flag are set. emptyFlags :: Flags packFlags :: [Flag] -> Flags -- | Flags will always be unpacked in order. unpackFlags :: Flags -> [Flag] clamped :: Flag -- | A source string (for instance, in fromByteString) contained -- errors. conversionSyntax :: Flag -- | A non-zero dividend is divided by zero. Unlike 0/0, it has a -- defined result (a signed Infinity). divisionByZero :: Flag -- | Sometimes raised by divideInteger and remainder. divisionImpossible :: Flag -- | 0/0 is undefined. It sets this flag and returns a quiet NaN. divisionUndefined :: Flag fpuError :: Flag -- | One or more non-zero coefficient digits were discarded during -- rounding. inexact :: Flag -- | The Context for computations was invalid; this error should never -- occur because deka keeps you from setting an invalid context. invalidContext :: Flag -- | Raised on a variety of invalid operations, such as an attempt to use -- compareSignal on an operand that is an NaN. invalidOperation :: Flag mallocError :: Flag notImplemented :: Flag -- | The exponent of a result is too large to be represented. overflow :: Flag rounded :: Flag subnormal :: Flag -- | A result is both subnormal and inexact. underflow :: Flag -- | Gets all currently set traps. getTraps :: Ctx Flags -- | If you set a trap, a computation will immediately raise -- SIGFPE if the corresponding error arises. (Currently this -- behavior cannot be configured to do something else.) setTraps -- clears all existing traps and sets them to the new ones you specify. -- -- By setting a flag here, SIGFPE is raised if any subsequent -- computations raise the corresponding error condition. Setting a flag -- with this function or with setTrap never, by itself, causes -- SIGFPE to be raised; it is raised only by a subsequent computation. -- So, if you set a flag using this function or setTrap and the -- corresponding status flag is already set, SIGFPE will be raised only -- if a subsequent computation raises that error condition. setTraps :: Flags -> Ctx () -- | All currently set status flags. getStatus :: Ctx Flags -- | Sets status flags. All existing status flags are cleared and replaced -- with the ones you indicate here. setStatus :: Flags -> Ctx () -- | Sets the precision to be used for all operations. The result of an -- operation is rounded to this length if necessary. data Precision -- | Creates a Precision that you can then set with setTrio. -- Returns Nothing if the argument is out of range. The minimum -- possible value is always 1; the maximum possible value is platform -- dependent and is revealed by maxBound. precision :: Signed -> Maybe Precision unPrecision :: Precision -> Signed getPrecision :: Ctx Precision -- | Sets the precision to the maximum possible, respecting that -- Emax > 5 * Precision. Returns the new -- Precision. setMaxPrecision :: Ctx Precision data Round -- | Round toward positive infinity. roundCeiling :: Round -- | Round away from zero. roundUp :: Round -- | 0.5 rounds up roundHalfUp :: Round -- | 0.5 rounds to nearest even roundHalfEven :: Round -- | 0.5 rounds down roundHalfDown :: Round -- | Round toward zero - truncate roundDown :: Round -- | Round toward negative infinity. roundFloor :: Round -- | Round for reround round05Up :: Round -- | Truncate, but set infinities. roundTruncate :: Round getRound :: Ctx Round setRound :: Round -> Ctx () -- | Maximum adjusted exponent. The adjusted exponent is calculated as -- though the number were expressed in scientific notation. If the -- adjusted exponent would be larger than Emax then an overflow -- results. -- -- The minimum possible value is always 0; the maximum possible value is -- platform dependent and is revealed by maxBound. data Emax unEmax :: Emax -> Signed -- | Returns an Emax for use in setTrio. Fails if argument is -- out of range. emax :: Signed -> Maybe Emax getEmax :: Ctx Emax -- | Minimum adjusted exponent. The adjusted exponent is calculated as -- though the number were expressed in scientific notation. If the -- adjusted exponent would be smaller than Emin then the result is -- subnormal. If the result is also inexact, an underflow results. If -- subnormal results are allowed (see setClamp) the smallest -- possible exponent is Emin minus Precision plus -- 1. -- -- The minimum possible value is platform dependent and is revealed by -- minBound; the maximum possible value is always 0. data Emin unEmin :: Emin -> Signed -- | Returns an Emin for use in setTrio. Fails if argument is -- out of range. emin :: Signed -> Maybe Emin getEmin :: Ctx Emin -- | In addition to the limits on Precision, Emax, and -- Emin, there are also requirements on the relationship between -- these three variables: -- -- -- -- The Trio enforces this relationship. -- -- It is also recommended that Emax > 10 * -- Precision, but since this is not required the Trio -- does not enforce it. data Trio trioPrecision :: Trio -> Precision trioEmax :: Trio -> Emax trioEmin :: Trio -> Emin -- | Make a new Trio. Fails if the values are out of range. trio :: Precision -> Emax -> Emin -> Maybe Trio setTrio :: Trio -> Ctx () getTrio :: Ctx Trio getClamp :: Ctx Bool -- | Controls explicit exponent clamping. When False, a result exponent is -- limited to a maximum of emax and a minimum of emin (for example, the -- exponent of a zero result will be clamped to be in this range). When -- True, a result exponent has the same minimum but is limited to a -- maximum of emax-(digits-1). As well as clamping zeros, this may cause -- the coefficient of a result to be padded with zeros on the right in -- order to bring the exponent within range. -- -- Also when True, this limits the length of NaN payloads to -- Precision - 1 when constructing a NaN by conversion from a -- string. setClamp :: Bool -> Ctx () -- | By default, most functions are correctly rounded. By setting -- allCorrectRound, correct rounding is additionally enabled for exp, ln, -- and log10. In this case, all functions except pow and invroot return -- correctly rounded results. getAllCorrectRound :: Ctx Bool setAllCorrectRound :: Bool -> Ctx () -- | Before running computations in a context. the context must be -- initialized with certain settings, such as the rounding mode, -- precision, and maximum adjusted exponent. An Initializer -- contains all these settings. -- -- On 64-bit platforms, the maximums are: -- -- -- -- On 32-bit platforms, the maximums are: -- -- data Initializer -- | Sets: -- -- -- -- As noted in the documentation for Trio, the specification -- requires that Emax > 5 * Precision; -- Max does not respect this. Max :: Initializer -- | Same as Max, except: -- -- Default :: Initializer -- | Same as Max, except: -- -- Basic :: Initializer -- | Sets the maximum allowable figures, while respecting the restriction -- that stated in the specification and the mpdecimal -- documentation, which is that Emax > 5 * -- Precision. Also, sets no traps. This sets: -- -- Pedantic :: Initializer -- | Sets: -- -- Decimal32 :: Initializer -- | Same as Decimal32, except: -- -- Decimal64 :: Initializer -- | Same as Decimal32, except: -- -- Decimal128 :: Initializer -- | Re-initialize a Ctx using the given Initializer. initCtx :: Initializer -> Ctx () -- | Runs a Ctx computation; begins with the given Initializer to set up -- the context. runCtxInit :: Initializer -> Ctx a -> a -- | Runs a Ctx computation using the Pedantic Initializer. runCtx :: Ctx a -> a -- | Like runCtx but also returns any status flags resulting from -- the computation. runCtxStatus :: Ctx a -> (a, Flags) -- | Runs a Ctx computation within the existing Ctx. The existing Ctx is -- copied to form a new Ctx; then the child computation is run without -- affecting the parent Ctx. local :: Ctx a -> Ctx a -- | Abstract representation of numbers. -- -- The General Decimal Arithmetic Specification gives an abstract -- representation of each number. This information is taken from the -- General Decimal Arithmetic specification at -- -- http://speleotrove.com/decimal/damodel.html -- -- A number may be finite, in which case it has three components: -- a sign, which must be zero (for zero or positive numbers) or -- one (for negative zero and negative numbers), an integral -- coefficient, which is always zero or positive, and a signed -- integral exponent, which indicates the power of ten by which -- the number is multiplied. The value of a finite number if given by -- -- 
--   (-1) ^ sign * coefficient * 10 ^ exponent
--
-- -- In addition to finite numbers, a number may also be one of three -- special values: -- -- -- -- When a number has one of these special values, its coefficient -- and exponent are undefined. An NaN, however, may have -- additional diagnostic information, which is a positive integer. -- -- All special values have a sign. The sign of an infinity is -- significant. The sign of an NaN has no meaning, though it may be -- considered as part of the diagnostic information. -- -- This module allows you to represent a number in abstract terms. It's -- abstract in the sense that you cannot use the abstract form to perform -- arithmetic. It is useful, however, because you might want to -- manipulate the abstract form in your own programs--to make a pretty -- printer with digit grouping, for example. -- -- You can transform an abstract form to a Dec losslessly by -- using abstractToByteString. This gives you a string in -- scientific notation, as specified in to-scientific-string in -- the specification. There is a one-to-one mapping of abstract -- representations to scientific-string representations. You can -- also transform a Dec to an Abstract losslessly by -- using abstractFromByteString. This operation will not fail if -- it is using output from toByteString; but it might fail -- otherwise, if the input is malformed. -- -- All typeclass instances in this module are derived; so while the -- Ord instance might be useful to use Abstract as the -- key in a Map, don't expect it to tell you anything about how to -- Abstract are situated on the number line. module Deka.Abstract -- | Decimal arithmetic. -- -- Much documentation is copied from documentation for the decNumber C -- library, available at -- -- http://speleotrove.com/decimal/dnnumb.html module Deka.Dec -- | A decimal value. A decimal consists of: -- -- -- -- A decimal may also be a special value, which can be: -- -- data Dec -- | Converts a character string to a Dec. Implements the -- _to-number_ conversion from the General Decimal Arithmetic -- specification. -- -- The conversion is exact provided that the numeric string has no more -- significant digits than are specified in the Precision in the -- Ctx and the adjusted exponent is in the range specified by -- Emin and Emax in the Ctx. If there are more than -- Precision digits in the string, or the exponent is out of -- range, the value will be rounded as necessary using the Round -- rounding mode. The Precision therefore both determines the -- maximum precision for unrounded numbers and defines the minimum size -- of the Dec structure required. -- -- Possible errors are conversionSyntax (the string does not have -- the syntax of a number, which depends on setExtended in the -- Ctx), overflow (the adjusted exponent of the number is -- larger than Emax), or underflow (the adjusted exponent -- is less than Emin and the conversion is not exact). If any of -- these conditions are set, the number structure will have a defined -- value as described in the arithmetic specification (this may be a -- subnormal or infinite value). fromByteString :: ByteString -> Ctx Dec -- | Converts a number to scientific notation. toByteString :: Dec -> ByteString -- | Converts a number to engineering notation. toEngByteString :: Dec -> ByteString -- | Addition. add :: Dec -> Dec -> Ctx Dec -- | Subtraction. subtract :: Dec -> Dec -> Ctx Dec -- | Multiplication. multiply :: Dec -> Dec -> Ctx Dec -- | fma x y z multiplies x by y and then adds -- z to that intermediate result. It is equivalent to a -- multiplication followed by an addition except that the intermediate -- result is not rounded and will not cause overflow or underflow. That -- is, only the final result is rounded and checked. -- -- This is a mathematical function; the 10 ^ 6 restrictions on -- precision and range apply as described above. fma :: Dec -> Dec -> Dec -> Ctx Dec -- | Division. divide :: Dec -> Dec -> Ctx Dec -- | Returns the integer part of the result of division. It must be -- possible to express the result as an integer. That is, it must have no -- more digits than Precision in the Ctx. If it does then -- divisionImpossible is raised. divideInteger :: Dec -> Dec -> Ctx Dec -- | remainder a b returns the remainder of a / b. remainder :: Dec -> Dec -> Ctx Dec -- | remainderNear a b returns a - b * n, where -- n is the integer nearest the exact value of a / b. -- If two integers are equally near then the even one is chosen. remainderNear :: Dec -> Dec -> Ctx Dec -- | Returns the absolute value. The same effect as plus unless the -- operand is negative, in which case it is the same as minus. abs :: Dec -> Ctx Dec -- | Returns the result of adding the operand to zero. This takes place -- according to the settings given in the Ctx, following the usual -- arithmetic rules. This may therefore be used for rounding or for -- implementing a prefix plus operation. plus :: Dec -> Ctx Dec -- | Returns the result of subtracting the operand from zero. hat is, it is -- negated, following the usual arithmetic rules; this may be used for -- implementing a prefix minus operation. minus :: Dec -> Ctx Dec -- | compare x y returns -1 if a is less than b, 0 if a -- is equal to b, and 1 if a is greater than b. invalidOperation -- is set if at least one of the operands is a signaling NaN. compare :: Dec -> Dec -> Ctx Dec -- | Identical to compare except that all NaNs (including quiet -- NaNs) set the invalidOperation condition. compareSignal :: Dec -> Dec -> Ctx Dec -- | compareTotal x y compares to numbers using the IEEE 754 total -- ordering. If x is less than y, returns -1. -- If they are equal (that is, when subtracted the result would be 0), -- returns 0. If y is greater than x, returns -- 1. -- -- Here is the total ordering: -- -- 
--   -NaN < -sNaN < -Infinity < -finites < -0 < +0 < +finites
--     < +Infinity < +SNaN < +NaN
--
-- -- Also, 1.000 < 1.0 (etc.) and NaNs are ordered by -- payload. compareTotal :: Dec -> Dec -> Ordering -- | Same as compareTotal except that the signs of the operands are -- ignored and taken to be 0 (non-negative). compareTotalMag :: Dec -> Dec -> Ordering -- | Compares two numbers numerically and returns the larger. If the -- numbers compare equal then number is chosen with regard to sign and -- exponent. Unusually, if one operand is a quiet NaN and the other a -- number, then the number is returned. max :: Dec -> Dec -> Ctx Dec -- | Compares the magnitude of two numbers numerically and sets number to -- the larger. It is identical to max except that the signs of the -- operands are ignored and taken to be 0 (non-negative). maxMag :: Dec -> Dec -> Ctx Dec -- | Compares two numbers numerically and sets number to the smaller. If -- the numbers compare equal then number is chosen with regard to sign -- and exponent. Unusually, if one operand is a quiet NaN and the other a -- number, then the number is returned. min :: Dec -> Dec -> Ctx Dec -- | Compares the magnitude of two numbers numerically and sets number to -- the smaller. It is identical to min except that the signs of -- the operands are ignored and taken to be 0 (non-negative). minMag :: Dec -> Dec -> Ctx Dec -- | Returns the closest representable number that is smaller than the -- operand. nextMinus :: Dec -> Ctx Dec -- | Returns the closest representable number that is larger than the -- operand. nextPlus :: Dec -> Ctx Dec -- | nextToward a b returns the representable number closest to -- a in the direction of b. nextToward :: Dec -> Dec -> Ctx Dec -- | True if both operands have the same exponent; False otherwise. sameQuantum :: Dec -> Dec -> Bool -- | quantize a b returns the number that is equal in value to -- a, but has the exponent of b. quantize :: Dec -> Dec -> Ctx Dec -- | rescale a b returns the number that is equal in value to -- a, but has the exponent b. Special numbers are -- copied without signaling. This function is not part of the General -- Decimal Arithmetic Specification. It is also not equivalent to the -- rescale function that was removed from the specification. rescale :: Dec -> Signed -> Ctx Dec -- | scaleB a b - b must be an integer with exponent 0. If -- a is infinite, returns a. Otherwise, returns -- a with the value of b added to the exponent. scaleB :: Dec -> Dec -> Ctx Dec -- | Digit-wise logical and. and :: Dec -> Dec -> Ctx Dec -- | Digit-wise logical inclusive or. or :: Dec -> Dec -> Ctx Dec -- | Digit-wise logical exclusive or. xor :: Dec -> Dec -> Ctx Dec -- | shift a b returns a shifted by b places. -- b must be in the range [-Precision, Precision]. -- A negative b indicates a right shift, a positive b a -- left shift. Digits that do not fit are discarded. shift :: Dec -> Dec -> Ctx Dec -- | rotate x y returns x rotated by y places. -- y must be in the range [-Precision, Precision]. -- A negative y indicates a right rotation, a positive -- y a left rotation. rotate :: Dec -> Dec -> Ctx Dec -- | Digit-wise inversion (a 0 becomes a 1 and vice -- versa). invert :: Dec -> Ctx Dec reduce :: Dec -> Ctx Dec -- | Round to an integer, using the rounding mode of the context. Only a -- signaling NaN causes an invalidOperation condition. toIntegralExact :: Dec -> Ctx Dec -- | Like toIntegralExact, but inexact and rounded are -- never set. toIntegralValue :: Dec -> Ctx Dec -- | Exponentiation. Result is rounded if necessary using the -- Precision in the Ctx and using the roundHalfEven -- rounding method. -- -- Finite results will always be full precision and inexact, except when -- rhs is a zero or -Infinity (giving 1 or 0 respectively). Inexact -- results will almost always be correctly rounded, but may be up to 1 -- ulp (unit in last place) in error in rare cases. -- -- This is a mathematical function; the 10 ^ 6 restrictions on -- precision and range apply as described above. exp :: Dec -> Ctx Dec -- | Natural logarithm. Results are correctly rounded if -- setAllCorrectRound is True. ln :: Dec -> Ctx Dec -- | Returns the adjusted exponent of the operand, according to the rules -- for logB of IEEE 754. This returns the exponent of the -- operand as though its decimal point had been moved to follow the first -- digit while keeping the same value. The result is not limited by -- Emin or Emax. -- -- If operand is an NaN, the general rules apply. If operand is infinite, -- the result is +Infinity. If operand is zero, result is -Infinity and -- invalidOperation is set. Otherwise, the result is the same as -- the adjusted exponent of the operand, or floor(log10(a)) -- where a is the operand. logB :: Dec -> Ctx Dec -- | Base 10 logarithm. Results are correctly rounded if -- setAllCorrectRound is True. log10 :: Dec -> Ctx Dec -- | power b e returns b raised to the power of -- e. Integer powers are exact, provided that the result is -- finite and fits into Precision. -- -- Results are not correctly rounded, even if setAllCorrectRound -- is True. The error of the function is less than 1ULP + t, -- where t has a maximum of 0.1ULP, but is almost -- always less than 0.001ULP. power :: Dec -> Dec -> Ctx Dec -- | Returns the square root. This function is always correctly rounded -- using the roundHalfEven method. squareRoot :: Dec -> Ctx Dec data PosNeg Pos :: PosNeg Neg :: PosNeg data Number Infinity :: Number Normal :: Number Subnormal :: Number Zero :: Number data Class SNaN :: Class NaN :: Class Number :: PosNeg -> Number -> Class strToClass :: IsString a => [(a, Class)] -- | Determines the Class of a Dec. numClass :: Dec -> Ctx Class -- | False if the decimal is special or zero, or the exponent is less than -- Emin. True otherwise. isNormal :: Dec -> Ctx Bool -- | False if the decimal is special or zero, or the exponent is greater or -- equal to Emin. True otherwise. isSubnormal :: Dec -> Ctx Bool isFinite :: Dec -> Bool isInfinite :: Dec -> Bool isNaN :: Dec -> Bool isNegative :: Dec -> Bool isPositive :: Dec -> Bool isSigned :: Dec -> Bool isQNaN :: Dec -> Bool isSNaN :: Dec -> Bool isSpecial :: Dec -> Bool isZero :: Dec -> Bool isZeroCoeff :: Dec -> Bool isOddCoeff :: Dec -> Bool -- | The sign of a number. data Sign -- | A sign of zero; used for positive numbers and for zero. Sign0 :: Sign -- | A sign of one; used for negative numbers and the negative zero. Sign1 :: Sign sign :: Dec -> Sign data EvenOdd Even :: EvenOdd Odd :: EvenOdd evenOdd :: Dec -> (Maybe EvenOdd) version :: ByteString instance [safe] Show Dec module Deka.Native.Abstract -- | A digit from one to nine. Useful to represent a most significant -- digit, or MSD, as an MSD cannot be the digit zero. data Novem D1 :: Novem D2 :: Novem D3 :: Novem D4 :: Novem D5 :: Novem D6 :: Novem D7 :: Novem D8 :: Novem D9 :: Novem novemToChar :: Novem -> Char charToNovem :: Char -> Maybe Novem novemToInt :: Integral a => Novem -> a intToNovem :: Integral a => a -> Maybe Novem -- | A digit from zero to nine. data Decem D0 :: Decem Nonem :: Novem -> Decem decemToChar :: Decem -> Char charToDecem :: Char -> Maybe Decem decemToInt :: Integral a => Decem -> a decemToNovem :: Decem -> Maybe Novem intToDecem :: Integral a => a -> Maybe Decem intToDecemList :: Integral a => a -> (Sign, [Decem]) decemListToInt :: Integral a => [Decem] -> a -- | A non-empty set of digits. The MSD must be from 1 to 9. data Decuple Decuple :: Novem -> [Decem] -> Decuple decupleToString :: Decuple -> String stringToDecuple :: String -> Maybe Decuple decupleToInt :: Integral a => Decuple -> a uncons :: [a] -> Maybe (a, [a]) intToDecuple :: Integral a => a -> Maybe (Sign, Decuple) decemListToDecuple :: [Decem] -> Maybe Decuple -- | Either a set of digits, or zero. Unsigned. data Aut -- | Zero Nil :: Aut -- | Non-zero Plenus :: Decuple -> Aut autToString :: Aut -> String stringToAut :: String -> Maybe Aut autToInt :: Integral a => Aut -> a -- | Fails if the argument is less than zero. intToAut :: Integral a => a -> Maybe Aut decemListToAut :: [Decem] -> Aut -- | Either a set of digits, or zero. Signed. data Firmado -- | Zero Cero :: Firmado -- | Non-zero Completo :: PosNeg -> Decuple -> Firmado firmadoToString :: Firmado -> String stringToFirmado :: String -> Maybe Firmado firmadoToInt :: Integral a => Firmado -> a intToFirmado :: Integral a => a -> Firmado -- | The coefficient in a number; not used in infinities or NaNs. newtype Coefficient Coefficient :: Aut -> Coefficient unCoefficient :: Coefficient -> Aut -- | The exponent in a number. newtype Exponent Exponent :: Firmado -> Exponent unExponent :: Exponent -> Firmado -- | The diagnostic information in an NaN. newtype Diagnostic Diagnostic :: Decuple -> Diagnostic unDiagnostic :: Diagnostic -> Decuple -- | Whether an NaN is quiet or signaling. data Noisy Quiet :: Noisy Signaling :: Noisy -- | Not a Number. data NonNum NonNum :: Noisy -> Maybe Diagnostic -> NonNum noisy :: NonNum -> Noisy diagnostic :: NonNum -> Maybe Diagnostic -- | All data in an abstract number except for the sign. data Value Finite :: Coefficient -> Exponent -> Value Infinite :: Value NotANumber :: NonNum -> Value -- | Abstract representation of all numbers covered by the General Decimal -- Arithmetic Specification. data Abstract Abstract :: Sign -> Value -> Abstract sign :: Abstract -> Sign value :: Abstract -> Value signToString :: Sign -> String -- | Adjusted exponent. Roughly speaking this represents the coefficient -- and exponent of an abstract decimal, adjusted so there is a decimal -- point between the most significant digit of the coefficient and the -- remaning digits. newtype AdjustedExp AdjustedExp :: Integer -> AdjustedExp unAdjustedExp :: AdjustedExp -> Integer -- | Computes an adjusted exponent. The length of a zero coefficient is -- one. adjustedExp :: Coefficient -> Exponent -> AdjustedExp fmtAdjustedExp :: AdjustedExp -> String finiteToString :: Coefficient -> Exponent -> String nanToString :: NonNum -> String fmtValue :: Value -> String -- | Transform an Abstract to a String. This conforms to the -- to-scientific-string transformation given in the General -- Decimal Arithmetic Specification at -- -- http://speleotrove.com/decimal/daconvs.html#reftostr -- -- with one exception: the specification provides that some finite -- numbers are represented without exponential notation. -- abstractToString always uses exponential notation on -- finite numbers. abstractToString :: Abstract -> String -- | Transforms an Abstract to a Dec. Result is computed in a -- context using the Pedantic initializer. Result is returned -- along with any status flags arising from the computation. abstractToDec :: Abstract -> (Dec, Flags) instance Eq Novem instance Ord Novem instance Show Novem instance Enum Novem instance Bounded Novem instance Eq Decem instance Ord Decem instance Show Decem instance Eq Decuple instance Ord Decuple instance Show Decuple instance Eq Aut instance Ord Aut instance Show Aut instance Eq Firmado instance Ord Firmado instance Show Firmado instance Eq Coefficient instance Ord Coefficient instance Show Coefficient instance Eq Exponent instance Ord Exponent instance Show Exponent instance Eq Diagnostic instance Ord Diagnostic instance Show Diagnostic instance Eq Noisy instance Ord Noisy instance Show Noisy instance Eq NonNum instance Ord NonNum instance Show NonNum instance Eq Value instance Ord Value instance Show Value instance Eq Abstract instance Ord Abstract instance Show Abstract instance Eq AdjustedExp instance Ord AdjustedExp instance Show AdjustedExp -- | Uses the specification for string conversions given in the General -- Decimal Arithmetic Specification to convert strings to an abstract -- syntax tree. The specification for string conversions is at -- -- http://speleotrove.com/decimal/daconvs.html -- -- The functions and types in this module fall into two groups. The first -- group converts a string to a NumericString, which is an -- abstract representation of the grammar given in the General Decimal -- Arithmetic Specification. These functions use Parsec to parse the -- string. The second group transforms the NumericString to an -- Abstract, a form which more closely aligns with the abstract -- representation given at -- -- http://speleotrove.com/decimal/damodel.html. -- -- You can transform an Abstract to a numeric string; no functions -- are provided to transform a NumericString directly back to a -- string. module Deka.Native.FromString sign :: Parser Sign optSign :: Parser Sign digit :: Parser Decem indicator :: Parser () digits :: Parser [Decem] data DecimalPart WholeFrac :: [Decem] -> [Decem] -> DecimalPart WholeOnly :: [Decem] -> DecimalPart decimalPart :: Parser DecimalPart data ExponentPart ExponentPart :: Sign -> [Decem] -> ExponentPart expSign :: ExponentPart -> Sign expDigits :: ExponentPart -> [Decem] exponentPart :: Parser ExponentPart infinity :: Parser () nanId :: Parser Noisy data NaN NaN :: Noisy -> [Decem] -> NaN nan :: Parser NaN data NumericValue NVDec :: DecimalPart -> (Maybe ExponentPart) -> NumericValue Infinity :: NumericValue numericValue :: Parser NumericValue data NumericString NumericString :: Sign -> Either NumericValue NaN -> NumericString nsSign :: NumericString -> Sign nsValue :: NumericString -> Either NumericValue NaN numericString :: Parser NumericString parseNumericString :: String -> Either String NumericString numericStringToAbstract :: NumericString -> Abstract nanToAbstract :: NaN -> NonNum finiteToAbstract :: DecimalPart -> Maybe ExponentPart -> (Coefficient, Exponent) -- | A numeric value for the exponent that was given in the input string. givenExponent :: Maybe ExponentPart -> Integer -- | The number of digits after the decimal point, subtracted from the -- numeric value for the exponent given in the string actualExponent :: DecimalPart -> Integer -> Integer abstractExponent :: Integer -> Exponent abstractCoeff :: DecimalPart -> Coefficient stringToAbstract :: String -> Either String Abstract -- | Transforms a Dec to an Abstract. decToAbstract :: Dec -> Abstract instance Eq DecimalPart instance Ord DecimalPart instance Show DecimalPart instance Eq ExponentPart instance Ord ExponentPart instance Show ExponentPart instance Eq NaN instance Ord NaN instance Show NaN instance Eq NumericValue instance Ord NumericValue instance Show NumericValue instance Eq NumericString instance Ord NumericString instance Show NumericString -- | Representation of numbers in native Haskell types. -- -- Since deka is a binding to the mpdecimal C library, the data types are -- held as pointers to data which are managed by C functions. Therefore -- there is no direct access to what is inside of the the Dec data -- type. Modules in Deka.Native provide Haskell types mirroring -- the abstract representations given in the General Decimal Arithmetic -- Specification. This is useful if you want to manipulate the data in an -- abstract way. For example, perhaps you want to perform arithmetic on a -- value, transform it to abstract form, add digit grouping characters, -- and then use your own functions to pretty print the result. -- -- The General Decimal Arithmetic Specification gives an abstract -- representation of each number. This information is taken from the -- General Decimal Arithmetic specification at -- -- http://speleotrove.com/decimal/damodel.html -- -- A number may be finite, in which case it has three components: -- a sign, which must be zero (for zero or positive numbers) or -- one (for negative zero and negative numbers), an integral -- coefficient, which is always zero or positive, and a signed -- integral exponent, which indicates the power of ten by which -- the number is multiplied. The value of a finite number if given by -- -- 
--   (-1) ^ sign * coefficient * 10 ^ exponent
--
-- -- In addition to finite numbers, a number may also be one of three -- special values: -- -- -- -- When a number has one of these special values, its coefficient -- and exponent are undefined. An NaN, however, may have -- additional diagnostic information, which is a positive integer. -- -- All special values have a sign. The sign of an infinity is -- significant. The sign of an NaN has no meaning, though it may be -- considered as part of the diagnostic information. -- -- You can transform an abstract form to a Dec losslessly by -- using abstractToByteString. This gives you a string in -- scientific notation, as specified in to-scientific-string in -- the specification. There is a one-to-one mapping of abstract -- representations to scientific-string representations. You can -- also transform a Dec to an Abstract losslessly by -- using abstractFromByteString. This operation will not fail if -- it is using output from toByteString; but it might fail -- otherwise, if the input is malformed. -- -- All standard typeclass instances in these modules are derived; so -- while the Ord instance might be useful to use Abstract -- as the key in a Map, don't expect it to tell you anything about how -- Abstract are situated on the number line. module Deka.Native -- | A digit from one to nine. Useful to represent a most significant -- digit, or MSD, as an MSD cannot be the digit zero. data Novem D1 :: Novem D2 :: Novem D3 :: Novem D4 :: Novem D5 :: Novem D6 :: Novem D7 :: Novem D8 :: Novem D9 :: Novem -- | A digit from zero to nine. data Decem D0 :: Decem Nonem :: Novem -> Decem -- | A non-empty set of digits. The MSD must be from 1 to 9. data Decuple Decuple :: Novem -> [Decem] -> Decuple -- | Either a set of digits, or zero. Unsigned. data Aut -- | Zero Nil :: Aut -- | Non-zero Plenus :: Decuple -> Aut -- | Either a set of digits, or zero. Signed. data Firmado -- | Zero Cero :: Firmado -- | Non-zero Completo :: PosNeg -> Decuple -> Firmado -- | The coefficient in a number; not used in infinities or NaNs. newtype Coefficient Coefficient :: Aut -> Coefficient unCoefficient :: Coefficient -> Aut -- | The exponent in a number. newtype Exponent Exponent :: Firmado -> Exponent unExponent :: Exponent -> Firmado -- | The diagnostic information in an NaN. newtype Diagnostic Diagnostic :: Decuple -> Diagnostic unDiagnostic :: Diagnostic -> Decuple -- | Whether an NaN is quiet or signaling. data Noisy Quiet :: Noisy Signaling :: Noisy -- | Not a Number. data NonNum NonNum :: Noisy -> Maybe Diagnostic -> NonNum noisy :: NonNum -> Noisy diagnostic :: NonNum -> Maybe Diagnostic -- | All data in an abstract number except for the sign. data Value Finite :: Coefficient -> Exponent -> Value Infinite :: Value NotANumber :: NonNum -> Value -- | Abstract representation of all numbers covered by the General Decimal -- Arithmetic Specification. data Abstract Abstract :: Sign -> Value -> Abstract sign :: Abstract -> Sign value :: Abstract -> Value -- | Transform an Abstract to a String. This conforms to the -- to-scientific-string transformation given in the General -- Decimal Arithmetic Specification at -- -- http://speleotrove.com/decimal/daconvs.html#reftostr -- -- with one exception: the specification provides that some finite -- numbers are represented without exponential notation. -- abstractToString always uses exponential notation on -- finite numbers. abstractToString :: Abstract -> String -- | Transforms an Abstract to a Dec. Result is computed in a -- context using the Pedantic initializer. Result is returned -- along with any status flags arising from the computation. abstractToDec :: Abstract -> (Dec, Flags) stringToAbstract :: String -> Either String Abstract -- | Transforms a Dec to an Abstract. decToAbstract :: Dec -> Abstract -- | Simple decimal arithmetic. -- -- Deka provides a decimal arithmetic type. Using this module, the -- results are never inexact. Computations will throw exceptions rather -- than returning an inexact result. That way, you know that any result -- you have is exactly correct. -- -- On 64-bit platforms, you are limited to: -- -- -- -- On 32-bit platforms, you are limited to: -- -- -- -- If you exceed these limits, your computation will throw an exception. -- -- Deka represents only finite values. There are no infinities or -- not-a-number values allowed. -- -- For more control over your arithmetic, see Deka.Dec, but for -- many routine uses this module is sufficient and is more succinct -- because, unlike Dec, Deka is a member of the Num -- typeclass. module Deka -- | Deka wraps a Dec. Only finite Dec may become a -- Deka; no infinities or NaN values are allowed. -- -- Deka is a member of Num, making it easy to use for -- elementary arithmetic. Any time you perform arithmetic, the results -- are always exact. The arithmetic functions will throw exceptions -- rather than give you an inexact result. -- -- Deka is not a member Fractional because it is generally -- impossible to perform division without getting inexact results, and -- Deka never holds inexact results. data Deka unDeka :: Deka -> Dec -- | Decimals with a total ordering. newtype DekaT DekaT :: Deka -> DekaT unDekaT :: DekaT -> Deka -- | Convert any integral to a Deka. Returns Nothing if the -- integer is too big to fit into a Deka. integralToDeka :: (Integral a, Show a) => a -> Maybe Deka -- | Convert a string to a Deka. You can use ordinary numeric strings, such -- as 3.25, or exponential notation, like 325E-2. More -- information on your choices is at: -- -- http://speleotrove.com/decimal/daconvs.html#reftonum -- -- You cannot use strings that represent an NaN or an infinity. If you do -- that, or use an otherwise invalid string, this function returns -- Nothing. strToDeka :: String -> Maybe Deka -- | Change a Dec to a Deka. Only succeeds for finite -- Dec. quadToDeka :: Dec -> Maybe Deka -- | Thrown by arithmetic functions in the Num class, as this is the only -- way to indicate errors. data DekaError -- | A computation set flags. This will happen if, for example, you -- calculate a result that is out of range. Flagged :: Flags -> DekaError instance [safe] Typeable DekaError instance [safe] Show DekaError instance [safe] Show Deka instance [safe] Show DekaT instance [safe] Ord DekaT instance [safe] Eq DekaT instance [safe] Num Deka instance [safe] Ord Deka instance [safe] Eq Deka instance [safe] Exception DekaError -- | If you are viewing this module in Haddock and expecting to see -- examples, you won't see anything. The file is written in literate -- Haskell, so the idea is that you will look at the source itself. You -- can look at the source in Haddock, but it will probably be poorly -- formatted because HsColour formats it rather oddly by default. The -- easiest way to see it is on Github: -- -- -- https://github.com/massysett/deka/blob/master/lib/Deka/Docs/Examples.lhs module Deka.Docs.Examples examples :: IO ()