The literal 0.0 as a named value

The literal 1.0 as a named value

NaN as a named value. NaN stands for not a number.

Note comparing values with Float.nan will always return false even if the value you are comparing against is also NaN.

For detecting Nan you should use Float.is_nan

Examples

  let is_not_a_number x = Float.(x = nan) in

  is_not_a_number nan = false

Positive infinity.

Float.log ~base:10.0 0.0 = Float.infinity

Negative infinity, see Float.infinity

An approximation of Euler's number.

An approximation of pi.

The smallest interval between two representable numbers.

The largest (furthest from zero) representable positive float.

The smallest representable positive float. The closest to zero without actually being zero.

For floats greater than maximum_safe_integer, it no longer holds that Float.(n + 1.) > n.

For floats less than minimum_safe_integer, it no longer holds that Float.(n - 1.) < n.

Convert an Int to a float.

Examples

  Float.from_int 5 = 5.0
  Float.from_int 0 = 0.0
  Float.from_int (-7) = (-7.0)

Convert a String to a float.

Parses nan and infinity case-insensitive.

Examples

Float.from_string "4.667" = Some 4.667

Float.from_string "-4.667" = Some (-4.667)

Float.from_string "Hamster" = None

Float.from_string "NaN" = Some Float.nan

Float.from_string "nan" = Some Float.nan

Float.from_string "Infinity" = Some Float.infinity

Addition for floating point numbers.

Although ints and floats support many of the same basic operations such as addition and subtraction you cannot add an int and a float directly which means you need to use functions like Int.to_float to convert both values to the same type.

So if you needed to add a List.length to a float for some reason, you could:

Float.add 3.14 (Int.to_float (List.length [1;2;3])) = 6.14

or

Float.(round 3.5 |> toInt) + List.length [1;2;3] = 6

Languages like Java and JavaScript automatically convert int values to float values when you mix and match. This can make it difficult to be sure exactly what type of number you are dealing with and cause unexpected behavior.

OCaml has opted for a design that makes all conversions explicit.

Examples

  Float.add 3.14 3.14 = 6.28
  Float.(3.14 + 3.14 = 6.28)

See Float.add

Subtract numbers.

Alternatively the - operator can be used

Examples

Float.subtract 4.0 3.0 = 1.0

Float.(4.0 - 3.0) = 1.0

See Float.subtract

Multiply numbers.

Alternatively the * operator can be used

Examples

Float.multiply 2.0 7.0 = 14.0

Float.(2.0 * 7.0) = 14.0

See Float.multiply.

Floating-point division:

Alternatively the / operator can be used

Examples

Float.divide 3.14 ~by:2.0 = 1.57

Float.(3.14 / 2.0) = 1.57

See Float.divide

Exponentiation, takes the base first, then the exponent.

Alternatively the ** operator can be used

Examples

Float.power ~base:7.0 ~exponent:3.0 = 343.0

Float.(7.0 ** 3.0) = 343.0

See Float.power

Flips the 'sign' of a float so that positive floats become negative and negative integers become positive. Zero stays as it is.

Alternatively an operator is available

Examples

Float.(~- 4.0) = (-4.0)

  Float.negate 8. = (-8.)
  Float.negate (-7.) = 7.
  Float.negate 0. = 0.

See Float.negate

Get the absolute value of a number.

Examples

  Float.absolute 8. = 8.
  Float.absolute (-7.) = 7.
  Float.absolute 0. = 0.

Returns the larger of two floats, if both arguments are equal, returns the first argument.

If either (or both) of the arguments are NaN, returns NaN

Examples

Float.maximum 7. 9. = 9.

Float.maximum (-4.) (-1.) = (-1.)

Float.(is_nan (maximum 7. nan)) = true

Returns the smaller of two floats, if both arguments are equal, returns the first argument.

If either (or both) of the arguments are NaN, returns NaN.

Examples

Float.minimum 7.0 9.0 = 7.0

Float.minimum (-4.0) (-1.0) = (-4.0)

