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


-- | Alternative floating point support for GHC.
--   
--   A replacement for the standard Haskell floating point types and
--   supporting functions. There are a number of shortcomings which I feel
--   severely hinder Haskell's utility for numerical computation. These
--   shortcomings include
--   
--   <ul>
--   <li>There is no way to sanely convert between Haskell's floating types
--   -- not even between Double and CDouble. The implementation of the
--   <a>realToFrac</a> function goes through <a>Rational</a>, which loses
--   information as <a>Rational</a> cannot represent all floating point
--   values.</li>
--   <li>Making floating types an instance of <a>Ord</a> makes no sense.
--   <a>Ord</a> is for totally ordered data types, which floats are not. As
--   a result, a number of library functions (such as <a>max</a> and
--   <a>sort</a>) produce nonsensical results.</li>
--   <li>The <a>Enum</a> instance for floating types similarly makes little
--   sense. While <a>fromEnum</a> and <a>toEnum</a> functions use
--   <a>Int</a> instead of <a>Integer</a>, limiting their usefulness,
--   <a>pred</a> and <a>succ</a> can be defined in a much more useful
--   way.</li>
--   <li>Functions that should care about negative zeros, such as
--   <a>signum</a> and <a>abs</a>, do not.</li>
--   <li>Some functions, such as <a>floor</a>, have nonsensical behaviour
--   for non-finite input.</li>
--   <li>The selection of floating point library functions pales in
--   comparison to C. This problem is made worse since, as noted above, it
--   is impossible to convert losslessly from <a>Double</a> to
--   <a>CDouble</a> in order to use the FFI.</li>
--   <li>There is no mechanism for handling rounding modes or
--   exceptions.</li>
--   </ul>
--   
--   This package is intended to address all of the above issues, and more.
--   Also provided, for convenience, is an alternative to the standard
--   Prelude which includes features from this library and the
--   non-overlapping parts of the standard Prelude.
@package altfloat
@version 0.3.1


-- | Partially ordered data types. The standard <a>Ord</a> class is for
--   total orders and therefore not suitable for floating point. However,
--   we can still define meaningful <a>max</a> and <a>sort</a> functions
--   for these types.
--   
--   We define our own <a>Ord</a> class which is intended as a replacement
--   for <a>Ord</a>. However, in order to take advantage of existing
--   libraries which use <a>Ord</a>, we make every instance of <a>Ord</a>
--   an instance of <a>Ord</a>. This is done using the OverlappingInstances
--   and UndecidableInstances extensions -- it remains to be seen if
--   problems occur as a result of this.
module Data.Poset

-- | Class for partially ordered data types. Instances should satisfy the
--   following laws for all values a, b and c:
--   
--   <ul>
--   <li><tt>a &lt;= a</tt>.</li>
--   <li><tt>a &lt;= b</tt> and <tt>b &lt;= a</tt> implies <tt>a ==
--   b</tt>.</li>
--   <li><tt>a &lt;= b</tt> and <tt>b &lt;= c</tt> implies <tt>a &lt;=
--   c</tt>.</li>
--   </ul>
--   
--   But note that the floating point instances don't satisfy the first
--   rule.
--   
--   Minimal complete definition: <a>compare</a> or <a>&lt;=</a>.
class Eq a => Poset a
compare :: Poset a => a -> a -> Ordering
(<==>) :: Poset a => a -> a -> Bool
(</=>) :: Poset a => a -> a -> Bool
(<) :: Poset a => a -> a -> Bool
(<=) :: Poset a => a -> a -> Bool
(>=) :: Poset a => a -> a -> Bool
(>) :: Poset a => a -> a -> Bool

-- | Class for partially ordered data types where sorting makes sense. This
--   includes all totally ordered sets and floating point types. Instances
--   should satisfy the following laws:
--   
--   <ul>
--   <li>The set of elements for which <a>isOrdered</a> returns true is
--   totally ordered.</li>
--   <li>The max (or min) of an insignificant element and a significant
--   element is the significant one.</li>
--   <li>The result of sorting a list should contain only significant
--   elements.</li>
--   <li><tt>max a b</tt> = <tt>max b a</tt></li>
--   <li><tt>min a b</tt> = <tt>min b a</tt></li>
--   </ul>
--   
--   The idea comes from floating point types, where non-comparable
--   elements (NaNs) are the exception rather than the rule. For these
--   types, we can define <a>max</a>, <a>min</a> and <a>sortBy</a> to
--   ignore insignificant elements. Thus, a sort of floating point values
--   will discard all NaNs and order the remaining elements.
--   
--   Minimal complete definition: <a>isOrdered</a>
class Poset a => Sortable a
sortBy :: Sortable a => (a -> a -> Ordering) -> [a] -> [a]
isOrdered :: Sortable a => a -> Bool
max :: Sortable a => a -> a -> a
min :: Sortable a => a -> a -> a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering
NC :: Ordering

