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


-- | ieee-utils
--   
--   IEEE 754 (Standard for Binary Floating-Point Arithmetic) Utilities.
@package ieee-utils
@version 0.4.0


module Numeric.IEEE.FloatExceptions

-- | Returns all exceptions set in the fpu's exception register.
getFloatExcepts :: IO [ArithException]

-- | Clears the specified exceptions from the fpu's exception register.
clearFloatExcepts :: [ArithException] -> IO Bool

-- | Arithmetic exceptions.
data ArithException :: *
Overflow :: ArithException
Underflow :: ArithException
LossOfPrecision :: ArithException
DivideByZero :: ArithException
Denormal :: ArithException
instance Enum ArithException


module Numeric.IEEE.RoundMode
data RoundMode
ToNearest :: RoundMode
Upward :: RoundMode
Downward :: RoundMode
TowardZero :: RoundMode

-- | Gets the fpu's current rounding mode.
getRound :: IO RoundMode

-- | Sets the fpu's rounding mode. Returns <tt>True</tt> if successful.
setRound :: RoundMode -> IO Bool
instance Eq RoundMode
instance Ord RoundMode
instance Show RoundMode
instance Read RoundMode
instance Enum RoundMode


-- | The IEEE monad provides tools for enforcing sequencing of calculations
--   such that fine grained control is provided over triggering exceptions,
--   evaluations within particular rounding modes, etc. The perturb family
--   of functions is built using this, allowing pure computations
--   paramaterized over an arbitrary Floating type to be tested for numeric
--   stability.
module Numeric.IEEE.Monad

-- | All uses of the IEEE monad need to be wrapped inside a top level call
--   to withIeeeDo. This ensures that access to floating point internals is
--   serialized properly, even between multiple threads.
withIeeeDo :: ((?ieeeMutex :: MVar ()) => IO a) -> IO a
newtype IEEE a
IEEE :: IO a -> IEEE a
unIEEE :: IEEE a -> IO a
runIEEE :: (?ieeeMutex :: MVar ()) => IEEE a -> IO a
getRound :: IEEE RoundMode
setRound :: RoundMode -> IEEE Bool
clearFloatExcepts :: [ArithException] -> IEEE Bool
getFloatExcepts :: IEEE [ArithException]

-- | Forces strict evaluation of the enclosed numeric argument.
calculate :: a -> IEEE a

-- | Calculate, but also returns any floating exceptions triggered.
calculate' :: a -> IEEE (a, [ArithException])

-- | Executes the specified IEEE action within a specific round mode.
withRoundMode :: RoundMode -> IEEE a -> IEEE a

-- | Given something of (forall a. Floating a =&gt; IEEE a) produces a
--   four-tuple of the value as calculated rounding up, down, to nearest,
--   and towards zero.
perturb' :: (?ieeeMutex :: MVar (), Floating b) => (forall a. (Floating a) => IEEE a) -> IO (b, b, b, b)

-- | Given something that produces a Floating, returns a representation of
--   the absolute difference between the results as calculated rounding
--   upwards and downwards.
perturb :: (?ieeeMutex :: MVar (), Floating b) => (forall a. (Floating a) => IEEE a) -> IO b

-- | Given something that produces a Floating, returns the magnitude of
--   instability introduced by perturbing the equation by rounding upwards
--   and then downwards. This is the absolute difference between the
--   results as calculated rounding upwards and downwards, and then divided
--   by the averaged result.
perturbedMag :: (?ieeeMutex :: MVar (), Floating b) => (forall a. (Floating a) => IEEE a) -> IO b
instance Monad IEEE
instance Functor IEEE
instance Applicative IEEE