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

-- | IEEE 754-2019 compliant operations
--   
--   Please see the README on GitHub at
--   https://github.com/minoki/haskell-floating-point/tree/master/fp-ieee#readme
@package fp-ieee
@version 0.1.0.6

-- | This module provides IEEE 754-compliant operations for floating-point
--   numbers.
--   
--   The functions in this module assume that the given floating-point type
--   conform to IEEE 754 format.
--   
--   Since RealFloat constraint is insufficient to query properties
--   of a NaN, the functions here assumes all NaN as positive, quiet. If
--   you want better treatment for NaNs, use the module
--   Numeric.Floating.IEEE.NaN.
--   
--   Since floating-point exceptions cannot be accessed from Haskell, the
--   operations provided by this module ignore exceptional behavior. This
--   library assumes the default exception handling is in use.
--   
--   If you are using GHC <= 8.8 on i386 target, you may need to set
--   -msse2 option to get correct floating-point behavior.
module Numeric.Floating.IEEE

-- | round' x returns the nearest integral value to
--   x; the even integer if x is equidistant between two
--   integers.
--   
--   IEEE 754 roundToIntegralTiesToEven operation.
--   
--   
--   \(x :: Double) -> isFinite x ==> (round' x == fromInteger (round x))
--   
--   
--   
--   >>> round' (-0.5)
--   -0.0
--   
round' :: RealFloat a => a -> a

-- | roundAway' x returns the nearest integral value to
--   x; the one with larger magnitude is returned if x is
--   equidistant between two integers.
--   
--   IEEE 754 roundToIntegralTiesToAway operation.
--   
--   
--   \(x :: Double) -> isFinite x ==> roundAway' x == fromInteger (roundAway x)
--   
--   
--   
--   >>> roundAway' (-0.5)
--   -1.0
--   
--   >>> roundAway' (-0.4)
--   -0.0
--   
roundAway' :: RealFloat a => a -> a

-- | truncate' x returns the integral value nearest to
--   x, and whose magnitude is not greater than that of
--   x.
--   
--   IEEE 754 roundToIntegralTowardZero operation.
--   
--   
--   \(x :: Double) -> isFinite x ==> truncate' x == fromInteger (truncate x)
--   
--   
--   
--   >>> truncate' (-0.5)
--   -0.0
--   
truncate' :: RealFloat a => a -> a

-- | ceiling' x returns the least integral value that is
--   not less than x.
--   
--   IEEE 754 roundToIntegralTowardPositive operation.
--   
--   
--   \(x :: Double) -> isFinite x ==> ceiling' x == fromInteger (ceiling x)
--   
--   
--   
--   >>> ceiling' (-0.8)
--   -0.0
--   
--   >>> ceiling' (-0.5)
--   -0.0
--   
ceiling' :: RealFloat a => a -> a

-- | floor' x returns the greatest integral value that is
--   not greater than x.
--   
--   IEEE 754 roundToIntegralTowardNegative operation.
--   
--   
--   \(x :: Double) -> isFinite x ==> floor' x == fromInteger (floor x)
--   
--   
--   
--   >>> floor' (-0.1)
--   -1.0
--   
--   >>> floor' (-0)
--   -0.0
--   
floor' :: RealFloat a => a -> a

-- | Returns the smallest value that is larger than the argument.
--   
--   IEEE 754 nextUp operation.
--   
--   
--   >>> nextUp 1 == (0x1.000002p0 :: Float)
--   True
--   
--   >>> nextUp 1 == (0x1.0000_0000_0000_1p0 :: Double)
--   True
--   
--   >>> nextUp (1/0) == (1/0 :: Double)
--   True
--   
--   >>> nextUp (-1/0) == (- maxFinite :: Double)
--   True
--   
--   >>> nextUp 0 == (0x1p-1074 :: Double)
--   True
--   
--   >>> nextUp (-0) == (0x1p-1074 :: Double)
--   True
--   
--   >>> nextUp (-0x1p-1074) :: Double -- returns negative zero
--   -0.0
--   
nextUp :: RealFloat a => a -> a

-- | Returns the largest value that is smaller than the argument.
--   
--   IEEE 754 nextDown operation.
--   
--   
--   >>> nextDown 1 == (0x1.ffff_ffff_ffff_fp-1 :: Double)
--   True
--   
--   >>> nextDown 1 == (0x1.fffffep-1 :: Float)
--   True
--   
--   >>> nextDown (1/0) == (maxFinite :: Double)
--   True
--   
--   >>> nextDown (-1/0) == (-1/0 :: Double)
--   True
--   
--   >>> nextDown 0 == (-0x1p-1074 :: Double)
--   True
--   
--   >>> nextDown (-0) == (-0x1p-1074 :: Double)
--   True
--   
--   >>> nextDown 0x1p-1074 -- returns positive zero
--   0.0
--   
--   >>> nextDown 0x1p-1022 == (0x0.ffff_ffff_ffff_fp-1022 :: Double)
--   True
--   
nextDown :: RealFloat a => a -> a

-- | Returns the value whose magnitude is smaller than that of the
--   argument, and is closest to the argument.
--   
--   This operation is not in IEEE, but may be useful to some.
--   
--   
--   >>> nextTowardZero 1 == (0x1.ffff_ffff_ffff_fp-1 :: Double)
--   True
--   
--   >>> nextTowardZero 1 == (0x1.fffffep-1 :: Float)
--   True
--   
--   >>> nextTowardZero (1/0) == (maxFinite :: Double)
--   True
--   
--   >>> nextTowardZero (-1/0) == (-maxFinite :: Double)
--   True
--   
--   >>> nextTowardZero 0 :: Double -- returns positive zero
--   0.0
--   
--   >>> nextTowardZero (-0 :: Double) -- returns negative zero
--   -0.0
--   
--   >>> nextTowardZero 0x1p-1074 :: Double
--   0.0
--   
nextTowardZero :: RealFloat a => a -> a

-- | remainder x y returns <math>, where <math>
--   is the integer nearest the exact number <math>; i.e.
--   <math>.
--   
--   IEEE 754 remainder operation.
remainder :: RealFloat a => a -> a -> a

-- | IEEE 754 scaleB operation, with each rounding attributes.
scaleFloatTiesToEven :: RealFloat a => Int -> a -> a

-- | IEEE 754 scaleB operation, with each rounding attributes.
scaleFloatTiesToAway :: RealFloat a => Int -> a -> a

-- | IEEE 754 scaleB operation, with each rounding attributes.
scaleFloatTowardPositive :: RealFloat a => Int -> a -> a

-- | IEEE 754 scaleB operation, with each rounding attributes.
scaleFloatTowardNegative :: RealFloat a => Int -> a -> a

-- | IEEE 754 scaleB operation, with each rounding attributes.
scaleFloatTowardZero :: RealFloat a => Int -> a -> a

-- | exponent corresponds to the second component of
--   decodeFloat. exponent 0 = 0 and for finite
--   nonzero x, exponent x = snd (decodeFloat x)
--   + floatDigits x. If x is a finite floating-point
--   number, it is equal in value to significand x * b ^^
--   exponent x, where b is the floating-point radix.
--   The behaviour is unspecified on infinite or NaN values.
exponent :: RealFloat a => a -> Int
(+) :: Num a => a -> a -> a
infixl 6 +
(-) :: Num a => a -> a -> a
infixl 6 -
(*) :: Num a => a -> a -> a
infixl 7 *

-- | Fractional division.
(/) :: Fractional a => a -> a -> a
infixl 7 /
sqrt :: Floating a => a -> a

-- | fusedMultiplyAdd a b c computes a * b + c as
--   a single, ternary operation. Rounding is done only once.
--   
--   May make use of hardware FMA instructions if the target architecture
--   has it; set fma3 package flag on x86 systems.
--   
--   IEEE 754 fusedMultiplyAdd operation.
--   
--   
--   \(a :: Double) (b :: Double) (c :: Double) -> fusedMultiplyAdd a b c == fromRational (toRational a * toRational b + toRational c)
--   
fusedMultiplyAdd :: RealFloat a => a -> a -> a -> a

-- | IEEE 754 addition operation.
genericAdd :: (RealFloat a, RealFloat b) => a -> a -> b
infixl 6 `genericAdd`

-- | IEEE 754 subtraction operation.
genericSub :: (RealFloat a, RealFloat b) => a -> a -> b
infixl 6 `genericSub`

-- | IEEE 754 multiplication operation.
genericMul :: (RealFloat a, RealFloat b) => a -> a -> b
infixl 7 `genericMul`

-- | IEEE 754 division operation.
genericDiv :: (RealFloat a, RealFloat b) => a -> a -> b
infixl 7 `genericDiv`

-- | IEEE 754 fusedMultiplyAdd operation.
genericFusedMultiplyAdd :: (RealFloat a, RealFloat b) => a -> a -> a -> b

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegerTiesToEven :: RealFloat a => Integer -> a

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegerTiesToAway :: RealFloat a => Integer -> a

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegerTowardPositive :: RealFloat a => Integer -> a

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegerTowardNegative :: RealFloat a => Integer -> a

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegerTowardZero :: RealFloat a => Integer -> a

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegralTiesToEven :: (Integral i, RealFloat a) => i -> a

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegralTiesToAway :: (Integral i, RealFloat a) => i -> a

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegralTowardPositive :: (Integral i, RealFloat a) => i -> a

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegralTowardNegative :: (Integral i, RealFloat a) => i -> a

-- | IEEE 754 convertFromInt operation, with each rounding
--   attributes.
fromIntegralTowardZero :: (Integral i, RealFloat a) => i -> a

-- | Conversion from a rational number to floating-point value, with each
--   rounding attributes.
fromRationalTiesToEven :: RealFloat a => Rational -> a

-- | Conversion from a rational number to floating-point value, with each
--   rounding attributes.
fromRationalTiesToAway :: RealFloat a => Rational -> a

-- | Conversion from a rational number to floating-point value, with each
--   rounding attributes.
fromRationalTowardPositive :: RealFloat a => Rational -> a

-- | Conversion from a rational number to floating-point value, with each
--   rounding attributes.
fromRationalTowardNegative :: RealFloat a => Rational -> a

-- | Conversion from a rational number to floating-point value, with each
--   rounding attributes.
fromRationalTowardZero :: RealFloat a => Rational -> a

-- | round x returns the nearest integer to x; the
--   even integer if x is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b

-- | roundAway x returns the nearest integer to x;
--   the integer with larger magnitude is returned if x is
--   equidistant between two integers.
--   
--   IEEE 754 convertToIntegerTiesToAway operation.
--   
--   
--   >>> roundAway 4.5
--   5
--   
roundAway :: (RealFrac a, Integral b) => a -> b

-- | truncate x returns the integer nearest x
--   between zero and x
truncate :: (RealFrac a, Integral b) => a -> b

-- | ceiling x returns the least integer not less than
--   x
ceiling :: (RealFrac a, Integral b) => a -> b

-- | floor x returns the greatest integer not greater than
--   x
floor :: (RealFrac a, Integral b) => a -> b

-- | Converts a floating-point value into another type.
--   
--   Similar to realToFrac, but treats NaN, infinities, negative
--   zero even if the rewrite rule is off.
--   
--   IEEE 754 convertFormat operation.
realFloatToFrac :: (RealFloat a, Fractional b) => a -> b

-- | A specialized version of realFloatToFrac.
--   
--   The resulting value will be canonical and non-signaling.
canonicalize :: RealFloat a => a -> a

-- | Unary negation.
negate :: Num a => a -> a

-- | Absolute value.
abs :: Num a => a -> a

-- | The classification of floating-point values.
data Class
SignalingNaN :: Class
QuietNaN :: Class
NegativeInfinity :: Class
NegativeNormal :: Class
NegativeSubnormal :: Class
NegativeZero :: Class
PositiveZero :: Class
PositiveSubnormal :: Class
PositiveNormal :: Class
PositiveInfinity :: Class

-- | Classifies a floating-point value.
--   
--   Since RealFloat constraint is insufficient to query signaling
--   status of a NaN, this function treats all NaNs as quiet. See also
--   Numeric.Floating.IEEE.NaN.
classify :: RealFloat a => a -> Class

-- | Returns True if the argument is negative (including negative
--   zero).
--   
--   Since RealFloat constraint is insufficient to query the sign of
--   NaNs, this function treats all NaNs as positive. See also
--   Numeric.Floating.IEEE.NaN.
--   
--   IEEE 754 isSignMinus operation.
isSignMinus :: RealFloat a => a -> Bool

-- | IEEE 754 isNormal operation.
isNormal :: RealFloat a => a -> Bool

-- | Returns True if the argument is normal, subnormal, or zero.
--   
--   IEEE 754 isFinite operation.
isFinite :: RealFloat a => a -> Bool

-- | Returns True if the argument is zero.
--   
--   IEEE 754 isZero operation.
isZero :: RealFloat a => a -> Bool

-- | True if the argument is too small to be represented in
--   normalized format
isDenormalized :: RealFloat a => a -> Bool

-- | True if the argument is an IEEE infinity or negative infinity
isInfinite :: RealFloat a => a -> Bool

-- | True if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: RealFloat a => a -> Bool

-- | a constant function, returning the radix of the representation (often
--   2)
floatRadix :: RealFloat a => a -> Integer

-- | Comparison with IEEE 754 totalOrder predicate.
--   
--   Floating-point numbers are ordered as, <math>.
--   
--   Since RealFloat constraint is insufficient to query the sign
--   and payload of NaNs, this function treats all NaNs as positive and
--   does not make distinction between them. See also
--   Numeric.Floating.IEEE.NaN.
--   
--   Also, for the same reason, this function cannot distinguish the
--   members of a cohort.
compareByTotalOrder :: RealFloat a => a -> a -> Ordering

-- | Comparison with IEEE 754 totalOrderMag predicate.
--   
--   Equivalent to compareByTotalOrder (abs x) (abs y).
compareByTotalOrderMag :: RealFloat a => a -> a -> Ordering

-- | IEEE 754 augmentedAddition operation.
--   
--   The first return value is the approximation of the sum, and the second
--   return value is the error.
--   
--   
--   fst (augmentedAddition x y) == roundTiesTowardZero (fromRationalR (toRational x + toRational y)) `const` (x :: Double)
--   
--   
--   
--   let (u, v) = augmentedAddition x y in toRational u + toRational v == toRational x + toRational y `const` (x :: Double)
--   
augmentedAddition :: RealFloat a => a -> a -> (a, a)

-- | IEEE 754 augmentedSubtraction operation.
--   
--   The first return value is the approximation of the difference, and the
--   second return value is the error.
--   
--   
--   fst (augmentedSubtraction x y) == roundTiesTowardZero (fromRationalR (toRational x - toRational y)) `const` (x :: Double)
--   
--   
--   
--   let (u, v) = augmentedSubtraction x y in toRational u + toRational v == toRational x - toRational y `const` (x :: Double)
--   
augmentedSubtraction :: RealFloat a => a -> a -> (a, a)

-- | IEEE 754 augmentedMultiplication operation.
--   
--   The first return value is the approximation of the product, and the
--   second return value is the error.
--   
--   
--   fst (augmentedMultiplication x y) == roundTiesTowardZero (fromRationalR (toRational x * toRational y)) `const` (x :: Double)
--   
--   
--   
--   let (u, v) = augmentedMultiplication x y in toRational u + toRational v == toRational x * toRational y `const` (x :: Double)
--   
augmentedMultiplication :: RealFloat a => a -> a -> (a, a)

-- | IEEE 754 minimum operation. -0 is smaller than
--   +0. Propagates NaNs.
minimum' :: RealFloat a => a -> a -> a

-- | IEEE 754 minimumNumber operation. -0 is smaller than
--   +0. Treats NaNs as missing data.
minimumNumber :: RealFloat a => a -> a -> a

-- | IEEE 754 maximum operation. -0 is smaller than
--   +0. Propagates NaNs.
maximum' :: RealFloat a => a -> a -> a

-- | IEEE 754 maximumNumber operation. -0 is smaller than
--   +0. Treats NaNs as missing data.
maximumNumber :: RealFloat a => a -> a -> a

-- | IEEE 754 minimumMagnitude operation.
minimumMagnitude :: RealFloat a => a -> a -> a

-- | IEEE 754 minimumMagnitudeNumber operation.
minimumMagnitudeNumber :: RealFloat a => a -> a -> a

-- | IEEE 754 maximumMagnitude operation.
maximumMagnitude :: RealFloat a => a -> a -> a

-- | IEEE 754 maximumMagnitudeNumber operation.
maximumMagnitudeNumber :: RealFloat a => a -> a -> a

-- | The smallest positive value expressible in an IEEE floating-point
--   format. This value is subnormal.
--   
--   
--   >>> (minPositive :: Float) == 0x1p-149
--   True
--   
--   >>> (minPositive :: Double) == 0x1p-1074
--   True
--   
--   >>> nextDown (minPositive :: Float)
--   0.0
--   
--   >>> nextDown (minPositive :: Double)
--   0.0
--   
minPositive :: RealFloat a => a

-- | The smallest positive normal value expressible in an IEEE
--   floating-point format.
--   
--   
--   >>> (minPositiveNormal :: Float) == 0x1p-126
--   True
--   
--   >>> (minPositiveNormal :: Double) == 0x1p-1022
--   True
--   
--   >>> isDenormalized (minPositiveNormal :: Float)
--   False
--   
--   >>> isDenormalized (minPositiveNormal :: Double)
--   False
--   
--   >>> isDenormalized (nextDown (minPositiveNormal :: Float))
--   True
--   
--   >>> isDenormalized (nextDown (minPositiveNormal :: Double))
--   True
--   
minPositiveNormal :: RealFloat a => a

-- | The largest finite value expressible in an IEEE floating-point format.
--   
--   
--   >>> (maxFinite :: Float) == 0x1.fffffep+127
--   True
--   
--   >>> (maxFinite :: Double) == 0x1.ffff_ffff_ffff_fp+1023
--   True
--   
maxFinite :: RealFloat a => a

-- | This module provides the typeclass for NaN manipulation:
--   RealFloatNaN.
--   
--   In addition to Float and Double, a couple of
--   floating-point types provided by third-party libraries can be
--   supported via package flags: Half via half and
--   Float128 via float128.
module Numeric.Floating.IEEE.NaN

-- | An instance of this class supports manipulation of NaN.
class RealFloat a => RealFloatNaN a

-- | Returns the first operand, with the sign of the second.
--   
--   IEEE 754 copySign operation.
copySign :: RealFloatNaN a => a -> a -> a

-- | Returns True if the operand is a negative number, negative
--   infinity, negative zero, or a NaN with negative sign bit.
--   
--   IEEE 754 isSignMinus operation.
isSignMinus :: RealFloatNaN a => a -> Bool

-- | Returns True if the operand is a signaling NaN.
--   
--   IEEE 754 isSignaling operation.
--   
--   Warning: GHC's optimizer is not aware of signaling NaNs.
isSignaling :: RealFloatNaN a => a -> Bool

-- | Returns the payload of a NaN. Returns -1 if the operand is
--   not a NaN.
--   
--   IEEE 754 getPayload operation.
getPayload :: RealFloatNaN a => a -> a

-- | Returns a quiet NaN with a given payload. Returns a positive zero if
--   the payload is invalid.
--   
--   IEEE 754 setPayload operation.
setPayload :: RealFloatNaN a => a -> a

-- | Returns a signaling NaN with a given payload. Returns a positive zero
--   if the payload is invalid.
--   
--   IEEE 754 setPayloadSignaling operation.
setPayloadSignaling :: RealFloatNaN a => a -> a

-- | IEEE 754 class operation.
classify :: RealFloatNaN a => a -> Class

-- | Equality with IEEE 754 totalOrder operation.
equalByTotalOrder :: RealFloatNaN a => a -> a -> Bool

-- | Comparison with IEEE 754 totalOrder operation.
--   
--   Floating-point numbers should be ordered as, <math>.
compareByTotalOrder :: RealFloatNaN a => a -> a -> Ordering

-- | The classification of floating-point values.
data Class
SignalingNaN :: Class
QuietNaN :: Class
NegativeInfinity :: Class
NegativeNormal :: Class
NegativeSubnormal :: Class
NegativeZero :: Class
PositiveZero :: Class
PositiveSubnormal :: Class
PositiveNormal :: Class
PositiveInfinity :: Class

-- | A newtype wrapper to compare floating-point numbers by
--   totalOrder predicate.
newtype TotallyOrdered a
TotallyOrdered :: a -> TotallyOrdered a