-- | Class for totally ordered data types. Instances should satisfy
--   <tt>isOrdered a = True</tt> for all <tt>a</tt>.
class Sortable a => Ord a

-- | Sort a list using the default comparison function.
sort :: Sortable a => [a] -> [a]

-- | Apply a function to values before comparing.
comparing :: Poset b => (a -> b) -> a -> a -> Ordering
instance Poset a => Poset [a]
instance Poset a => Poset (Maybe a)


-- | Generic classes for floating point types. The interface is loosely
--   based off of the C math library.
module Data.Floating.Classes

-- | Classification of floating point values.
data FPClassification
FPInfinite :: FPClassification
FPNaN :: FPClassification
FPNormal :: FPClassification
FPSubNormal :: FPClassification
FPZero :: FPClassification

-- | Class for types which can be rounded to integers. The rounding
--   functions in the Prelude are inadequate for floating point because
--   they shoehorn their results into an integral type.
--   
--   Minimal complete definition: <a>toIntegral</a> and <a>round</a>.
class (Fractional a, Poset a) => Roundable a
toIntegral :: (Roundable a, Integral b) => a -> Maybe b
ceiling :: Roundable a => a -> a
floor :: Roundable a => a -> a
truncate :: Roundable a => a -> a
round :: Roundable a => a -> a

-- | Class for floating point types (real or complex-valued).
--   
--   Minimal complete definition: everything.
class Fractional a => Floating a
(**) :: Floating a => a -> a -> a
sqrt :: Floating a => a -> a
acos :: Floating a => a -> a
asin :: Floating a => a -> a
atan :: Floating a => a -> a
cos :: Floating a => a -> a
sin :: Floating a => a -> a
tan :: Floating a => a -> a
acosh :: Floating a => a -> a
asinh :: Floating a => a -> a
atanh :: Floating a => a -> a
cosh :: Floating a => a -> a
sinh :: Floating a => a -> a
tanh :: Floating a => a -> a
exp :: Floating a => a -> a
log :: Floating a => a -> a

-- | Class for real-valued floating point types.
--   
--   Minimal complete definition: all except <a>pi</a>, <a>infinity</a> and
--   <a>nan</a>.
class Floating a => RealFloat a
fma :: RealFloat a => a -> a -> a -> a
copysign :: RealFloat a => a -> a -> a
nextafter :: RealFloat a => a -> a -> a
atan2 :: RealFloat a => a -> a -> a
fmod :: RealFloat a => a -> a -> a
frem :: RealFloat a => a -> a -> a
hypot :: RealFloat a => a -> a -> a
cbrt :: RealFloat a => a -> a
exp2 :: RealFloat a => a -> a
expm1 :: RealFloat a => a -> a
log10 :: RealFloat a => a -> a
log1p :: RealFloat a => a -> a
log2 :: RealFloat a => a -> a
logb :: RealFloat a => a -> a
erf :: RealFloat a => a -> a
erfc :: RealFloat a => a -> a
gamma :: RealFloat a => a -> a
lgamma :: RealFloat a => a -> a
rint :: RealFloat a => a -> a
nearbyint :: RealFloat a => a -> a
infinity :: RealFloat a => a
nan :: RealFloat a => a
pi :: RealFloat a => a

-- | Class for the basic floating point types.
class (Roundable a, RealFloat a) => PrimFloat a
classify :: PrimFloat a => a -> FPClassification
instance Show FPClassification
instance Read FPClassification
instance Eq FPClassification
instance Enum FPClassification
instance Bounded FPClassification


