Module `Floatml.F32`Source

IEEE 754 binary32, single precision.

Sourcetype t

A concrete floating-point value (every bit pattern, NaNs included).

Sourcetype bits = int32

The raw bit pattern of t, as a native integer type.

Format parameters

Sourceval size : int

Total width in bits (eb + sb): 16, 32, 64 or 128.

Sourceval exponent_bits : int

Width of the exponent field (eb): 5, 8, 11 or 15.

Sourceval significand_bits : int

Width of the significand (sb), counting the hidden bit: 11, 24, 53 or 113. Note this is one more than the number of stored mantissa bits.

Construction and bit access

Sourceval of_string : string -> t

Parse a floating-point literal, correctly rounded to nearest-ties-to-even (IEEE 754 convertFromDecimalCharacter).

Accepted: an optionally signed decimal literal with optional fraction and exponent ("3.5", "1e-10", ".5", "+1.0"), an optionally signed hexadecimal literal ("0x1.8p1"), or one of "inf", "nan" and "snan" with an optional -. Leading or trailing whitespace is not accepted, and neither is any trailing text.

raises Invalid_argument
if s is not a valid float literal. This includes the case where s is not valid UTF-8, since no float literal is.

Sourceval of_string_opt : string -> t option

of_string, returning None instead of raising.

Sourceval of_float : float -> t

Round an OCaml float (binary64) to this precision, ties to even. Exact for F64 and F128.

Sourceval of_z : Z.t -> t

Round an arbitrary-precision integer to this precision, ties to even. Unlike int2float the argument is a mathematical integer rather than the contents of a bit-vector, so it is not reduced to any width: a magnitude too large for the format gives an infinity. Zero gives +0.

of_z (Z.of_int 200) is 200., where int2float (Z.of_int 200) Int8 m ~signed:true is -56. — the same 200 read as the eight bits of a signed bit-vector.

Sourceval of_bits : bits -> t

Reinterpret a raw interchange-format bit pattern as a float. Only the low eb+sb bits are used, so for F16 — whose bits is a full-width int — the argument is narrowed to 16 bits and to_bits does not return it unchanged.

Sourceval of_bits_z : Z.t -> t

