Module Float32_u

Utilities for unboxed float32s. This module is mostly a copy of Float32, but with much functionality missing because it can't yet be implemented for unboxed float32s or unboxed types generally.

compare t1 t2 returns 0 if t1 is equal to t2, a negative integer if t1 is less than t2, and a positive integer if t1 is greater than t2.

ascending is identical to compare. descending x y = ascending y x. These are intended to be mnemonic when used like List.sort ~compare:ascending and List.sort ~cmp:descending, since they cause the list to be sorted in ascending or descending order, respectively.

between t ~low ~high means low <= t <= high

clamp_exn t ~min ~max returns t', the closest value to t such that between t' ~low:min ~high:max is true.

Raises if not (min <= max).

Equal to infinity.

Equal to neg_infinity.

The constant pi.

The constant sqrt(pi).

The constant sqrt(2 * pi).

Euler-Mascheroni constant (γ).

The difference between 1.0s and the smallest exactly representable float32 number greater than 1.0s. That is:

epsilon_float = (one_ulp `Up 1.0s) - 1.0s

This gives the relative accuracy of type t, in the sense that for numbers on the order of x, the roundoff error is on the order of x * float_epsilon.

See also: Machine epsilon.

An order-preserving bijection between all float32s except for nans, and all int32s with absolute value smaller than or equal to 2**31 - 2**23. Note both 0.s and -0.s map to 0L.

Returns nan if the absolute value of the argument is too large.

The next or previous representable float32. ULP stands for "unit of least precision", and is the spacing between floating point numbers. Both one_ulp `Up infinity and one_ulp `Down neg_infinity return a nan.

Converts a 64-bit float to the nearest representable float32.

Converts a float32 to a 64-bit float.

Converts a 64-bit unboxed float to the nearest representable float32.

Converts a float32 to a 64-bit float#.

Convert an integer to a float32. Note that this doesn't round trip in either direction. For example, Float32.to_int (Float32.of_int max_int) <> max_int.

Truncate the given float32 to an integer. The result is unspecified if the argument is nan or falls outside the range of representable integers.

Converts the given int64 to the nearest representable float32. The amd64 flambda-backend compiler translates this call to CVTSI2SS.

Truncate the given float32 number to an int64. The result is unspecified if the argument is nan or falls outside the range of representable int64s. The amd64 flambda-backend compiler translates this call to CVTTSS2SI.

Converts the given int64# to the nearest representable float32. The amd64 flambda-backend compiler translates this call to CVTSI2SS.

Truncate the given float32 number to an int64#. The result is unspecified if the argument is nan or falls outside the range of representable int64s. The amd64 flambda-backend compiler translates this call to CVTTSS2SI.

Converts an int32 to a float32 with the same bit pattern. The amd64 flambda-backend compiler translates this call to MOVD.

Converts a float32 to an int32 with the same bit pattern. The amd64 flambda-backend compiler translates this call to MOVD.

round rounds a float32 to an integer float32. iround{,_exn} rounds a float32 to an int. Both round according to a direction dir, with default dir being `Nearest.

  | `Down    | rounds toward Float32.neg_infinity                           |
  | `Up      | rounds toward Float32.infinity                               |
  | `Nearest | rounds to the nearest int ("round half-integers up")         |
  | `Zero    | rounds toward zero                                           |

iround_exn raises when trying to handle nan or trying to handle a float32 outside the range [float32 min_int, float32 max_int).

Here are some examples for round for each direction:

  | `Down    | [-2.s,-1s.)   to -2.s | [-1.s,0.s)   to -1.s | [0.s,1.s) to 0.s, [1.s,2.s) to 1.s |
  | `Up      | (-2.s,-1s.]   to -1.s | (-1.s,0.s]   to -0.s | (0.s,1.s] to 1.s, (1.s,2.s] to 2.s |
  | `Zero    | (-2.s,-1s.]   to -1.s | (-1.s,1.s)   to 0.s  | [1.s,2.s) to 1.s                   |
  | `Nearest | [-1.5s,-0.5s) to -1.s | [-0.5s,0.5s) to 0.s  | [0.5s,1.5s) to 1.s                 |

For convenience, versions of these functions with the dir argument hard-coded are provided. If you are writing performance-critical code you should use the versions with the hard-coded arguments (e.g. iround_down_exn). The _exn ones are the fastest.

The following properties hold:

• of_int (iround_*_exn i) = i for any float32 i that is an integer with min_int <= i <= max_int.

• round_* i = i for any float32 i that is an integer.

• iround_*_exn (of_int i) = i for any int i with -2**52 <= i <= 2**52.

Rounds a float32 to the next integer float32 toward zero. The amd64 flambda-backend compiler translates this call to ROUNDSS.

Rounds a float32 down to the next integer float32 toward negative infinity. The amd64 flambda-backend compiler translates this call to ROUNDSS.

Rounds a float32 up to the next integer float32 toward positive infinity. The amd64 flambda-backend compiler translates this call to ROUNDSS.

Rounds half integers up.

Rounds a float32 to an integer float32 using the current rounding mode. The default rounding mode is "round half to even", and we expect that no program will change the rounding mode. The amd64 flambda-backend compiler translates this call to ROUNDSS.

Rounds a float32 to an int64 using the current rounding mode. The default rounding mode is "round half to even", and we expect that no program will change the rounding mode. If the argument is NaN, infinite, or otherwise cannot be represented, no exception is raised and the result is an unspecified int64. The amd64 flambda-backend compiler translates this call to CVTSS2SI.

A float32 is infinite when it is either infinity or neg_infinity.

A float32 is finite when neither is_nan nor is_inf is true.

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

mod_float x y returns a result with the same sign as x. It returns nan if y is 0. It is basically

  let mod_float x y = x -. (float32 (truncate (x /. y)) *. y)

not

  let mod_float x y = x -. (floor (x /. y) *. y)

and therefore resembles mod on integers more than %.

Ordinary functions for arithmetic operations

These are for modules that inherit from t, since the infix operators are more convenient.

A sub-module designed to be opened to make working with float32s more convenient.

Similar to O, except that operators are suffixed with a dot, allowing one to have both int and float32 operators in scope simultaneously.

to_string x builds a string s representing the float32 x that guarantees the round trip, that is such that Float32_u.equal x (Float32_u.of_string s).

of_string is inverse to to_string.

Pretty print float32, for example to_string_hum ~decimals:3 1234.1999s = "1_234.200" to_string_hum ~decimals:3 ~strip_zero:true 1234.1999s = "1_234.2" . No delimiters are inserted to the right of the decimal.

Produce a lossy compact string representation of the float32. The float32 is scaled by an appropriate power of 1000 and rendered with one digit after the decimal point, except that the decimal point is written as '.', 'k', 'm', 'g', 't', or 'p' to indicate the scale factor. (However, if the digit after the "decimal" point is 0, it is suppressed.)

The smallest scale factor that allows the number to be rendered with at most 3 digits to the left of the decimal is used. If the number is too large for this format (i.e., the absolute value is at least 999.95e15), scientific notation is used instead. E.g.:

• to_padded_compact_string (-0.01s) = "-0 "
• to_padded_compact_string 1.89s = "1.9"
• to_padded_compact_string 999_949.99s = "999k9"
• to_padded_compact_string 999_950.s = "1m "

In the case where the digit after the "decimal", or the "decimal" itself is omitted, the numbers are padded on the right with spaces to ensure the last two columns of the string always correspond to the decimal and the digit afterward (except in the case of scientific notation, where the exponent is the right-most element in the string and could take up to four characters).

• to_padded_compact_string 1.s = "1 "
• to_padded_compact_string 1.e6s = "1m "
• to_padded_compact_string 1.e16s = "1.e+16"
• to_padded_compact_string max_finite_value = "1.8e+308"

Numbers in the range -.05 < x < .05 are rendered as "0 " or "-0 ".

Other cases:

• to_padded_compact_string nan = "nan "
• to_padded_compact_string infinity = "inf "
• to_padded_compact_string neg_infinity = "-inf "

Exact ties are resolved to even in the decimal:

• to_padded_compact_string 3.25s = "3.2"
• to_padded_compact_string 3.75s = "3.8"
• to_padded_compact_string 33_250.s = "33k2"
• to_padded_compact_string 33_350.s = "33k4"

to_padded_compact_string is defined in terms of to_padded_compact_string_custom below as

  let to_padded_compact_string t =
    to_padded_compact_string_custom
      t
      ?prefix:None
      ~kilo:"k"
      ~mega:"m"
      ~giga:"g"
      ~tera:"t"
      ~peta:"p"
      ()
  ;;

Similar to to_padded_compact_string but allows the user to provide different abbreviations. This can be useful to display currency values, e.g. $1mm3, where prefix="$", mega="mm".

int_pow x n computes x ** float32 n via repeated squaring. It is generally much faster than **.

Note that int_pow x 0 always returns 1.s, even if x = nan. This coincides with x ** 0.s and is intentional.

For n >= 0 the result is identical to an n-fold product of x with itself under *, with a certain placement of parentheses. For n < 0 the result is identical to int_pow (1.s / x) (-n).

The error will be on the order of |n| ulps, essentially the same as if you perturbed x by up to a ulp and then exponentiated exactly.

Benchmarks show a factor of 5-10 speedup (relative to **) for exponents up to about 1000 (approximately 10ns vs. 70ns). For larger exponents the advantage is smaller but persists into the trillions. For a recent or more detailed comparison, run the benchmarks.

Depending on context, calling this function might or might not allocate 2 minor words. Even if called in a way that causes allocation, it still appears to be faster than **.

square x returns x *. x.

ldexp x n returns x *. 2 ** n

Base 10 logarithm.

Base 2 logarithm.

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

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

copysign x y returns a float32 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.

Cosine. Argument is in radians.

Sine. Argument is in radians.

Tangent. Argument is in radians.

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

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

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

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.

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.

Hyperbolic cosine. Argument is in radians.

Hyperbolic sine. Argument is in radians.

Hyperbolic tangent. Argument is in radians.

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

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

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

Square root.

Cube root.

Exponential.

Natural logarithm.

Excluding nan the floating-point "number line" looks like:

• deprecated [since 2016-01] Replace [sign] with [robust_sign] or [sign_exn]

The sign of a float32. Both -0.s and 0.s map to Zero. Raises on nan. All other values map to Neg or Pos.

The sign of a float32, with support for NaN. Both -0.s and 0.s map to Zero. All NaN values map to Nan. All other values map to Neg or Pos.

Branchless, as Bool.select.

Branchless.