-- | Access to the floating point environment. Performing this access
--   within a Haskell program turns out to be extremely problematic,
--   because floating point operations are secretly impure. For example,
--   the innocent-looking function
--   
--   <pre>
--   (+) :: Double -&gt; Double -&gt; Double
--   </pre>
--   
--   potentially both depends on and modifies the global floating point
--   environment.
--   
--   This module avoids the referential transparency problems that occur as
--   a result of accessing the floating point environment by restricting
--   when computations which access it are evaluated. There is some minor
--   discipline required of the programmer: she must arrange her code so
--   that pure floating point expressions are not forced during a call to
--   <a>fenvEval</a>. See <tt>fenv-impure.hs</tt> in the <tt>examples/</tt>
--   directory of the altfloat distribution for why this discipline is
--   necessary.
--   
--   FEnv instances the numeric classes, so it should be possible to use
--   natural syntax. Note that the operations done on FEnv are stored so
--   that they can be performed later, thus one should be take care not to
--   construct huge thunks when using this interface.
--   
--   This interface has not been tested in multi-threaded programs. It
--   might work: more info is needed about GHC's threading support.
module Data.Floating.Environment
data RoundingMode
ToNearest :: RoundingMode
Upward :: RoundingMode
Downward :: RoundingMode
TowardZero :: RoundingMode
data FloatException
DivByZero :: FloatException
Inexact :: FloatException
Invalid :: FloatException
Overflow :: FloatException
Underflow :: FloatException

-- | Opaque type which stores the complete floating point environment. It
--   corresponds to the C type <tt>fenv_t</tt>.
data FEnvState

-- | Container for computations which will be run in a modified floating
--   point environment. The FEnv container records all operations for later
--   evaluation by <a>fenvEval</a>. Note that <a>pure</a> is strict in
--   order to force evaluation of floating point values stored in the
--   container.
--   
--   Do not use the <a>Eq</a> or <a>Show</a> instances, they are provided
--   only because Num requires them.
data FEnv a

-- | Runs all the computations which are recorded in an FEnv container. The
--   floating point environment is preserved across this call, and any
--   floating point exceptions which were raised during the computation are
--   returned.
fenvEval :: FEnv a -> IO (a, [FloatException])

-- | Evaluate an FEnv using a specific rounding mode. Rounding mode
--   selections nest: subcomputations might use another mode. The default
--   rounding mode is unspecified.
withRoundingMode :: RoundingMode -> FEnv a -> FEnv a

-- | Raise floating point exceptions as part of an FEnv computation.
raiseExceptions :: [FloatException] -> FEnv a -> FEnv a

-- | This function is to help with debugging the floating point environment
--   handling. <tt>fenvTrace msg x</tt> constructs an FEnv value containing
--   <tt>x</tt> that prints <tt>msg</tt> (using <a>trace</a>) whenever the
--   value is extracted.
fenvTrace :: String -> a -> FEnv a

-- | Saves the current floating point environment and, optionally, clears
--   all floating point exception flags and sets non-stop (continue on
--   exceptions) mode.
unsafeSaveEnvironment :: Bool -> IO FEnvState

-- | Restores a previously-saved floating point environment and returns the
--   list of floating point exceptions that occurred prior to restoring the
--   environment.
unsafeRestoreEnvironment :: FEnvState -> IO [FloatException]

-- | Raises the given floating point exceptions.
unsafeRaiseExceptions :: [FloatException] -> IO ()
unsafeSetRoundingMode :: RoundingMode -> IO ()
getRoundingMode :: IO RoundingMode
instance Show FloatException
instance Read FloatException
instance Enum FloatException
instance Bounded FloatException
instance Show RoundingMode
instance Read RoundingMode
instance Enum RoundingMode
instance Bounded RoundingMode
instance RealFloat a => RealFloat (FEnv a)
instance Floating a => Floating (FEnv a)
instance Fractional a => Fractional (FEnv a)
instance Num a => Num (FEnv a)
instance Show a => Show (FEnv a)
instance Eq a => Eq (FEnv a)
instance Applicative FEnv
instance Functor FEnv
instance Storable FEnvState


-- | Definition of the core floating point types and basic manipulation of
--   them.
module Data.Floating.Types

-- | The Double type. This is expected to be an identical declaration to
--   the one found in GHC.Prim. We avoid simply using GHC's type because we
--   need to define our own class instances.
data Double
D# :: Double# -> Double

-- | The Float type.
data Float
F# :: Float# -> Float

-- | Coercion to floating point types.
class FloatConvert a b
toFloating :: FloatConvert a b => a -> b
instance [overlap ok] FloatConvert a a
instance [overlap ok] Real a => FloatConvert a Float
instance [overlap ok] Real a => FloatConvert a Double
instance [overlap ok] FloatConvert Integer Float
instance [overlap ok] FloatConvert Integer Double
instance [overlap ok] FloatConvert Float Double
instance [overlap ok] FloatConvert Double Float
instance [overlap ok] FloatConvert CFloat Float
instance [overlap ok] FloatConvert Float CFloat
instance [overlap ok] FloatConvert CDouble Double
instance [overlap ok] FloatConvert Double CDouble