Float.(is_nan (minimum 7. nan)) = true

Clamps n within the inclusive lower and upper bounds.

Exceptions

Throws an Invalid_argument exception if lower > upper.

Examples

Float.clamp ~lower:0. ~upper:8. 5. = 5.

Float.clamp ~lower:0. ~upper:8. 9. = 8.

Float.clamp ~lower:(-10.) ~upper:(-5.) 5. = (-5.)

Take the square root of a number.

square_root returns NaN when its argument is negative. See Float.nan for more.

Examples

Float.square_root 4.0 = 2.0

Float.square_root 9.0 = 3.0

Calculate the logarithm of a number with a given base.

Examples

Float.log ~base:10. 100. = 2.

Float.log ~base:2. 256. = 8.

Determine whether a float is an undefined or unrepresentable number.

Note: this function is more useful than it might seem since NaN does not equal NaN:

Float.(nan = nan) = false

Examples

Float.is_nan (0.0 /. 0.0) = true

Float.(is_nan (square_root (-1.0))) = true

Float.is_nan (1.0 /. 0.0) = false  (* Float.infinity {b is} a number *)

Float.is_nan 1. = false

Determine whether a float is finite number. True for any float except Infinity, -Infinity or NaN

Notice that NaN is not finite!

Examples

Float.is_finite (0. /. 0.) = false

Float.(is_finite (square_root (-1.))) = false

Float.is_finite (1. /. 0.) = false

Float.is_finite 1. = true

Float.(is_finite nan) = false

Determine whether a float is positive or negative infinity.

Examples

Float.is_infinite (0. /. 0.) = false

Float.(is_infinite (square_root (-1.))) = false

Float.is_infinite (1. /. 0.) = true

Float.is_infinite 1. = false

Float.(is_infinite nan) = false

Determine whether the passed value is an integer.

Examples

Float.is_integer 4.0 = true

Float.is_integer Float.pi = false

Determine whether the passed value is a safe integer (number between -(2**53 - 1) and 2**53 - 1).

Examples

Float.is_safe_integer 4.0 = true

Float.is_safe_integer Float.pi = false

Float.(is_safe_integer (maximum_safe_integer + 1.)) = false

Checks if a float is between lower and up to, but not including, upper.

If lower is not specified, it's set to to 0.0.

Exceptions

Throws an Invalid_argument exception if lower > upper

Examples

Float.in_range ~lower:2. ~upper:4. 3. = true

Float.in_range ~lower:1. ~upper:2. 2. = false

Float.in_range ~lower:5.2 ~upper:7.9 9.6 = false

This type is just an alias for float.

Its purpose is to make understanding the signatures of the following functions a little easier.

hypotenuse x y returns 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 (0, 0).

Examples

Float.hypotenuse 3. 4. = 5.

Converts an angle in degrees to Float.radians.

Examples

Float.degrees 180. = Float.pi

Float.degrees 360. = Float.pi *. 2.

Float.degrees 90. = Float.pi /. 2.

Convert a Float.t to radians.

Note This function doesn't actually do anything to its argument, but can be useful to indicate intent when inter-mixing angles of different units within the same function.

Examples

Float.(radians pi) = 3.141592653589793

Convert an angle in turns into Float.radians.

One turn is equal to 360 degrees.

Examples

Float.(turns (1. / 2.)) = Float.pi

Float.(turns 1. = degrees 360.)

Convert polar coordinates (radius, radians) to Cartesian coordinates (x,y).

Examples

Float.(from_polar (square_root 2., degrees 45.)) = (1., 1.)

Convert Cartesian coordinates (x, y) to polar coordinates (radius, radians).

Examples

Float.to_polar (-1.0, 0.0) = (1.0, Float.pi)

Float.to_polar (3.0, 4.0) = (5.0, 0.9272952180016122)

Float.to_polar (5.0, 12.0) = (13.0, 1.1760052070951352)

Figure out the cosine given an angle in radians.

