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


-- | Bitwise accurate floating point conversion, and Unit of Lease Precision calculation.
--   
--   A small library to cast floating point values to integral values and
--   back preserving the bit-pattern.
@package floating-bits
@version 0.3.1.0


-- | Primitive operations to coerce floating point numbers to integral
--   numbers preserving their bitwise representations as well as functions
--   operating on boxed values.
module Data.Bits.Floating.Prim

-- | Convert a <a>Double</a> to a <a>Word64</a> while preserving the
--   bit-pattern.
double2WordBitwise :: Double -> Word64

-- | Convert a <a>Float</a> to a <a>Word32</a> while preserving the
--   bit-pattern.
float2WordBitwise :: Float -> Word32

-- | Convert a <a>Word64</a> to a <a>Double</a> while preserving the
--   bit-pattern.
word2DoubleBitwise :: Word64 -> Double

-- | Convert a <a>Word32</a> to a <a>Float</a> while preserving the
--   bit-pattern.
word2FloatBitwise :: Word32 -> Float


-- | Provides increment-by-ulp, decrement-by-ulp, and get-ulp functions for
--   Doubles, and Floats.
module Data.Bits.Floating.Ulp

-- | Advance a <a>Double</a> by one ULP.
doubleNextUlp :: Double -> Double

-- | Subtract one ULP from a <a>Double</a>.
doublePrevUlp :: Double -> Double

-- | Return the distance to the next floating point number.
doubleUlp :: Double -> Double

-- | Advance a <a>Float</a> by one ULP.
floatNextUlp :: Float -> Float

-- | Subtract one ULP from a <a>Float</a>.
floatPrevUlp :: Float -> Float

-- | Return the distance to the next floating point number.
floatUlp :: Float -> Float


-- | Functions for performing conversions between floating point values and
--   Integral values, for retrieving the Unit of Least Precision of a
--   floating point value, and for incrementing / decrementing a value by
--   one ULP..
module Data.Bits.Floating
class (Floating f, Integral w) => FloatingBits f w | f -> w

-- | Coerce a floating point number to an integral number preserving the
--   bitwise representation.
coerceToWord :: FloatingBits f w => f -> w

-- | Coerce a integral number to an floating point number preserving the
--   bitwise representation.
--   
--   Note: It is not always possible to do this. In particular, if we
--   coerce the bit pattern of a NaN value, we might get a NaN value with a
--   different bit pattern than we wanted, so it is possible that
--   <tt><a>coerceToWord</a> (<a>coerceToFloat</a> w) /= w</tt>.
coerceToFloat :: FloatingBits f w => w -> f

-- | Return the next floating point value in the direction of +INF. If the
--   argument is NaN, NaN is returned. If the argument is +INF, +INF is
--   returned. If the argument is 0.0, the minimum value greater than 0.0
--   is returned. If the argument is -INF, -INF is returned.
nextUp :: FloatingBits f w => f -> f

-- | Return the next floating point value in the direction of -INF. If the
--   argument is NaN, NaN is returned. If the argument is +INF, +INF is
--   returned. If the argument is 0.0, the maximum value smaller than 0.0
--   is returned. If the argument is -INF, -INF is returned.
nextDown :: FloatingBits f w => f -> f

-- | Return the size of the Unit of Least Precision of the argument. If the
--   argument is NaN, NaN is returned. If the argument is +INF or -INF,
--   +INF is returned. If the argument is 0.0, the minimum value greater
--   than 0.0 is returned.
--   
--   If <tt>x</tt> is not NaN or one of the infinities, <tt><a>ulp</a> x ==
--   <a>ulp</a> (-x)</tt> holds.
ulp :: FloatingBits f w => f -> f
class ShowFloat f

-- | Like <a>showFloat</a>, but prepends the value to another string.
showsFloat :: ShowFloat f => f -> ShowS

-- | Convert a float to a string, but show additional information if it is
--   a NaN value.
showFloat :: ShowFloat f => f -> String

-- | Cast a <a>CFloat</a> to a <a>Float</a>.
fromCFloat :: CFloat -> Float

-- | Cast a <a>CDouble</a> to a <a>Double</a>.
fromCDouble :: CDouble -> Double
instance Data.Bits.Floating.ShowFloat GHC.Types.Float
instance Data.Bits.Floating.ShowFloat GHC.Types.Double
instance Data.Bits.Floating.ShowFloat Foreign.C.Types.CFloat
instance Data.Bits.Floating.ShowFloat Foreign.C.Types.CDouble
instance Data.Bits.Floating.FloatingBits GHC.Types.Float GHC.Word.Word32
instance Data.Bits.Floating.FloatingBits GHC.Types.Double GHC.Word.Word64
instance Data.Bits.Floating.FloatingBits Foreign.C.Types.CFloat GHC.Word.Word32
instance Data.Bits.Floating.FloatingBits Foreign.C.Types.CDouble GHC.Word.Word64