Safe Haskell	None
Language	Haskell2010

Numeric.Floating.IEEE

Contents

Standard Haskell classes
5.3 Homogeneous general-computational operations
5.4 formatOf general-computational operations
- 5.4.1 Arithmetic operations
- 5.4.2 Conversion operations for floating-point formats and decimal character sequences
5.4.3 Conversion operations for binary formats
5.5 Quiet-computational operations
- 5.5.1 Sign bit operations
- 5.5.2 Decimal re-encoding operations (not supported)
5.6 Signaling-computational operations
- 5.6.1 Comparisons (not supported)
5.7 Non-computational operations
9. Recommended operations
9.5 Augmented arithmetic operations
9.6 Minimum and maximum operations
Floating-point constants

Description

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.

Synopsis

round' :: RealFloat a => a -> a
roundAway' :: RealFloat a => a -> a
truncate' :: RealFloat a => a -> a
ceiling' :: RealFloat a => a -> a
floor' :: RealFloat a => a -> a
nextUp :: RealFloat a => a -> a
nextDown :: RealFloat a => a -> a
nextTowardZero :: RealFloat a => a -> a
remainder :: RealFloat a => a -> a -> a
scaleFloatTiesToEven :: RealFloat a => Int -> a -> a
scaleFloatTiesToAway :: RealFloat a => Int -> a -> a
scaleFloatTowardPositive :: RealFloat a => Int -> a -> a
scaleFloatTowardNegative :: RealFloat a => Int -> a -> a
scaleFloatTowardZero :: RealFloat a => Int -> a -> a
exponent :: RealFloat a => a -> Int
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
(*) :: Num a => a -> a -> a
(/) :: Fractional a => a -> a -> a
sqrt :: Floating a => a -> a
fusedMultiplyAdd :: RealFloat a => a -> a -> a -> a
genericAdd :: (RealFloat a, RealFloat b) => a -> a -> b
genericSub :: (RealFloat a, RealFloat b) => a -> a -> b
genericMul :: (RealFloat a, RealFloat b) => a -> a -> b
genericDiv :: (RealFloat a, RealFloat b) => a -> a -> b
genericFusedMultiplyAdd :: (RealFloat a, RealFloat b) => a -> a -> a -> b
fromIntegerTiesToEven :: RealFloat a => Integer -> a
fromIntegerTiesToAway :: RealFloat a => Integer -> a
fromIntegerTowardPositive :: RealFloat a => Integer -> a
fromIntegerTowardNegative :: RealFloat a => Integer -> a
fromIntegerTowardZero :: RealFloat a => Integer -> a
fromIntegralTiesToEven :: (Integral i, RealFloat a) => i -> a
fromIntegralTiesToAway :: (Integral i, RealFloat a) => i -> a
fromIntegralTowardPositive :: (Integral i, RealFloat a) => i -> a
fromIntegralTowardNegative :: (Integral i, RealFloat a) => i -> a
fromIntegralTowardZero :: (Integral i, RealFloat a) => i -> a
fromRationalTiesToEven :: RealFloat a => Rational -> a
fromRationalTiesToAway :: RealFloat a => Rational -> a
fromRationalTowardPositive :: RealFloat a => Rational -> a
fromRationalTowardNegative :: RealFloat a => Rational -> a
fromRationalTowardZero :: RealFloat a => Rational -> a
round :: (RealFrac a, Integral b) => a -> b
roundAway :: (RealFrac a, Integral b) => a -> b
truncate :: (RealFrac a, Integral b) => a -> b
ceiling :: (RealFrac a, Integral b) => a -> b
floor :: (RealFrac a, Integral b) => a -> b
realFloatToFrac :: (RealFloat a, Fractional b) => a -> b
canonicalize :: RealFloat a => a -> a
negate :: Num a => a -> a
abs :: Num a => a -> a
data Class
- = SignalingNaN
- | QuietNaN
- | NegativeInfinity
- | NegativeNormal
- | NegativeSubnormal
- | NegativeZero
- | PositiveZero
- | PositiveSubnormal
- | PositiveNormal
- | PositiveInfinity
classify :: RealFloat a => a -> Class
isSignMinus :: RealFloat a => a -> Bool
isNormal :: RealFloat a => a -> Bool
isFinite :: RealFloat a => a -> Bool
isZero :: RealFloat a => a -> Bool
isDenormalized :: RealFloat a => a -> Bool
isInfinite :: RealFloat a => a -> Bool
isNaN :: RealFloat a => a -> Bool
floatRadix :: RealFloat a => a -> Integer
compareByTotalOrder :: RealFloat a => a -> a -> Ordering
compareByTotalOrderMag :: RealFloat a => a -> a -> Ordering
augmentedAddition :: RealFloat a => a -> a -> (a, a)
augmentedSubtraction :: RealFloat a => a -> a -> (a, a)
augmentedMultiplication :: RealFloat a => a -> a -> (a, a)
minimum' :: RealFloat a => a -> a -> a
minimumNumber :: RealFloat a => a -> a -> a
maximum' :: RealFloat a => a -> a -> a
maximumNumber :: RealFloat a => a -> a -> a
minimumMagnitude :: RealFloat a => a -> a -> a
minimumMagnitudeNumber :: RealFloat a => a -> a -> a
maximumMagnitude :: RealFloat a => a -> a -> a
maximumMagnitudeNumber :: RealFloat a => a -> a -> a
minPositive :: RealFloat a => a
minPositiveNormal :: RealFloat a => a
maxFinite :: RealFloat a => a

Standard Haskell classes

