# Float.3o - Man Page

Floating-point arithmetic.

## Module

Module Float

## Documentation

Module **Float**

: **sig end**

Floating-point arithmetic.

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** , basic arithmetic operations ( **+.** , **-.** , ***.** , **/.** ) with **nan** as an argument return **nan** , ...

**Since** 4.07.0

*val zero* : **float**

The floating point 0.

**Since** 4.08.0

*val one* : **float**

The floating-point 1.

**Since** 4.08.0

*val minus_one* : **float**

The floating-point -1.

**Since** 4.08.0

*val neg* : **float -> float**

Unary negation.

*val add* : **float -> float -> float**

Floating-point addition.

*val sub* : **float -> float -> float**

Floating-point subtraction.

*val mul* : **float -> float -> float**

Floating-point multiplication.

*val div* : **float -> float -> float**

Floating-point division.

*val fma* : **float -> float -> float -> float**

**fma x y z** returns **x * y + z** , with a best effort for computing this expression with a single rounding, using either hardware instructions (providing full IEEE compliance) or a software emulation.

On 64-bit Cygwin, 64-bit mingw-w64 and MSVC 2017 and earlier, this function may be emulated owing to known bugs on limitations on these platforms. Note: since software emulation of the fma is costly, make sure that you are using hardware fma support if performance matters.

**Since** 4.08.0

*val rem* : **float -> float -> float**

**rem a b** returns the remainder of **a** with respect to **b** . The returned value is **a -. n *. b** , where **n** is the quotient **a /. b** rounded towards zero to an integer.

*val succ* : **float -> float**

**succ x** returns the floating point number right after **x** i.e., the smallest floating-point number greater than **x** . See also **Float.next_after** .

**Since** 4.08.0

*val pred* : **float -> float**

**pred x** returns the floating-point number right before **x** i.e., the greatest floating-point number smaller than **x** . See also **Float.next_after** .

**Since** 4.08.0

*val abs* : **float -> float**

**abs f** returns the absolute value of **f** .

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

*val pi* : **float**

The constant pi.

*val max_float* : **float**

The largest positive finite value of type **float** .

*val min_float* : **float**

The smallest positive, non-zero, non-denormalized value of type **float** .

*val epsilon* : **float**

The difference between **1.0** and the smallest exactly representable floating-point number greater than **1.0** .

*val is_finite* : **float -> bool**

**is_finite x** is **true** if and only if **x** is finite i.e., not infinite and not **Float.nan** .

**Since** 4.08.0

*val is_infinite* : **float -> bool**

**is_infinite x** is **true** if and only if **x** is **Float.infinity** or **Float.neg_infinity** .

**Since** 4.08.0

*val is_nan* : **float -> bool**

**is_nan x** is **true** if and only if **x** is not a number (see **Float.nan** ).

**Since** 4.08.0

*val is_integer* : **float -> bool**

**is_integer x** is **true** if and only if **x** is an integer.

**Since** 4.08.0

*val of_int* : **int -> float**

Convert an integer to floating-point.

*val to_int* : **float -> int**

Truncate the given floating-point number to an integer. The result is unspecified if the argument is **nan** or falls outside the range of representable integers.

*val of_string* : **string -> float**

Convert the given string to a float. The string is read in decimal (by default) or in hexadecimal (marked by **0x** or **0X** ). The format of decimal floating-point numbers is **[-] dd.ddd (e|E) [+|-] dd** , where **d** stands for a decimal digit. The format of hexadecimal floating-point numbers is **[-] 0(x|X) hh.hhh (p|P) [+|-] dd** , where **h** stands for an hexadecimal digit and **d** for a decimal digit. In both cases, at least one of the integer and fractional parts must be given; the exponent part is optional. The **_** (underscore) character can appear anywhere in the string and is ignored. Depending on the execution platforms, other representations of floating-point numbers can be accepted, but should not be relied upon.

**Raises Failure** if the given string is not a valid representation of a float.

*val of_string_opt* : **string -> float option**

Same as **of_string** , but returns **None** instead of raising.

*val to_string* : **float -> string**

Return the string representation of a floating-point number.

*type fpclass* = **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

*)

The five classes of floating-point numbers, as determined by the **Float.classify_float** function.

*val classify_float* : **float -> fpclass**

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

*val pow* : **float -> float -> float**

Exponentiation.

*val sqrt* : **float -> float**

Square root.

*val cbrt* : **float -> float**

Cube root.

**Since** 4.13.0

*val exp* : **float -> float**

Exponential.

*val exp2* : **float -> float**

Base 2 exponential function.

**Since** 4.13.0

*val log* : **float -> float**

Natural logarithm.

*val log10* : **float -> float**

Base 10 logarithm.

*val log2* : **float -> float**

Base 2 logarithm.

**Since** 4.13.0

*val expm1* : **float -> float**

**expm1 x** computes **exp x -. 1.0** , giving numerically-accurate results even if **x** is close to **0.0** .

*val log1p* : **float -> float**

**log1p x** computes **log(1.0 +. x)** (natural logarithm), giving numerically-accurate results even if **x** is close to **0.0** .

*val cos* : **float -> float**

Cosine. Argument is in radians.

*val sin* : **float -> float**

Sine. Argument is in radians.

*val tan* : **float -> float**

Tangent. Argument is in radians.

*val acos* : **float -> float**

Arc cosine. The argument must fall within the range **[-1.0, 1.0]** . Result is in radians and is between **0.0** and **pi** .

*val asin* : **float -> float**

Arc sine. The argument must fall within the range **[-1.0, 1.0]** . Result is in radians and is between **-pi/2** and **pi/2** .

*val atan* : **float -> float**

Arc tangent. Result is in radians and is between **-pi/2** and **pi/2** .

