# Module BatFloat

`module BatFloat: `sig` .. `end``

Operations on floating-point numbers.

OCaml's floating-point numbers follow the IEEE 754 standard, using double precision (64 bits) numbers. Floating-point operations never raise an exception on overflow, underflow, division by zero, etc. Instead, special IEEE numbers are returned as appropriate, such as `infinity` for `1.0 /. 0.0`, `neg_infinity` for `-1.0 /. 0.0`, and `nan` (``not a number'') for `0.0 /. 0.0`. These special numbers then propagate through floating-point computations as expected: for instance, `1.0 /. infinity` is `0.0`, and any operation with `nan` as argument returns `nan` as result.

For more precision, see The Wikipedia entry on standard IEEE 754.

• Author(s): Gabriel Scherer, David Teller, Edgar Friendly

`type t = `float` `

The type of floating-point numbers.

Floating-point numbers are the default representation of real numbers by OCaml.

Usual operations
`val zero : `float``

Floating number zero. This is the same thing as `0.`

`val one : `float``

Floating number one. This is the same thing as `1.`

`val neg : `float -> float``

Returns the negation of the input, i.e. (fun x -> ~-. x)

`val succ : `float -> float``

Add `1.` to a floating number. Note that, as per IEEE 754, if `x` is a large enough float number, `succ x` might be equal to `x`, due to rounding.

`val pred : `float -> float``

Subtract `1.` from a floating number. Note that, as per IEEE 754, if `x` is a large enough float number, `pred x` might be equal to `x`, due to rounding.

`val abs : `float -> float``

The absolute value of a floating point number.

`val add : `float -> float -> float``
`val sub : `float -> float -> float``
`val mul : `float -> float -> float``
`val div : `float -> float -> float``
`val modulo : `float -> float -> float``
`val pow : `float -> float -> float``
`val min_num : `bounded``
`val max_num : `bounded``
`val compare : `float -> float -> int``
`val equal : `float -> float -> bool``
`val ord : `float -> float -> BatOrd.order``
`val of_int : `int -> float``
`val to_int : `float -> int``
`val of_float : `float -> float``
`val to_float : `float -> float``
`val of_string : `string -> float``
`val to_string : `float -> string``
`val (+) : `t -> t -> t``
`val (-) : `t -> t -> t``
`val ( * ) : `t -> t -> t``
`val (/) : `t -> t -> t``
`val ( ** ) : `t -> t -> t``
`val min : `float -> float -> float``
`val max : `float -> float -> float``
`val (--) : `t -> t -> t BatEnum.t``
`val (---) : `t -> t -> t BatEnum.t``
`val operations : `t BatNumber.numeric``
Operations specific to floating-point numbers
`val sqrt : `float -> float``

Square root.

`val exp : `float -> float``

Exponential.

`val log : `float -> float``

Natural logarithm.

`val log10 : `float -> float``

Base 10 logarithm.

`val cos : `float -> float``
`val sin : `float -> float``
`val tan : `float -> float``
`val acos : `float -> float``
`val asin : `float -> float``
`val atan : `float -> float``
`val atan2 : `float -> float -> float``

The usual trigonometric functions.

`val cosh : `float -> float``
`val sinh : `float -> float``
`val tanh : `float -> float``

The usual hyperbolic trigonometric functions.

`val ceil : `float -> float``
`val floor : `float -> float``

Round the given float to an integer value. `floor f` returns the greatest integer value less than or equal to `f`. `ceil f` returns the least integer value greater than or equal to `f`.

`val round : `float -> float``

`round x` rounds `x` to the nearest integral floating-point (the nearest of `floor x` and `ceil x`). In case the fraction of x is exactly 0.5, we round away from 0. : `round 1.5` is `2.` but `round (-3.5)` is `-4.`.

`val round_to_int : `float -> int``

`round_to_int x` is `int_of_float (round x)`.

• Since 2.0
`val round_to_string : `?digits:int -> float -> string``

`round_to_string ~digits:d x` will return a string representation of `x` -- in base 10 -- rounded to `d` digits after the decimal point. By default, `digits` is `0`, we round to the nearest integer.

• Since 2.0
• Raises `Invalid_argument` if the ~digits argument is negative. This is strictly a convenience function for simple end-user printing and you should not rely on its behavior. One possible implementation is to rely on C `sprintf` internally, which means:
• no guarantee is given on the round-at-half behavior; it may not be consistent with `round` or `round_to_int`
• `round_to_string ~digits:0 3.` may return "3" instead of "3." as `string_of_float` would
• no guarantee is given on the behavior for abusively high number of digits precision; for example ```round_to_string     ~digits:max_int x``` may return the empty string.
`val root : `float -> int -> float``

