`module Pervasives := Stdlib`

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 Gabriel Scherer

- author David Teller

- author Edgar Friendly

@documents Float

`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 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`

See `atan2`.

`val sin : float -> float`

See `atan2`.

`val tan : float -> float`

See `atan2`.

`val acos : float -> float`

See `atan2`.

`val asin : float -> float`

See `atan2`.

`val atan : float -> float`

See `atan2`.

`val atan2 : float -> float -> float`

The usual trigonometric functions.

`val cosh : float -> float`

See `tanh`.

`val sinh : float -> float`

See `tanh`.

`val tanh : float -> float`

The usual hyperbolic trigonometric functions.

`val ceil : float -> float`

See `floor`.

`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.

- 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.

- since 2.0

`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`

- returns

  True if the sign bit of `x` is set. This usually indicates thet `x` is negative.

- since 2.0

`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 = Pervasives.fpclass =`

1. `| FP_normal`
   (*

   Normal number, none of the below

   *)
2. `| FP_subnormal`
   (*

   Number very close to 0.0, has reduced precision

   *)
3. `| FP_zero`
   (*

   Number is 0.0 or -0.0

   *)
4. `| FP_infinite`
   (*

   Number is positive or negative infinity

   *)
5. `| 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 `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 with type bat__refops_t = t`
`type bat__refops_t = t`
`val (+=) : bat__refops_t Stdlib.ref -> bat__refops_t -> unit`
`val (-=) : bat__refops_t Stdlib.ref -> bat__refops_t -> unit`
`val (*=) : bat__refops_t Stdlib.ref -> bat__refops_t -> unit`
`val (/=) : bat__refops_t Stdlib.ref -> bat__refops_t -> unit`
`include BatNumber.Bounded with type bounded = t`
`type bounded = t`
`val min_num : bounded`
`val max_num : bounded`

## Boilerplate code

`val print : (t, _) BatIO.printer`

Printing

`module Safe_float : sig ... end`

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