Examples

Float.(cos (degrees 60.)) = 0.5000000000000001

Float.(cos (radians (pi / 3.))) = 0.5000000000000001

Figure out the arccosine for adjacent / hypotenuse in radians:

Examples

Float.(acos (radians 1.0 / 2.0)) = Float.radians 1.0471975511965979 (* 60 degrees or pi/3 radians *)

Figure out the sine given an angle in radians.

Examples

Float.(sin (degrees 30.)) = 0.49999999999999994

Float.(sin (radians (pi / 6.))) = 0.49999999999999994

Figure out the arcsine for opposite / hypotenuse in radians:

Examples

Float.(asin (1.0 / 2.0)) = 0.5235987755982989 (* 30 degrees or pi / 6 radians *)

Figure out the tangent given an angle in radians.

Examples

Float.(tan (degrees 45.)) = 0.9999999999999999

Float.(tan (radians (pi / 4.))) = 0.9999999999999999

Float.(tan (pi / 4.)) = 0.9999999999999999

This helps you find the angle (in radians) to an (x, y) coordinate, but in a way that is rarely useful in programming.

You probably want atan2 instead!

This version takes y / x as its argument, so there is no way to know whether the negative signs comes from the y or x value. So as we go counter-clockwise around the origin from point (1, 1) to (1, -1) to (-1,-1) to (-1,1) we do not get angles that go in the full circle:

Notice that everything is between pi / 2 and -pi/2. That is pretty useless for figuring out angles in any sort of visualization, so again, check out Float.atan2 instead!

Examples

Float.atan (1. /. 1.) = 0.7853981633974483  (* 45 degrees or pi/4 radians *)

Float.atan (1. /. -1.) = (-0.7853981633974483)  (* 315 degrees or 7 * pi / 4 radians *)

Float.atan (-1. /. -1.) = 0.7853981633974483 (* 45 degrees or pi/4 radians *)

Float.atan (-1. /.  1.) = (-0.7853981633974483) (* 315 degrees or 7 * pi/4 radians *)

This helps you find the angle (in radians) to an (x, y) coordinate.

So rather than Float.(atan (y / x)) you can Float.atan2 ~y ~x and you can get a full range of angles:

Examples

Float.atan2 ~y:1. ~x:1. = 0.7853981633974483  (* 45 degrees or pi/4 radians *)

Float.atan2 ~y:1. ~x:(-1.) = 2.3561944901923449  (* 135 degrees or 3 * pi/4 radians *)

Float.atan2 ~y:(-1.) ~x:(-1.) = (-2.3561944901923449) (* 225 degrees or 5 * pi/4 radians *)

Float.atan2 ~y:(-1.) ~x:1. = (-0.7853981633974483) (* 315 degrees or 7 * pi/4 radians *)

The possible directions availible when doing Float.round.

See Float.round for what each variant represents.

Round a number, by default to the to the closest int with halves rounded `Up (towards positive infinity).

Other rounding strategies are available by using the optional ~direction labelelled.

Examples

  Float.round 1.2 = 1.0
  Float.round 1.5 = 2.0
  Float.round 1.8 = 2.0
  Float.round (-1.2) = (-1.0)
  Float.round (-1.5) = (-1.0)
  Float.round (-1.8) = (-2.0)

Towards zero

  Float.round ~direction:`Zero 1.2 = 1.0
  Float.round ~direction:`Zero 1.5 = 1.0
  Float.round ~direction:`Zero 1.8 = 1.0
  Float.round ~direction:`Zero (-1.2) = (-1.0)
  Float.round ~direction:`Zero (-1.5) = (-1.0)
  Float.round ~direction:`Zero (-1.8) = (-1.0)

Away from zero

  Float.round ~direction:`AwayFromZero 1.2 = 2.0
  Float.round ~direction:`AwayFromZero 1.5 = 2.0
  Float.round ~direction:`AwayFromZero 1.8 = 2.0
  Float.round ~direction:`AwayFromZero (-1.2) = (-2.0)
  Float.round ~direction:`AwayFromZero (-1.5) = (-2.0)
  Float.round ~direction:`AwayFromZero (-1.8) = (-2.0)

Towards infinity

This is also known as Float.ceiling.

  Float.round ~direction:`Up 1.2 = 2.0
  Float.round ~direction:`Up 1.5 = 2.0
  Float.round ~direction:`Up 1.8 = 2.0
  Float.round ~direction:`Up (-1.2) = (-1.0)
  Float.round ~direction:`Up (-1.5) = (-1.0)
  Float.round ~direction:`Up (-1.8) = (-1.0)

Towards negative infinity

This is also known as Float.floor.

List.map  ~f:(Float.round ~direction:`Down) [-1.8; -1.5; -1.2; 1.2; 1.5; 1.8] = [-2.0; -2.0; -2.0; 1.0; 1.0; 1.0]