`root x n` calculates the nth root of x.

• Raises `Invalid_argument` if n is negative or if the result would be imaginary
`val signbit : `float -> bool``
• Since 2.0
• Returns True if the sign bit of `x` is set. This usually indicates thet `x` is negative.
`val copysign : `float -> float -> float``

`copysign x y` returns a copy of `x` with the same sign as `y`.

• Since 2.0
`val is_nan : `float -> bool``

`is_nan f` returns `true` if `f` is `nan`, `false` otherwise.

`val is_special : `float -> bool``

`is_special f` returns `true` if `f` is `nan` or `+/- infinity`, `false` otherwise.

• Since 2.0
`val is_finite : `float -> bool``

`is_finite f` returns `true` if `f` is not `nan` or `+/- infinity`, `false` otherwise.

• Since 2.0
Constants

Special float constants. It may not be safe to compare directly with these, as they have multiple internal representations. Instead use the `is_special`, `is_nan`, etc. tests

`val infinity : `float``

Positive infinity.

`val neg_infinity : `float``

Negative infinity.

`val nan : `float``

A special floating-point value denoting the result of an undefined operation such as `0.0 /. 0.0`. Stands for ``not a number''. Any floating-point operation with `nan` as argument returns `nan` as result. As for floating-point comparisons, `=`, `<`, `<=`, `>` and `>=` return `false` and `<>` returns `true` if one or both of their arguments is `nan`.

Numeric constants

`val epsilon : `float``

The smallest positive float `x` such that `1.0 +. x <> 1.0`.

`val e : `float``

Euler? ... Euler? ... Euler?

• Since 2.0
`val log2e : `float``

`Math.log2 e`

• Since 2.0
`val log10e : `float``

`log10 e`

• Since 2.0
`val ln2 : `float``

`log 2`

• Since 2.0
`val ln10 : `float``

`log 10`

• Since 2.0
`val pi : `float``

The constant pi (3.14159...)

`val pi2 : `float``

`pi /. 2.`

• Since 2.0
`val pi4 : `float``

`pi /. 4.`

• Since 2.0
`val invpi : `float``

`1. /. pi`

• Since 2.0
`val invpi2 : `float``

`2. /. pi`

• Since 2.0
`val sqrtpi2 : `float``

`2. *. sqrt pi`

• Since 2.0
`val sqrt2 : `float``

`sqrt 2.`

• Since 2.0
`val invsqrt2 : `float``

`1. /. sqrt 2.`

• Since 2.0
Operations on the internal representation of floating-point numbers
`val frexp : `float -> float * int``

`frexp f` returns the pair of the significant and the exponent of `f`. When `f` is zero, the significant `x` and the exponent `n` of `f` are equal to zero. When `f` is non-zero, they are defined by `f = x *. 2 ** n` and `0.5 <= x < 1.0`.

`val ldexp : `float -> int -> float``

`ldexp x n` returns `x *. 2 ** n`.

`val modf : `float -> float * float``

`modf f` returns the pair of the fractional and integral part of `f`.

`type fpkind = `Stdlib.Pervasives.fpclass` = `
 `|` `FP_normal` `(*` Normal number, none of the below `*)` `|` `FP_subnormal` `(*` Number very close to 0.0, has reduced precision `*)` `|` `FP_zero` `(*` Number is 0.0 or -0.0 `*)` `|` `FP_infinite` `(*` Number is positive or negative infinity `*)` `|` `FP_nan` `(*` Not a number: result of an undefined operation `*)`

Classes of floating point numbers

The five classes of floating-point numbers, as determined by the `BatFloat.classify` function.

`val classify : `float -> fpkind``

Return the class of the given floating-point number: normal, subnormal, zero, infinite, or not a number.

`val approx_equal : `?epsilon:float -> float -> float -> bool``

Test whether two floats are approximately equal (i.e. within epsilon of each other). `epsilon` defaults to 1e-5.

Submodules grouping all infix operators
`module Infix: `sig` .. `end``
`module Compare: `BatNumber.Compare``  with type bat__compare_t = t``
`include BatNumber.RefOps`
`include BatNumber.Bounded`
Boilerplate code
`val print : `(t, 'a) BatIO.printer``
Printing
`module Safe_float: `sig` .. `end``

Operations on floating-point numbers, with exceptions raised in case of error.