-- | Bindings to the standard C math library.
module Data.Floating.CMath
c_acos :: CDouble -> CDouble
c_acosf :: CFloat -> CFloat
c_asin :: CDouble -> CDouble
c_asinf :: CFloat -> CFloat
c_atan :: CDouble -> CDouble
c_atanf :: CFloat -> CFloat
c_atan2 :: CDouble -> CDouble -> CDouble
c_atan2f :: CFloat -> CFloat -> CFloat
c_cos :: CDouble -> CDouble
c_cosf :: CFloat -> CFloat
c_sin :: CDouble -> CDouble
c_sinf :: CFloat -> CFloat
c_tan :: CDouble -> CDouble
c_tanf :: CFloat -> CFloat
c_acosh :: CDouble -> CDouble
c_acoshf :: CFloat -> CFloat
c_asinh :: CDouble -> CDouble
c_asinhf :: CFloat -> CFloat
c_atanh :: CDouble -> CDouble
c_atanhf :: CFloat -> CFloat
c_cosh :: CDouble -> CDouble
c_coshf :: CFloat -> CFloat
c_sinh :: CDouble -> CDouble
c_sinhf :: CFloat -> CFloat
c_tanh :: CDouble -> CDouble
c_tanhf :: CFloat -> CFloat
c_exp :: CDouble -> CDouble
c_expf :: CFloat -> CFloat
c_exp2 :: CDouble -> CDouble
c_exp2f :: CFloat -> CFloat
c_expm1 :: CDouble -> CDouble
c_expm1f :: CFloat -> CFloat
c_frexp :: CDouble -> Ptr CInt -> IO CDouble
c_frexpf :: CFloat -> Ptr CInt -> IO CFloat
c_ilogb :: CDouble -> CInt
c_ilogbf :: CFloat -> CInt
c_ldexp :: CDouble -> CInt -> CDouble
c_ldexpf :: CFloat -> CInt -> CFloat
c_log :: CDouble -> CDouble
c_logf :: CFloat -> CFloat
c_log10 :: CDouble -> CDouble
c_log10f :: CFloat -> CFloat
c_log1p :: CDouble -> CDouble
c_log1pf :: CFloat -> CFloat
c_log2 :: CDouble -> CDouble
c_log2f :: CFloat -> CFloat
c_logb :: CDouble -> CDouble
c_logbf :: CFloat -> CFloat
c_modf :: CDouble -> Ptr CDouble -> IO CDouble
c_modff :: CFloat -> Ptr CFloat -> IO CFloat
c_scalbn :: CDouble -> CInt -> CDouble
c_scalbnf :: CFloat -> CInt -> CFloat
c_scalbln :: CDouble -> CLong -> CDouble
c_scalblnf :: CFloat -> CLong -> CFloat
c_cbrt :: CDouble -> CDouble
c_cbrtf :: CFloat -> CFloat
c_fabs :: CDouble -> CDouble
c_fabsf :: CFloat -> CFloat
c_hypot :: CDouble -> CDouble -> CDouble
c_hypotf :: CFloat -> CFloat -> CFloat
c_pow :: CDouble -> CDouble -> CDouble
c_powf :: CFloat -> CFloat -> CFloat
c_sqrt :: CDouble -> CDouble
c_sqrtf :: CFloat -> CFloat
c_fmod :: CDouble -> CDouble -> CDouble
c_fmodf :: CFloat -> CFloat -> CFloat
c_remainder :: CDouble -> CDouble -> CDouble
c_remainderf :: CFloat -> CFloat -> CFloat
c_remquo :: CDouble -> CDouble -> Ptr CInt -> IO CDouble
c_remquof :: CFloat -> CFloat -> Ptr CInt -> IO CFloat
c_copysign :: CDouble -> CDouble -> CDouble
c_copysignf :: CFloat -> CFloat -> CFloat
c_nan :: CString -> IO CDouble
c_nanf :: CString -> IO CFloat
c_nextafter :: CDouble -> CDouble -> CDouble
c_nextafterf :: CFloat -> CFloat -> CFloat
c_erf :: CDouble -> CDouble
c_erff :: CFloat -> CFloat
c_erfc :: CDouble -> CDouble
c_erfcf :: CFloat -> CFloat
c_lgamma :: CDouble -> CDouble
c_lgammaf :: CFloat -> CFloat
c_tgamma :: CDouble -> CDouble
c_tgammaf :: CFloat -> CFloat
c_ceil :: CDouble -> CDouble
c_ceilf :: CFloat -> CFloat
c_floor :: CDouble -> CDouble
c_floorf :: CFloat -> CFloat
c_nearbyint :: CDouble -> CDouble
c_nearbyintf :: CFloat -> CFloat
c_rint :: CDouble -> CDouble
c_rintf :: CFloat -> CFloat
c_lrint :: CDouble -> CLong
c_lrintf :: CFloat -> CLong
c_llrint :: CDouble -> CLLong
c_llrintf :: CFloat -> CLLong
c_round :: CDouble -> CDouble
c_roundf :: CFloat -> CFloat
c_lround :: CDouble -> CLong
c_lroundf :: CFloat -> CLong
c_llround :: CDouble -> CLLong
c_llroundf :: CFloat -> CLLong
c_trunc :: CDouble -> CDouble
c_truncf :: CFloat -> CFloat
c_fdim :: CDouble -> CDouble -> CDouble
c_fdimf :: CFloat -> CFloat -> CFloat
c_fmax :: CDouble -> CDouble -> CDouble
c_fmaxf :: CFloat -> CFloat -> CFloat
c_fmin :: CDouble -> CDouble -> CDouble
c_fminf :: CFloat -> CFloat -> CFloat
c_fma :: CDouble -> CDouble -> CDouble -> CDouble
c_fmaf :: CFloat -> CFloat -> CFloat -> CFloat
libmDouble :: (CDouble -> CDouble) -> Double -> Double
libmFloat :: (CFloat -> CFloat) -> Float -> Float
libmDouble2 :: (CDouble -> CDouble -> CDouble) -> Double -> Double -> Double
libmFloat2 :: (CFloat -> CFloat -> CFloat) -> Float -> Float -> Float
libmDouble3 :: (CDouble -> CDouble -> CDouble -> CDouble) -> Double -> Double -> Double -> Double
libmFloat3 :: (CFloat -> CFloat -> CFloat -> CFloat) -> Float -> Float -> Float -> Float

