# 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

Substract `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 : float

    val max_num : 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 `BatFloat.atan2`.

    val sin : float -> float

See `BatFloat.atan2`.

    val tan : float -> float

See `BatFloat.atan2`.

    val acos : float -> float

See `BatFloat.atan2`.

    val asin : float -> float

See `BatFloat.atan2`.

    val atan : float -> float

See `BatFloat.atan2`.

    val atan2 : float -> float -> float

The usual trigonometric functions.

    val cosh : float -> float

See `BatFloat.tanh`.

    val sinh : float -> float

See `BatFloat.tanh`.

    val tanh : float -> float

The usual hyperbolic trigonometric functions.

    val ceil : float -> float

See `BatFloat.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.
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 = 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

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