Relude.Numeric

Attempt to convert an Integral type a to an Integral type b using the size of the types as measured by Bits methods.

A simpler version of this function is:

toIntegral :: (Integral a, Integral b) => a -> Maybe b
toIntegral x
  | toInteger x == toInteger y = Just y
  | otherwise                  = Nothing
  where
    y = fromIntegral x

This version requires going through Integer, which can be inefficient. However, toIntegralSized is optimized to allow GHC to statically determine the relative type sizes (as measured by bitSizeMaybe and isSigned) and avoid going through Integer for many types. (The implementation uses fromIntegral, which is itself optimized with rules for base types but may go through Integer for some type pairs.)

Bitwise "xor"

A fixed-precision integer type with at least the range [-2^29 .. 2^29-1]. The exact range for a given implementation can be determined by using Prelude.minBound and Prelude.maxBound from the Prelude.Bounded class.

16-bit signed integer type

32-bit signed integer type

64-bit signed integer type

8-bit signed integer type

8-bit unsigned integer type

A Word is an unsigned integral type, with the same size as Int.

16-bit unsigned integer type

32-bit unsigned integer type

64-bit unsigned integer type

Reverse order of bytes in Word16.

Reverse order of bytes in Word32.

Reverse order of bytes in Word64.

Double-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE double-precision type.

Single-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE single-precision type.

Trigonometric and hyperbolic functions and related functions.

The Haskell Report defines no laws for Floating. However, (+), (*) and exp are customarily expected to define an exponential field and have the following properties:

• exp (a + b) = exp a * exp b

• exp (fromInteger 0) = fromInteger 1

Efficient, machine-independent access to the components of a floating-point number.

Basic numeric class.

The Haskell Report defines no laws for Num. However, (+) and (*) are customarily expected to define a ring and have the following properties:

Associativity of (+)

(x + y) + z

=

x + (y + z)

Commutativity of (+)

x + y

=

y + x

fromInteger 0 is the additive identity

x + fromInteger 0

=

x

negate gives the additive inverse

x + negate x

=

fromInteger 0

Associativity of (*)

(x * y) * z

=

x * (y * z)

fromInteger 1 is the multiplicative identity

x * fromInteger 1

=

x

and

fromInteger 1 * x

=

x

Distributivity of (*) with respect to (+)

a * (b + c)

=

(a * b) + (a * c)

and

(b + c) * a

=

(b * a) + (c * a)

Coherence with toInteger

if the type also implements

GHC.Real.Integral

, then

fromInteger

is a left inverse for

toInteger

, i.e.

fromInteger (toInteger i) == i

Note that it isn't customarily expected that a type instance of both Num and Ord implement an ordered ring. Indeed, in base only Integer and Rational do.

Arbitrary precision integers. In contrast with fixed-size integral types such as Int, the Integer type represents the entire infinite range of integers.

Integers are stored in a kind of sign-magnitude form, hence do not expect two's complement form when using bit operations.

If the value is small (i.e., fits into an Int), the IS constructor is used. Otherwise IP and IN constructors are used to store a BigNat representing the positive or the negative value magnitude, respectively.

Invariant: IP and IN are used iff the value does not fit in IS.

the same as flip (-).

Because - is treated specially in the Haskell grammar, (- e) is not a section, but an application of prefix negation. However, (subtract exp) is equivalent to the disallowed section.

Real numbers.

The Haskell report defines no laws for Real, however Real instances are customarily expected to adhere to the following law:

Coherence with fromRational

if the type also implements

Fractional

, then

fromRational

is a left inverse for

toRational

, i.e.

fromRational (toRational i) = i

The law does not hold for Float, Double, CFloat, CDouble, etc., because these types contain non-finite values, which cannot be roundtripped through Rational.

Fractional numbers, supporting real division.

The Haskell Report defines no laws for Fractional. However, (+) and (*) are customarily expected to define a division ring and have the following properties:

recip gives the multiplicative inverse

x * recip x

=

recip x * x

=

fromInteger 1

Totality of toRational

toRational

is total

Coherence with toRational

if the type also implements

Real

, then

fromRational

is a left inverse for

toRational

, i.e.

fromRational (toRational i) = i

Note that it isn't customarily expected that a type instance of Fractional implement a field. However, all instances in base do.

Integral numbers, supporting integer division.

The Haskell Report defines no laws for Integral. However, Integral instances are customarily expected to define a Euclidean domain and have the following properties for the div/mod and quot/rem pairs, given suitable Euclidean functions f and g:

• x = y * quot x y + rem x y with rem x y = fromInteger 0 or g (rem x y) < g y

• x = y * div x y + mod x y with mod x y = fromInteger 0 or f (mod x y) < f y

An example of a suitable Euclidean function, for Integer's instance, is abs.

In addition, toInteger should be total, and fromInteger should be a left inverse for it, i.e. fromInteger (toInteger i) = i.

Rational numbers, with numerator and denominator of some Integral type.

Note that Ratio's instances inherit the deficiencies from the type parameter's. For example, Ratio Natural's Num instance has similar problems to Numeric.Natural.Natural's.

Arbitrary-precision rational numbers, represented as a ratio of two Integer values. A rational number may be constructed using the % operator.

Extracting components of fractions.

Extract the denominator of the ratio in reduced form: the numerator and denominator have no common factor and the denominator is positive.

General coercion from Integral types.

WARNING: This function performs silent truncation if the result type is not at least as big as the argument's type.

gcd x y is the non-negative factor of both x and y of which every common factor of x and y is also a factor; for example gcd 4 2 = 2, gcd (-4) 6 = 2, gcd 0 4 = 4. gcd 0 0 = 0. (That is, the common divisor that is "greatest" in the divisibility preordering.)

Note: Since for signed fixed-width integer types, abs minBound < 0, the result may be negative if one of the arguments is minBound (and necessarily is if the other is 0 or minBound) for such types.

lcm x y is the smallest positive integer that both x and y divide.

Extract the numerator of the ratio in reduced form: the numerator and denominator have no common factor and the denominator is positive.

General coercion to Fractional types.

WARNING: This function goes through the Rational type, which does not have values for NaN for example. This means it does not round-trip.

For Double it also behaves differently with or without -O0:

Prelude> realToFrac nan -- With -O0
-Infinity
Prelude> realToFrac nan
NaN

raise a number to a non-negative integral power

raise a number to an integral power

Natural number

Invariant: numbers <= 0xffffffffffffffff use the NS constructor

Transforms an integer number to a bounded integral. It returns Nothing for integers outside the bound of the return type.

>>> integerToBounded @Int 42Just 42

>>> integerToBounded @Int8 1024Nothing

>>> integerToBounded @Int (toInteger (minBound :: Int))Just (-9223372036854775808)>>> integerToBounded @Int $ (toInteger (minBound :: Int)) - 1Nothing

>>> integerToBounded @Int (toInteger (maxBound :: Int))Just 9223372036854775807>>> integerToBounded @Int $ (toInteger (maxBound :: Int)) + 1Nothing

If you want to convert Int or Word to a bounded type, take a look at toIntegralSized function instead.

Transforms an integer number to a natural. Only non-negative integers are considered natural, everything else will return Nothing.

>>> integerToNatural (-1)Nothing

>>> integerToNatural 0Just 0

>>> integerToNatural 10Just 10