This library assumes that some of the standard numeric functions correspond to the operations specified by IEEE. The rounding attribute should be roundTiesToEven and the exceptional behavior should be the default one.

`Num`

(+), (-), and (*) should be correctly-rounding.
negate, abs should comply with IEEE semantics.
fromInteger should be correctly-rounding, but unfortunately not for Float and Double (see GHC's #17231). This module provides a correctly-rounding alternative: fromIntegerTiesToEven.

`Fractional`

(/) should be correctly-rounding.
fromRational should be correctly-rounding, but some third-partiy floating-point types fail to do so.

`Floating`

sqrt should be correctly-rounding.

`RealFrac`

truncate: IEEE 754 convertToIntegerTowardZero operation.
round: IEEE 754 convertToIntegerTiesToEven operation; the Language Report says that this should choose the even integer if the argument is the midpoint of two successive integers.
ceiling: IEEE 754 convertToIntegerTowardPositive operation.
floor: IEEE 754 convertToIntegerTowardNegative operation.

To complete these, roundAway is provided by this library. Note that Haskell's round is specified to be ties-to-even, whereas C's round is ties-to-away.

`RealFloat`

This class provides information on the IEEE-compliant format.

floatRadix: The base \(b\). IEEE 754 radix operation.
floatDigits: The precision \(p\).
floatRange: The exponent range offset by 1: \((\mathit{emin}+1,\mathit{emax}+1)\)
decodeFloat x: The exponent part returned is in the range \([\mathit{emin}+1-p,\mathit{emax}+1-p]\) if x is normal, or in \([\mathit{emin}-2p+2,\mathit{emin}-p]\) if x is subnormal.
encodeFloat should accept the significand in the range [0, floatRadix x ^ floatDigits x]. This library does not assume a particular rounding behavior when the result cannot be expressed in the target type.
exponent x: The exponent offset by 1: \(\mathrm{logB}(x)+1\). Returns an integer in \([\mathit{emin}+1,\mathit{emax}+1]\) if x is normal, or in \([\mathit{emin}-p+2,\mathit{emin}]\) if x is subnormal.
significand x: Returns the significand of x as a value between \([1/b,1)\).
scaleFloat: This library does not assume a particular rounding behavior when the result is subnormal.
isNaN
isInfinite
isDenormalized
isNegativeZero
isIEEE should return True if you are using the type with this library.

5.3 Homogeneous general-computational operations

5.3.1 General operations

round' :: RealFloat a => a -> a Source #

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

roundAway' :: RealFloat a => a -> a Source #

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

truncate' :: RealFloat a => a -> a Source #

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

ceiling' :: RealFloat a => a -> a Source #

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

floor' :: RealFloat a => a -> a Source #

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

nextUp :: RealFloat a => a -> a Source #

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

nextDown :: RealFloat a => a -> a Source #

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

nextTowardZero :: RealFloat a => a -> a Source #

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

remainder :: RealFloat a => a -> a -> a Source #

remainder x y returns \(r=x-yn\), where \(n\) is the integer nearest the exact number \(x/y\); i.e. \(n=\mathrm{round}(x/y)\).

IEEE 754 remainder operation.

5.3.2 Decimal operations (not supported)

Not supported.

5.3.3 logBFormat operations

scaleFloatTiesToEven :: RealFloat a => Int -> a -> a Source #

IEEE 754 scaleB operation, with each rounding attributes.

scaleFloatTiesToAway :: RealFloat a => Int -> a -> a Source #

IEEE 754 scaleB operation, with each rounding attributes.

scaleFloatTowardPositive :: RealFloat a => Int -> a -> a Source #

IEEE 754 scaleB operation, with each rounding attributes.

scaleFloatTowardNegative :: RealFloat a => Int -> a -> a Source #

IEEE 754 scaleB operation, with each rounding attributes.

scaleFloatTowardZero :: RealFloat a => Int -> a -> a Source #

IEEE 754 scaleB operation, with each rounding attributes.

The Haskell counterpart for IEEE 754 logB operation is exponent. Note that logB and exponent are different by one: logB x = exponent x - 1

exponent :: RealFloat a => a -> Int #

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.

5.4 formatOf general-computational operations

5.4.1 Arithmetic operations

For IEEE-compliant floating-point types, (+), (-), (*), (/), and sqrt from Prelude should be correctly-rounding. fusedMultiplyAdd is provided by this library. This library also provides "generic" version of the arithmetic operations, which can be useful if the target type is narrower than source.

(+) :: Num a => a -> a -> a infixl 6 #

(-) :: Num a => a -> a -> a infixl 6 #

(*) :: Num a => a -> a -> a infixl 7 #

(/) :: Fractional a => a -> a -> a infixl 7 #

Fractional division.

sqrt :: Floating a => a -> a #

fusedMultiplyAdd :: RealFloat a => a -> a -> a -> a Source #

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)

genericAdd :: (RealFloat a, RealFloat b) => a -> a -> b infixl 6 Source #

IEEE 754 addition operation.

genericSub :: (RealFloat a, RealFloat b) => a -> a -> b infixl 6 Source #

IEEE 754 subtraction operation.

genericMul :: (RealFloat a, RealFloat b) => a -> a -> b infixl 7 Source #

IEEE 754 multiplication operation.

genericDiv :: (RealFloat a, RealFloat b) => a -> a -> b infixl 7 Source #

IEEE 754 division operation.

genericSqrt is not implemented yet.

genericFusedMultiplyAdd :: (RealFloat a, RealFloat b) => a -> a -> a -> b Source #

IEEE 754 fusedMultiplyAdd operation.

fromIntegerTiesToEven :: RealFloat a => Integer -> a Source #