include module type of sig ... end
val t_sexp_grammar : Base.Sexp.Private.Raw_grammar.t
include Base.Floatable.S with type t := t
max
and min
will return nan if either argument is nan.
include Base.Identifiable.S with type t := t
val hash_fold_t : Base.Hash.state -> t -> Base.Hash.state
val hash : t -> Base.Hash.hash_value
include Base.Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.Sexp.t
include Base.Stringable.S with type t := t
include Base.Comparable.S with type t := t
val ascending : t -> t -> int
ascending
is identical tocompare
.descending x y = ascending y x
. These are intended to be mnemonic when used likeList.sort ~compare:ascending
andList.sort ~cmp:descending
, since they cause the list to be sorted in ascending or descending order, respectively.
val descending : t -> t -> int
val between : t -> low:t -> high:t -> bool
between t ~low ~high
meanslow <= t <= high
val clamp_exn : t -> min:t -> max:t -> t
clamp_exn t ~min ~max
returnst'
, the closest value tot
such thatbetween t' ~low:min ~high:max
is true.Raises if
not (min <= max)
.
val clamp : t -> min:t -> max:t -> t Base.Or_error.t
include Base.Comparator.S with type t := t
val comparator : (t, comparator_witness) Base.Comparator.comparator
val validate_lbound : min:t Base.Maybe_bound.t -> t Base.Validate.check
val validate_ubound : max:t Base.Maybe_bound.t -> t Base.Validate.check
val validate_bound : min:t Base.Maybe_bound.t -> max:t Base.Maybe_bound.t -> t Base.Validate.check
include Base.Pretty_printer.S with type t := t
val pp : Base.Formatter.t -> t -> unit
include Base.Comparable.With_zero with type t := t
val validate_positive : t Base.Validate.check
val validate_non_negative : t Base.Validate.check
val validate_negative : t Base.Validate.check
val validate_non_positive : t Base.Validate.check
val is_positive : t -> bool
val is_non_negative : t -> bool
val is_negative : t -> bool
val is_non_positive : t -> bool
val sign : t -> Base__Sign0.t
Returns
Neg
,Zero
, orPos
in a way consistent with the above functions.
include Base.Invariant.S with type t := t
val invariant : t -> unit
val validate_ordinary : t Base.Validate.check
validate_ordinary
fails if class isNan
orInfinite
.
val min_value : t
Equal to
neg_infinity
.
val sqrt_pi : t
The constant sqrt(pi).
val sqrt_2pi : t
The constant sqrt(2 * pi).
val euler : t
Euler-Mascheroni constant (γ).
val epsilon_float : t
The difference between 1.0 and the smallest exactly representable floating-point number greater than 1.0. That is:
epsilon_float = (one_ulp `Up 1.0) -. 1.0
This gives the relative accuracy of type
t
, in the sense that for numbers on the order ofx
, the roundoff error is on the order ofx *. float_epsilon
.See also: Machine epsilon.
val max_finite_value : t
val min_positive_subnormal_value : t
val min_positive_normal_value : t
val to_int64_preserve_order : t -> int64 option
An order-preserving bijection between all floats except for nans, and all int64s with absolute value smaller than or equal to
2**63 - 2**52
. Note both 0. and -0. map to 0L.
val to_int64_preserve_order_exn : t -> int64
val of_int64_preserve_order : int64 -> t
Returns
nan
if the absolute value of the argument is too large.
val one_ulp : [ `Up | `Down ] -> t -> t
The next or previous representable float. ULP stands for "unit of least precision", and is the spacing between floating point numbers. Both
one_ulp `Up infinity
andone_ulp `Down neg_infinity
return a nan.
val of_int : int -> t
Note that this doesn't round trip in either direction. For example,
Float.to_int (Float.of_int max_int) <> max_int
.
val to_int : t -> int
val of_int63 : Base.Int63.t -> t
val of_int64 : int64 -> t
val to_int64 : t -> int64
val round : ?dir:[ `Zero | `Nearest | `Up | `Down ] -> t -> t
round
rounds a float to an integer float.iround{,_exn}
rounds a float to an int. Both round according to a directiondir
, with defaultdir
being`Nearest
.| `Down | rounds toward Float.neg_infinity | | `Up | rounds toward Float.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 float outside the range [float min_int, float max_int).Here are some examples for
round
for each direction:| `Down | [-2.,-1.) to -2. | [-1.,0.) to -1. | [0.,1.) to 0., [1.,2.) to 1. | | `Up | (-2.,-1.] to -1. | (-1.,0.] to -0. | (0.,1.] to 1., (1.,2.] to 2. | | `Zero | (-2.,-1.] to -1. | (-1.,1.) to 0. | [1.,2.) to 1. | | `Nearest | [-1.5,-0.5) to -1. | [-0.5,0.5) to 0. | [0.5,1.5) to 1. |
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 floati
that is an integer withmin_int <= i <= max_int
.
round_* i = i
for any floati
that is an integer.
iround_*_exn (of_int i) = i
for any inti
with-2**52 <= i <= 2**52
.
val iround : ?dir:[ `Zero | `Nearest | `Up | `Down ] -> t -> int option
val iround_exn : ?dir:[ `Zero | `Nearest | `Up | `Down ] -> t -> int
val round_towards_zero : t -> t
val round_down : t -> t
val round_up : t -> t
val round_nearest : t -> t
Rounds half integers up.
val iround_towards_zero : t -> int option
val iround_down : t -> int option
val iround_up : t -> int option
val iround_nearest : t -> int option
val iround_towards_zero_exn : t -> int
val iround_down_exn : t -> int
val iround_up_exn : t -> int
val iround_nearest_exn : t -> int
val int63_round_down_exn : t -> Base.Int63.t
val int63_round_up_exn : t -> Base.Int63.t
val int63_round_nearest_exn : t -> Base.Int63.t
val iround_lbound : t
If
f <= iround_lbound || f >= iround_ubound
, theniround*
functions will refuse to roundf
, returningNone
or raising as appropriate.
val iround_ubound : t
val round_significant : float -> significant_digits:int -> float
round_significant x ~significant_digits:n
rounds to the nearest number withn
significant digits. More precisely: it returns the representable float closest tox rounded to n significant digits
. It is meant to be equivalent tosprintf "%.*g" n x |> Float.of_string
but faster (10x-15x). Exact ties are resolved as round-to-even.However, it might in rare cases break the contract above.
It might in some cases appear as if it violates the round-to-even rule:
let x = 4.36083208835;; let z = 4.3608320883;; assert (z = fast_approx_round_significant x ~sf:11)
But in this case so does sprintf, since
x
as a float is slightly under-represented:sprintf "%.11g" x = "4.3608320883";; sprintf "%.30g" x = "4.36083208834999958014577714493"
More importantly,
round_significant
might sometimes give a different result thansprintf ... |> Float.of_string
because it round-trips through an integer. For example, the decimal fraction 0.009375 is slightly under-represented as a float:sprintf "%.17g" 0.009375 = "0.0093749999999999997"
But:
0.009375 *. 1e5 = 937.5
Therefore:
round_significant 0.009375 ~significant_digits:3 = 0.00938
whereas:
sprintf "%.3g" 0.009375 = "0.00937"
In general we believe (and have tested on numerous examples) that the following holds for all x:
let s = sprintf "%.*g" significant_digits x |> Float.of_string in s = round_significant ~significant_digits x || s = round_significant ~significant_digits (one_ulp `Up x) || s = round_significant ~significant_digits (one_ulp `Down x)
Also, for float representations of decimal fractions (like 0.009375),
round_significant
is more likely to give the "desired" result thansprintf ... |> of_string
(that is, the result of rounding the decimal fraction, rather than its float representation). But it's not guaranteed either--see the4.36083208835
example above.
val round_decimal : float -> decimal_digits:int -> float
round_decimal x ~decimal_digits:n
roundsx
to the nearest10**(-n)
. For positiven
it is meant to be equivalent tosprintf "%.*f" n x |> Float.of_string
, but faster.All the considerations mentioned in
round_significant
apply (both functions use the same code path).
val min_inan : t -> t -> t
val max_inan : t -> t -> t
val (+) : t -> t -> t
val (-) : t -> t -> t
val (/) : t -> t -> t
val (*) : t -> t -> t
val (**) : t -> t -> t
val (~-) : t -> t
module Parts : sig ... end with type Parts.outer := t
Returns the fractional part and the whole (i.e., integer) part. For example,
modf (-3.14)
returns{ fractional = -0.14; integral = -3.; }
!
val modf : t -> Parts.t
val mod_float : t -> t -> t
mod_float x y
returns a result with the same sign asx
. It returnsnan
ify
is0
. It is basicallylet mod_float x y = x -. float(truncate(x/.y)) *. y
not
let mod_float x y = x -. floor(x/.y) *. y
and therefore resembles
mod
on integers more than%
.
val add : t -> t -> t
Ordinary functions for arithmetic operations
These are for modules that inherit from
t
, since the infix operators are more convenient.
module O : sig ... end
A sub-module designed to be opened to make working with floats more convenient.
module O_dot : sig ... end
Similar to
O
, except that operators are suffixed with a dot, allowing one to have both int and float operators in scope simultaneously.
val to_string : t -> string
to_string x
builds a strings
representing the floatx
that guarantees the round trip, that is such thatFloat.equal x (Float.of_string s)
.It usually yields as few significant digits as possible. That is, it won't print
3.14
as3.1400000000000001243
. The only exception is that occasionally it will output 17 significant digits when the number can be represented with just 16 (but not 15 or less) of them.
val to_string_hum : ?delimiter:char -> ?decimals:int -> ?strip_zero:bool -> t -> string
Pretty print float, for example
to_string_hum ~decimals:3 1234.1999 = "1_234.200"
to_string_hum ~decimals:3 ~strip_zero:true 1234.1999 = "1_234.2"
. No delimiters are inserted to the right of the decimal.
val to_padded_compact_string : t -> string
Produce a lossy compact string representation of the float. The float 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.01) = "-0 "
to_padded_compact_string 1.89 = "1.9"
to_padded_compact_string 999_949.99 = "999k9"
to_padded_compact_string 999_950. = "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. = "1 "
to_padded_compact_string 1.e6 = "1m "
to_padded_compact_string 1.e16 = "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.25 = "3.2"
to_padded_compact_string 3.75 = "3.8"
to_padded_compact_string 33_250. = "33k2"
to_padded_compact_string 33_350. = "33k4"
to_padded_compact_string
is defined in terms ofto_padded_compact_string_custom
below aslet to_padded_compact_string t = to_padded_compact_string_custom t ?prefix:None ~kilo:"k" ~mega:"m" ~giga:"g" ~tera:"t" ~peta:"p" ()
val to_padded_compact_string_custom : t -> ?prefix:string -> kilo:string -> mega:string -> giga:string -> tera:string -> ?peta:string -> unit -> string
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".
val int_pow : t -> int -> t
int_pow x n
computesx ** float n
via repeated squaring. It is generally much faster than**
.Note that
int_pow x 0
always returns1.
, even ifx = nan
. This coincides withx ** 0.
and is intentional.For
n >= 0
the result is identical to an n-fold product ofx
with itself under*.
, with a certain placement of parentheses. Forn < 0
the result is identical toint_pow (1. /. x) (-n)
.The error will be on the order of
|n|
ulps, essentially the same as if you perturbedx
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
**
.
val frexp : t -> t * int
frexp f
returns the pair of the significant and the exponent off
. Whenf
is zero, the significantx
and the exponentn
off
are equal to zero. Whenf
is non-zero, they are defined byf = x *. 2 ** n
and0.5 <= x < 1.0
.
val expm1 : t -> t
expm1 x
computesexp x -. 1.0
, giving numerically-accurate results even ifx
is close to0.0
.
val log1p : t -> t
log1p x
computeslog(1.0 +. x)
(natural logarithm), giving numerically-accurate results even ifx
is close to0.0
.
val copysign : t -> t -> t
copysign x y
returns a float whose absolute value is that ofx
and whose sign is that ofy
. Ifx
isnan
, returnsnan
. Ify
isnan
, returns eitherx
or-. x
, but it is not specified which.
val acos : t -> t
Arc cosine. The argument must fall within the range
[-1.0, 1.0]
. Result is in radians and is between0.0
andpi
.
val asin : t -> t
Arc sine. The argument must fall within the range
[-1.0, 1.0]
. Result is in radians and is between-pi/2
andpi/2
.
val atan2 : t -> t -> t
atan2 y x
returns the arc tangent ofy /. x
. The signs ofx
andy
are used to determine the quadrant of the result. Result is in radians and is between-pi
andpi
.
val hypot : t -> t -> t
hypot x y
returnssqrt(x *. x + y *. y)
, that is, the length of the hypotenuse of a right-angled triangle with sides of lengthx
andy
, or, equivalently, the distance of the point(x,y)
to origin.
module Class : sig ... end
Excluding nan the floating-point "number line" looks like:
val classify : t -> Class.t
val is_finite : t -> bool
is_finite t
returnstrue
iffclassify t
is inNormal; Subnormal; Zero;
.
val sign : t -> Base.Sign.t
val sign_exn : t -> Base.Sign.t
The sign of a float. Both
-0.
and0.
map toZero
. Raises on nan. All other values map toNeg
orPos
.
val sign_or_nan : t -> Base.Sign_or_nan.t
The sign of a float, with support for NaN. Both
-0.
and0.
map toZero
. All NaN values map toNan
. All other values map toNeg
orPos
.
val create_ieee : negative:bool -> exponent:int -> mantissa:Base.Int63.t -> t Base.Or_error.t
These functions construct and destruct 64-bit floating point numbers based on their IEEE representation with a sign bit, an 11-bit non-negative (biased) exponent, and a 52-bit non-negative mantissa (or significand). See Wikipedia for details of the encoding.
In particular, if 1 <= exponent <= 2046, then:
create_ieee_exn ~negative:false ~exponent ~mantissa = 2 ** (exponent - 1023) * (1 + (2 ** -52) * mantissa)
val create_ieee_exn : negative:bool -> exponent:int -> mantissa:Base.Int63.t -> t
val ieee_negative : t -> bool
val ieee_exponent : t -> int
val ieee_mantissa : t -> Base.Int63.t
module Terse : sig ... end
S-expressions contain at most 8 significant digits.
type t = Base.Float.t
include Typerep_lib.Typerepable.S with type t := t
val typerep_of_t : t Typerep_lib.Std_internal.Typerep.t
val typename_of_t : t Typerep_lib.Typename.t
module Robust_compare : sig ... end
The results of robust comparisons on nan
should be considered undefined.
include Robust_compare.S
val robust_comparison_tolerance : Base.Float.t
intended to be a tolerance on human-entered floats
include Robustly_comparable.S with type t := Base.Float.t
val (>=.) : Base.Float.t -> Base.Float.t -> bool
val (<=.) : Base.Float.t -> Base.Float.t -> bool
val (=.) : Base.Float.t -> Base.Float.t -> bool
val (>.) : Base.Float.t -> Base.Float.t -> bool
val (<.) : Base.Float.t -> Base.Float.t -> bool
val (<>.) : Base.Float.t -> Base.Float.t -> bool
val robustly_compare : Base.Float.t -> Base.Float.t -> int
module O : sig ... end
module Robustly_comparable : Robust_compare.S
module Terse : sig ... end
include Identifiable.S with type t := t and type comparator_witness := Base.Float.comparator_witness
include Bin_prot.Binable.S with type t := t
include Bin_prot.Binable.S_only_functions with type t := t
val bin_size_t : t Bin_prot.Size.sizer
val bin_write_t : t Bin_prot.Write.writer
val bin_read_t : t Bin_prot.Read.reader
val __bin_read_t__ : (int -> t) Bin_prot.Read.reader
This function only needs implementation if
t
exposed to be a polymorphic variant. Despite what the type reads, this does *not* produce a function after reading; instead it takes the constructor tag (int) before reading and reads the rest of the variantt
afterwards.
val bin_shape_t : Bin_prot.Shape.t
val bin_writer_t : t Bin_prot.Type_class.writer
val bin_reader_t : t Bin_prot.Type_class.reader
val bin_t : t Bin_prot.Type_class.t
val hash_fold_t : Base.Hash.state -> t -> Base.Hash.state
val hash : t -> Base.Hash.hash_value
include Ppx_sexp_conv_lib.Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.Sexp.t
include Identifiable.S_common with type t := t
val compare : t -> t -> Base.Int.t
val hash_fold_t : Base.Hash.state -> t -> Base.Hash.state
val hash : t -> Base.Hash.hash_value
val sexp_of_t : t -> Ppx_sexp_conv_lib.Sexp.t
include Base.Stringable.S with type t := t
include Base.Pretty_printer.S with type t := t
val pp : Base.Formatter.t -> t -> unit
include Comparable.S_binable with type comparator_witness := Base.Float.comparator_witness and type t := t
include Base.Comparable.S with type comparator_witness := Base.Float.comparator_witness and type t := t
val ascending : t -> t -> int
ascending
is identical tocompare
.descending x y = ascending y x
. These are intended to be mnemonic when used likeList.sort ~compare:ascending
andList.sort ~cmp:descending
, since they cause the list to be sorted in ascending or descending order, respectively.
val descending : t -> t -> int
val between : t -> low:t -> high:t -> bool
between t ~low ~high
meanslow <= t <= high
val clamp_exn : t -> min:t -> max:t -> t
clamp_exn t ~min ~max
returnst'
, the closest value tot
such thatbetween t' ~low:min ~high:max
is true.Raises if
not (min <= max)
.
val clamp : t -> min:t -> max:t -> t Base.Or_error.t
include Base.Comparator.S with type comparator_witness := Base.Float.comparator_witness and type t := t
val comparator : (t, Base.Float.comparator_witness) Base.Comparator.comparator
val validate_lbound : min:t Base.Maybe_bound.t -> t Base.Validate.check
val validate_ubound : max:t Base.Maybe_bound.t -> t Base.Validate.check
val validate_bound : min:t Base.Maybe_bound.t -> max:t Base.Maybe_bound.t -> t Base.Validate.check
module Replace_polymorphic_compare : sig ... end
include Comparator.S with type comparator_witness := Base.Float.comparator_witness and type t := t
val comparator : (t, Base.Float.comparator_witness) Comparator.comparator
module Map : Map.S_binable with type Key.t = t with type Key.comparator_witness = Base.Float.comparator_witness
module Set : Set.S_binable with type Elt.t = t with type Elt.comparator_witness = Base.Float.comparator_witness
include Hashable.S_binable with type t := t
val hash_fold_t : Base.Hash.state -> t -> Base.Hash.state
val hash : t -> Base.Hash.hash_value
val hashable : t Hashtbl.Hashable.t
module Table : Hashtbl.S_binable with type key = t
module Hash_set : Hash_set.S_binable with type elt = t
module Hash_queue : Hash_queue.S with type key = t
val to_string_12 : t -> Base.String.t
to_string_12 x
builds a string representingx
using up to 12 significant digits. It loses precision. You can use"%{Float#12}"
in formats, but consider"%.12g"
,"%{Float#hum}"
, or"%{Float}"
as alternatives.
val to_string : t -> Base.String.t
to_string x
builds a strings
representing the floatx
that guarantees the round trip, i.e.,Float.equal x (Float.of_string s)
.It usually yields as few significant digits as possible. That is, it won't print
3.14
as3.1400000000000001243
. The only exception is that occasionally it will output 17 significant digits when the number can be represented with just 16 (but not 15 or fewer) of them.
include Quickcheckable.S with type t := t
val quickcheck_generator : t Base_quickcheck.Generator.t
val quickcheck_observer : t Base_quickcheck.Observer.t
val quickcheck_shrinker : t Base_quickcheck.Shrinker.t
val sign : t -> Sign.t
val robust_sign : t -> Sign.t
(Formerly
sign
) Uses robust comparison (so sufficiently small numbers are mapped toZero
). Also maps NaN toZero
. Using this function is weakly discouraged.
val gen_uniform_excl : t -> t -> t Quickcheck.Generator.t
gen_uniform_excl lo hi
creates a Quickcheck generator producing finitet
values betweenlo
andhi
, exclusive. The generator approximates a uniform distribution over the interval (lo, hi). Raises an exception iflo
is not finite,hi
is not finite, or the requested range is empty.The implementation chooses values uniformly distributed between 0 (inclusive) and 1 (exclusive) up to 52 bits of precision, then scales that interval to the requested range. Due to rounding errors and non-uniform floating point precision, the resulting distribution may not be precisely uniform and may not include all values between
lo
andhi
.
val gen_incl : t -> t -> t Quickcheck.Generator.t
gen_incl lo hi
creates a Quickcheck generator that produces values betweenlo
andhi
, inclusive, approximately uniformly distributed, with extra weight given to generating the endpointslo
andhi
. Raises an exception iflo
is not finite,hi
is not finite, or the requested range is empty.
val gen_finite : t Quickcheck.Generator.t
gen_finite
produces all finitet
values, excluding infinities and all NaN values.
val gen_positive : t Quickcheck.Generator.t
gen_positive
produces all (strictly) positive finitet
values.
val gen_negative : t Quickcheck.Generator.t
gen_negative
produces all (strictly) negative finitet
values.
val gen_without_nan : t Quickcheck.Generator.t
gen_without_nan
produces all finite and infinitet
values, excluding all NaN values.
val gen_infinite : t Quickcheck.Generator.t
gen_infinite
produces both infinite values
val gen_nan : t Quickcheck.Generator.t
gen_nan
produces all NaN values.
val gen_normal : t Quickcheck.Generator.t
gen_normal
produces all normal values
val gen_subnormal : t Quickcheck.Generator.t
gen_subnormal
produces all subnormal values
val gen_zero : t Quickcheck.Generator.t
gen_zero
produces both zero values