-- 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.
--   All are currently addressed except for rounding modes and exceptions.
--   
--   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.2.2


-- | 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
fquotRem :: (RealFloat a) => a -> a -> (Int, 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
lgamma :: (RealFloat a) => a -> a
tgamma :: (RealFloat a) => a -> a
classify :: (RealFloat a) => a -> FPClassification
infinity :: (RealFloat a) => a
nan :: (RealFloat a) => a
pi :: (RealFloat a) => a
instance Show FPClassification
instance Read FPClassification
instance Eq FPClassification
instance Enum FPClassification
instance Bounded FPClassification


-- | 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_asin :: CDouble -> CDouble
c_atan :: CDouble -> CDouble
c_atan2 :: CDouble -> CDouble -> CDouble
c_cos :: CDouble -> CDouble
c_sin :: CDouble -> CDouble
c_tan :: CDouble -> CDouble
c_acosh :: CDouble -> CDouble
c_asinh :: CDouble -> CDouble
c_atanh :: CDouble -> CDouble
c_cosh :: CDouble -> CDouble
c_sinh :: CDouble -> CDouble
c_tanh :: CDouble -> CDouble
c_exp :: CDouble -> CDouble
c_exp2 :: CDouble -> CDouble
c_expm1 :: CDouble -> CDouble
c_frexp :: CDouble -> Ptr CInt -> IO CDouble
c_ilogb :: CDouble -> CInt
c_ldexp :: CDouble -> CInt -> CDouble
c_log :: CDouble -> CDouble
c_log10 :: CDouble -> CDouble
c_log1p :: CDouble -> CDouble
c_log2 :: CDouble -> CDouble
c_logb :: CDouble -> CDouble
c_modf :: CDouble -> Ptr CDouble -> IO CDouble
c_scalbn :: CDouble -> CInt -> CDouble
c_scalbln :: CDouble -> CLong -> CDouble
c_cbrt :: CDouble -> CDouble
c_fabs :: CDouble -> CDouble
c_hypot :: CDouble -> CDouble -> CDouble
c_pow :: CDouble -> CDouble -> CDouble
c_sqrt :: CDouble -> CDouble
c_fmod :: CDouble -> CDouble -> CDouble
c_remainder :: CDouble -> CDouble -> CDouble
c_remquo :: CDouble -> CDouble -> Ptr CInt -> IO CDouble
c_copysign :: CDouble -> CDouble -> CDouble
c_nan :: CString -> IO CDouble
c_nextafter :: CDouble -> CDouble -> CDouble
c_erf :: CDouble -> CDouble
c_erfc :: CDouble -> CDouble
c_lgamma :: CDouble -> CDouble
c_tgamma :: CDouble -> CDouble
c_ceil :: CDouble -> CDouble
c_floor :: CDouble -> CDouble
c_nearbyint :: CDouble -> CDouble
c_rint :: CDouble -> CDouble
c_lrint :: CDouble -> CLong
c_llrint :: CDouble -> CLLong
c_round :: CDouble -> CDouble
c_lround :: CDouble -> CLong
c_llround :: CDouble -> CLLong
c_trunc :: CDouble -> CDouble
c_fdim :: CDouble -> CDouble -> CDouble
c_fmax :: CDouble -> CDouble -> CDouble
c_fmin :: CDouble -> CDouble -> CDouble
c_fma :: CDouble -> CDouble -> CDouble -> CDouble
libmDouble :: (CDouble -> CDouble) -> Double -> Double
libmDouble2 :: (CDouble -> CDouble -> CDouble) -> Double -> Double -> Double
libmDouble3 :: (CDouble -> CDouble -> CDouble -> CDouble) -> Double -> Double -> Double -> Double

module Data.Floating.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 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


-- | 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 :: (RealFloat a) => a -> Bool
isNaN :: (RealFloat a) => a -> Bool
isNormal :: (RealFloat a) => a -> Bool
isSubNormal :: (RealFloat a) => a -> Bool
isFinite :: (RealFloat a) => a -> Bool
isNegativeZero :: (RealFloat a) => a -> Bool

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