Like of_bits but taking the bit pattern as a Z.t, of which the low eb+sb bits are used. Total: any Z.t, negative ones included (read as two's complement), denotes a bit pattern.

Sourceval to_bits : t -> bits

The raw bit pattern of t.

Sourceval to_z : t -> Z.t

The raw bit pattern of t as a non-negative Z.t.

Sourceval to_float : t -> float

Nearest OCaml float (binary64) to t, for display. Lossy for F128 and exact for the smaller formats.

Constants

Each of these is exactly representable at every precision.

Sourceval zero : t

Sourceval neg_zero : t

Sourceval one : t

Sourceval nan : t

The canonical quiet NaN — the one every operation here yields when it produces a NaN, so equal nan (div zero zero) holds. Note this is not of_float Float.nan: OCaml's Float.nan carries a payload of 1.

Sourceval infinity : t

Sourceval neg_infinity : t

Arithmetic

Arithmetic rounds to nearest-ties-to-even (the IEEE 754 default mode).

Sourceval add : t -> t -> t

IEEE 754 addition.

Sourceval sub : t -> t -> t

IEEE 754 subtraction.

Sourceval mul : t -> t -> t

IEEE 754 multiplication.

Sourceval div : t -> t -> t

IEEE 754 division.

Sourceval fma : t -> t -> t -> t

IEEE 754 fusedMultiplyAdd: a*b + c with a single rounding.

Sourceval rem : t -> t -> t

IEEE 754 remainder: x - y*n where n is the integer nearest x/y (ties to even). This is not C fmod; e.g. rem (-5.) 3. = 1..

Sourceval fmod : t -> t -> t

C fmod — and so Rust's % on floats, and LLVM frem: the remainder x - y*n where n is x/y truncated toward zero. Distinct from rem, which rounds x/y to nearest: fmod (-5.) 3. = -2. where rem (-5.) 3. = 1..

Sourceval sqrt : t -> t

IEEE 754 squareRoot, correctly rounded to nearest-ties-to-even.

Sourceval abs : t -> t

IEEE 754 abs (clears the sign bit).

Sourceval neg : t -> t

IEEE 754 negate (flips the sign bit).

Sourceval min : t -> t -> t

IEEE 754 minNum. If one argument is NaN the other is returned. On +0 and -0 the first argument is returned, so min is deterministic but not commutative on zeros; minimum is.

Sourceval max : t -> t -> t

IEEE 754 maxNum, with the same NaN and signed-zero behaviour as min.

Sourceval copy_sign : t -> t -> t

copy_sign x y is x carrying the sign bit of y (IEEE 754 copySign, Rust's copysign). Applies to NaN like any other value.

Sourceval minimum : t -> t -> t

IEEE 754-2019 minimum: like min, but NaN propagates and -0 is treated as smaller than +0, which makes it commutative everywhere.

Sourceval maximum : t -> t -> t

IEEE 754-2019 maximum, the counterpart to minimum.

Sourceval next_up : t -> t

IEEE 754 nextUp: the least value greater than t, one bit pattern away. next_up neg_infinity is the most negative finite value and next_up infinity is infinity; NaN maps to NaN.

Sourceval next_down : t -> t

IEEE 754 nextDown, the counterpart to next_up.

Sourceval round : rounding_mode -> t -> t

IEEE 754 roundToIntegral: round to an integral value in the given direction, preserving the format.

Comparisons

IEEE 754 semantics: NaN is unordered (all comparisons with it are false), and +0 = -0.

Sourceval eq : t -> t -> bool

IEEE 754 compareQuietEqual.

Sourceval equal : t -> t -> bool

Alias for bits_equal. With compare and hash this is the total, structural triple, for use as a hash-table or Map key. It is not eq: equal nan nan is true and equal zero neg_zero is false.

Sourceval bits_equal : t -> t -> bool

Bitwise equality: two values are equal iff their bit patterns match (so bits_equal nan nan can hold, and bits_equal +0 -0 does not).

Sourceval lt : t -> t -> bool

IEEE 754 compareQuietLess.

Sourceval le : t -> t -> bool

IEEE 754 compareQuietLessEqual.

Sourceval gt : t -> t -> bool

IEEE 754 compareQuietGreater.

Sourceval ge : t -> t -> bool

IEEE 754 compareQuietGreaterEqual.

Sourceval compare : t -> t -> int

The IEEE 754 totalOrder predicate as a comparison returning -1, 0 or 1: a genuine total order on bit patterns, suitable as a Map/Set key. It is not lt/eq: NaNs are ordered rather than unordered (-NaN below -inf, +NaN above +inf), and -0 sorts below +0. So compare x y = 0 holds exactly when bits_equal does, not when eq does.

Sourceval hash : t -> int

A hash of the bit pattern, consistent with equal and compare: equal x y implies hash x = hash y. Allocates nothing.

Classification

Sourceval fpclass : t -> fpclass

Classify per IEEE 754.

Sourceval is_nan : t -> bool

IEEE 754 isNaN.

Sourceval is_infinite : t -> bool

IEEE 754 isInfinite.

Sourceval is_zero : t -> bool

IEEE 754 isZero.

Sourceval is_finite : t -> bool

IEEE 754 isFinite: neither NaN nor an infinity.

Sourceval is_normal : t -> bool

IEEE 754 isNormal.

Sourceval is_subnormal : t -> bool

IEEE 754 isSubnormal.

Sourceval is_negative : t -> bool

A negative non-NaN value, -0 included. This is not IEEE 754 isSignMinus, which is true for a negative NaN.

Sourceval is_positive : t -> bool

A positive non-NaN value, +0 included.

Integer conversions

Sourceval float2int : t -> int_size -> rounding_mode -> signed:bool -> Z.t option

IEEE 754 convertToInteger in the given direction: round to a signed or unsigned integer of the given width. None if t is NaN or infinite, or if the rounded value is out of range for the target type.

Sourceval int2float : Z.t -> int_size -> rounding_mode -> signed:bool -> t

IEEE 754 convertFromInt: round an integer, read at the given width and signedness, to a float.

Total: the argument is the bit-vector's contents, so it is first reduced modulo 2^width and then read at that width. int2float (Z.of_int 200) Int8 m ~signed:true is therefore -56., and int2float Z.minus_one Int8 m ~signed:false is 255..

Pretty-printing

All three produce the same exact decimal: enough digits that of_string reads the value back unchanged, at every precision. Infinities print as "+Inf" and "-Inf", and any NaN as "NaN" — all of which of_string accepts, though a NaN payload does not survive the round trip.

Sourceval to_string : t -> string

Sourceval pp : Format.formatter -> t -> unit

Sourceval show : t -> string

Infix operators

Sourceval (+) : t -> t -> t

Sourceval (-) : t -> t -> t

Sourceval (*) : t -> t -> t

Sourceval (/) : t -> t -> t

Sourceval (mod) : t -> t -> t

rem (IEEE remainder).

Sourceval (=) : t -> t -> bool

Sourceval (<) : t -> t -> bool

Sourceval (<=) : t -> t -> bool

Sourceval (>) : t -> t -> bool

Sourceval (>=) : t -> t -> bool

package floatml

Module Floatml.F32Source