*val atan2* : **float -> float -> float**

**atan2 y x** returns the arc tangent of **y /. x** . The signs of **x** and **y** are used to determine the quadrant of the result. Result is in radians and is between **-pi** and **pi** .

*val hypot* : **float -> float -> float**

**hypot x y** returns **sqrt(x *. x + y *. y)** , that is, the length of the hypotenuse of a right-angled triangle with sides of length **x** and **y** , or, equivalently, the distance of the point **(x,y)** to origin. If one of **x** or **y** is infinite, returns **infinity** even if the other is **nan** .

*val cosh* : **float -> float**

Hyperbolic cosine. Argument is in radians.

*val sinh* : **float -> float**

Hyperbolic sine. Argument is in radians.

*val tanh* : **float -> float**

Hyperbolic tangent. Argument is in radians.

*val acosh* : **float -> float**

Hyperbolic arc cosine. The argument must fall within the range **[1.0, inf]** . Result is in radians and is between **0.0** and **inf** .

**Since** 4.13.0

*val asinh* : **float -> float**

Hyperbolic arc sine. The argument and result range over the entire real line. Result is in radians.

**Since** 4.13.0

*val atanh* : **float -> float**

Hyperbolic arc tangent. The argument must fall within the range **[-1.0, 1.0]** . Result is in radians and ranges over the entire real line.

**Since** 4.13.0

*val erf* : **float -> float**

Error function. The argument ranges over the entire real line. The result is always within **[-1.0, 1.0]** .

**Since** 4.13.0

*val erfc* : **float -> float**

Complementary error function ( **erfc x = 1 - erf x** ). The argument ranges over the entire real line. The result is always within **[-1.0, 1.0]** .

**Since** 4.13.0

*val trunc* : **float -> float**

**trunc x** rounds **x** to the nearest integer whose absolute value is less than or equal to **x** .

**Since** 4.08.0

*val round* : **float -> float**

**round x** rounds **x** to the nearest integer with ties (fractional values of 0.5) rounded away from zero, regardless of the current rounding direction. If **x** is an integer, **+0.** , **-0.** , **nan** , or infinite, **x** itself is returned.

On 64-bit mingw-w64, this function may be emulated owing to a bug in the C runtime library (CRT) on this platform.

**Since** 4.08.0

*val ceil* : **float -> float**

Round above to an integer value. **ceil f** returns the least integer value greater than or equal to **f** . The result is returned as a float.

*val floor* : **float -> float**

Round below to an integer value. **floor f** returns the greatest integer value less than or equal to **f** . The result is returned as a float.

*val next_after* : **float -> float -> float**

**next_after x y** returns the next representable floating-point value following **x** in the direction of **y** . More precisely, if **y** is greater (resp. less) than **x** , it returns the smallest (resp. largest) representable number greater (resp. less) than **x** . If **x** equals **y** , the function returns **y** . If **x** or **y** is **nan** , a **nan** is returned. Note that **next_after max_float infinity = infinity** and that **next_after 0. infinity** is the smallest denormalized positive number. If **x** is the smallest denormalized positive number, **next_after x 0. = 0.**

**Since** 4.08.0

*val copy_sign* : **float -> float -> float**

**copy_sign x y** returns a float whose absolute value is that of **x** and whose sign is that of **y** . If **x** is **nan** , returns **nan** . If **y** is **nan** , returns either **x** or **-. x** , but it is not specified which.

*val sign_bit* : **float -> bool**

**sign_bit x** is **true** if and only if the sign bit of **x** is set. For example **sign_bit 1.** and **signbit 0.** are **false** while **sign_bit (-1.)** and **sign_bit (-0.)** are **true** .

**Since** 4.08.0

*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 t* = **float**

An alias for the type of floating-point numbers.

*val compare* : **t -> t -> int**

**compare x y** returns **0** if **x** is equal to **y** , a negative integer if **x** is less than **y** , and a positive integer if **x** is greater than **y** . **compare** treats **nan** as equal to itself and less than any other float value. This treatment of **nan** ensures that **compare** defines a total ordering relation.

*val equal* : **t -> t -> bool**

The equal function for floating-point numbers, compared using **Float.compare** .

*val min* : **t -> t -> t**

**min x y** returns the minimum of **x** and **y** . It returns **nan** when **x** or **y** is **nan** . Moreover **min (-0.) (+0.) = -0.**

**Since** 4.08.0

*val max* : **float -> float -> float**

**max x y** returns the maximum of **x** and **y** . It returns **nan** when **x** or **y** is **nan** . Moreover **max (-0.) (+0.) = +0.**

**Since** 4.08.0

*val min_max* : **float -> float -> float * float**

**min_max x y** is **(min x y, max x y)** , just more efficient.

**Since** 4.08.0

*val min_num* : **t -> t -> t**

**min_num x y** returns the minimum of **x** and **y** treating **nan** as missing values. If both **x** and **y** are **nan** , **nan** is returned. Moreover **min_num (-0.) (+0.) = -0.**

**Since** 4.08.0

*val max_num* : **t -> t -> t**

**max_num x y** returns the maximum of **x** and **y** treating **nan** as missing values. If both **x** and **y** are **nan nan** is returned. Moreover **max_num (-0.) (+0.) = +0.**

**Since** 4.08.0

*val min_max_num* : **float -> float -> float * float**

**min_max_num x y** is **(min_num x y, max_num x y)** , just more efficient. Note that in particular **min_max_num x nan = (x, x)** and **min_max_num nan y = (y, y)** .

**Since** 4.08.0

*val hash* : **t -> int**

The hash function for floating-point numbers.

*module Array :* **sig end**

Float arrays with packed representation.

*module ArrayLabels :* **sig end**

Float arrays with packed representation (labeled functions).