To the closest integer

Rounding a number x to the closest integer requires some tie-breaking for when the fraction part of x is exactly 0.5.

Halves rounded towards zero

List.map  ~f:(Float.round ~direction:(`Closest `Zero)) [-1.8; -1.5; -1.2; 1.2; 1.5; 1.8] = [-2.0; -1.0; -1.0; 1.0; 1.0; 2.0]

Halves rounded away from zero

This method is often known as commercial rounding.

List.map  ~f:(Float.round ~direction:(`Closest `AwayFromZero)) [-1.8; -1.5; -1.2; 1.2; 1.5; 1.8] = [-2.0; -2.0; -1.0; 1.0; 2.0; 2.0]

Halves rounded down

List.map  ~f:(Float.round ~direction:(`Closest `Down)) [-1.8; -1.5; -1.2; 1.2; 1.5; 1.8] = [-2.0; -2.0; -1.0; 1.0; 1.0; 2.0]

Halves rounded up

This is the default.

Float.round 1.5 is the same as Float.round ~direction:(`Closest `Up) 1.5

Halves rounded towards the closest even number

  Float.round ~direction:(`Closest `ToEven) (-1.5) = (-2.0)
  Float.round ~direction:(`Closest `ToEven) (-2.5) = (-2.0)

Floor function, equivalent to Float.round ~direction:`Down.

Examples

  Float.floor 1.2 = 1.0
  Float.floor 1.5 = 1.0
  Float.floor 1.8 = 1.0
  Float.floor (-1.2) = (-2.0)
  Float.floor (-1.5) = (-2.0)
  Float.floor (-1.8) = (-2.0)

Ceiling function, equivalent to Float.round ~direction:`Up.

Examples

  Float.ceiling 1.2 = 2.0
  Float.ceiling 1.5 = 2.0
  Float.ceiling 1.8 = 2.0
  Float.ceiling (-1.2) = (-1.0)
  Float.ceiling (-1.5) = (-1.0)
  Float.ceiling (-1.8) = (-1.0)

Ceiling function, equivalent to Float.round ~direction:`Zero.

Examples

  Float.truncate 1.0 = 1.
  Float.truncate 1.2 = 1.
  Float.truncate 1.5 = 1.
  Float.truncate 1.8 = 1.
  Float.truncate (-1.2) = (-1.)
  Float.truncate (-1.5) = (-1.)
  Float.truncate (-1.8) = (-1.)

Converts a float to an Int by ignoring the decimal portion. See Float.truncate for examples.

Returns None when trying to round a float which can't be represented as an int such as Float.nan or Float.infinity or numbers which are too large or small.

You probably want to use some form of Float.round prior to using this function.

Examples

Float.(to_int 1.6) = (Some 1)

Float.(to_int 2.0) = (Some 2)

Float.(to_int 5.683) = (Some 5)

Float.(to_int nan) = None

Float.(to_int infinity) = None

Float.(round 1.6 |> to_int) = Some 2

Convert a float to a String.

The behaviour of this function is platform specific.

Test two floats for equality.

Compare two floats.