module Data.Floating.Types.Double

-- | The Double type. This is expected to be an identical declaration to
--   the one found in GHC.Prim. We avoid simply using GHC's type because we
--   need to define our own class instances.
data Double
instance PrimFloat Double
instance RealFloat Double
instance Floating Double
instance Roundable Double
instance Fractional Double
instance Sortable Double
instance Poset Double
instance Enum Double
instance Num Double
instance Eq Double
instance Read Double
instance Show Double

module Data.Floating.Types.Float

-- | The Float type.
data Float
instance PrimFloat Float
instance RealFloat Float
instance Floating Float
instance Roundable Float
instance Fractional Float
instance Sortable Float
instance Poset Float
instance Enum Float
instance Num Float
instance Eq Float
instance Read Float
instance Show Float


-- | Top level module for alternative floating point support.
module Data.Floating

-- | The Double type. This is expected to be an identical declaration to
--   the one found in GHC.Prim. We avoid simply using GHC's type because we
--   need to define our own class instances.
data Double

-- | The Float type.
data Float
isInfinite :: PrimFloat a => a -> Bool
isNaN :: PrimFloat a => a -> Bool
isNormal :: PrimFloat a => a -> Bool
isSubNormal :: PrimFloat a => a -> Bool
isFinite :: PrimFloat a => a -> Bool
isNegativeZero :: PrimFloat a => a -> Bool

-- | <tt>fquotRem x y</tt> computes the remainder and integral quotient
--   upon division of x by y. The result is (x-n*y, n), where n is the
--   value x/y rounded to the nearest integer.
fquotRem :: RealFloat a => a -> a -> (a, a)

-- | Convert to a floating point type. Conversions from integers and real
--   types are provided, as well as conversions between floating point
--   types. Conversions between floating point types preserve infinities,
--   negative zeros and NaNs.
toFloating :: FloatConvert a b => a -> b


-- | Alternate prelude for the alternate floating point types. This module
--   re-exports the Data.Floating and Data.Poset operations as well as all
--   the Prelude operations that do not conflict.
module Data.Floating.Prelude