f16 - Rust
Skip to main content f16 Primitive Type f16 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Expand description A 16-bit floating-point type (specifically, the βbinary16β type defined in IEEE 754-2008). This type is very similar to f32 but has decreased precision because it uses half as many bits. Please see the documentation for f32 or Wikipedia on half-precision values for more information. Note that most common platforms will not support f16 in hardware without enabling extra target features, with the notable exception of Apple Silicon (also known as M1, M2, etc.) processors.
Hardware support on x86/x86-64 requires the avx512fp16 or avx10.1 features, while RISC-V requires Zfh, and Arm/AArch64 requires FEAT_FP16. Usually the fallback implementation will be to use f32 hardware if it exists, and convert between f16 and f32 when performing math. See also the std::f16::consts module . Implementations Β§ Source Β§ impl f16 Source pub const RADIX : u32 = 2 π¬ This is a nightly-only experimental API. ( f16 #116909 ) The radix or base of the internal representation of f16 .
Source pub const BITS : u32 = 16 π¬ This is a nightly-only experimental API. ( float_bits_const #151073 ) The size of this float type in bits. Source pub const MANTISSA_DIGITS : u32 = 11 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Number of significant digits in base 2. Note that the size of the mantissa in the bitwise representation is one smaller than this since the leading 1 is not stored explicitly.
Source pub const DIGITS : u32 = 3 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Approximate number of significant digits in base 10. This is the maximum x such that any decimal number with x significant digits can be converted to f16 and back without loss. Equal to floor(log 10 2 MANTISSA_DIGITS β 1 ). Source pub const EPSILON : f16 = 9.7656e-4_f16 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Machine epsilon value for f16 .
This is the difference between 1.0 and the next larger representable number. Equal to 2 1 β MANTISSA_DIGITS . Source pub const MIN : f16 = -6.5504e+4_f16 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Smallest finite f16 value. Equal to β MAX . Source pub const MIN_POSITIVE : f16 = 6.1035e-5_f16 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Smallest positive normal f16 value. Equal to 2 MIN_EXP β 1 .
Source pub const MAX : f16 = 6.5504e+4_f16 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Largest finite f16 value. Equal to (1 β 2 β MANTISSA_DIGITS ) 2 MAX_EXP . Source pub const MIN_EXP : i32 = -13 π¬ This is a nightly-only experimental API. ( f16 #116909 ) One greater than the minimum possible normal power of 2 exponent for a significand bounded by 1 β€ x < 2 (i.e. the IEEE definition). This corresponds to the exact minimum possible normal power of 2 exponent for a significand bounded by 0.5 β€ x < 1 (i.e. the C definition).
In other words, all normal numbers representable by this type are greater than or equal to 0.5 Γ 2 MIN_EXP . Source pub const MAX_EXP : i32 = 16 π¬ This is a nightly-only experimental API. ( f16 #116909 ) One greater than the maximum possible power of 2 exponent for a significand bounded by 1 β€ x < 2 (i.e. the IEEE definition). This corresponds to the exact maximum possible power of 2 exponent for a significand bounded by 0.5 β€ x < 1 (i.e. the C definition).
In other words, all numbers representable by this type are strictly less than 2 MAX_EXP . Source pub const MIN_10_EXP : i32 = -4 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Minimum x for which 10 x is normal. Equal to ceil(log 10 MIN_POSITIVE ). Source pub const MAX_10_EXP : i32 = 4 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Maximum x for which 10 x is normal. Equal to floor(log 10 MAX ).
Source pub const NAN : f16 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Not a Number (NaN). Note that IEEE 754 doesnβt define just a single NaN value; a plethora of bit patterns are considered to be NaN. Furthermore, the standard makes a difference between a βsignalingβ and a βquietβ NaN, and allows inspecting its βpayloadβ (the unspecified bits in the bit pattern) and its sign. See the specification of NaN bit patterns for more info.
This constant is guaranteed to be a quiet NaN (on targets that follow the Rust assumptions that the quiet/signaling bit being set to 1 indicates a quiet NaN). Beyond that, nothing is guaranteed about the specific bit pattern chosen here: both payload and sign are arbitrary. The concrete bit pattern may change across Rust versions and target platforms. Source pub const INFINITY : f16 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Infinity (β).
Source pub const NEG_INFINITY : f16 π¬ This is a nightly-only experimental API. ( f16 #116909 ) Negative infinity (ββ). Source pub const MAX_EXACT_INTEGER : i16 π¬ This is a nightly-only experimental API. ( float_exact_integer_constants #152466 ) Maximum integer that can be represented exactly in an f16 value, with no other integer converting to the same floating point value. For an integer x which satisfies MIN_EXACT_INTEGER <= x <= MAX_EXACT_INTEGER , there is a βone-to-oneβ mapping between i16 and f16 values.
MAX_EXACT_INTEGER + 1 also converts losslessly to f16 and back to i16 , but MAX_EXACT_INTEGER + 2 converts to the same f16 value (and back to MAX_EXACT_INTEGER + 1 as an integer) so there is not a βone-to-oneβ mapping. #![feature(f16)] #![feature(float_exact_integer_constants)] let max_exact_int = f16::MAX_EXACT_INTEGER; assert_eq! (max_exact_int, max_exact_int as f16 as i16); assert_eq! (max_exact_int + 1 , (max_exact_int + 1 ) as f16 as i16); assert_ne! (max_exact_int + 2 , (max_exact_int + 2 ) as f16 as i16); // Beyond `f16::MAX_EXACT_INTEGER`, multiple integers can map to one float value assert_eq! ((max_exact_int + 1 ) as f16, (max_exact_int + 2 ) as f16); Source pub const MIN_EXACT_INTEGER : i16 π¬ This is a nightly-only experimental API. ( float_exact_integer_constants #152466 ) Minimum integer that can be represented exactly in an f16 value, with no other integer converting to the same floating point value.
For an integer x which satisfies MIN_EXACT_INTEGER <= x <= MAX_EXACT_INTEGER , there is a βone-to-oneβ mapping between i16 and f16 values. MAX_EXACT_INTEGER + 1 also converts losslessly to f16 and back to i16 , but MAX_EXACT_INTEGER + 2 converts to the same f16 value (and back to MAX_EXACT_INTEGER + 1 as an integer) so there is not a βone-to-oneβ mapping. This constant is equivalent to -MAX_EXACT_INTEGER . #![feature(f16)] #![feature(float_exact_integer_constants)] let min_exact_int = f16::MIN_EXACT_INTEGER; assert_eq! (min_exact_int, min_exact_int as f16 as i16); assert_eq! (min_exact_int - 1 , (min_exact_int - 1 ) as f16 as i16); assert_ne! (min_exact_int - 2 , (min_exact_int - 2 ) as f16 as i16); // Below `f16::MIN_EXACT_INTEGER`, multiple integers can map to one float value assert_eq! ((min_exact_int - 1 ) as f16, (min_exact_int - 2 ) as f16); Source pub const SIGN_MASK : u16 = 0x8000 π¬ This is a nightly-only experimental API. ( float_masks #154064 ) The mask of the bit used to encode the sign of an f16 .
This bit is set when the sign is negative and unset when the sign is positive. If you only need to check whether a value is positive or negative, is_sign_positive or is_sign_negative can be used. #![feature(float_masks)] #![feature(f16)] let sign_mask = f16::SIGN_MASK; let a = 1.6552f16 ; let a_bits = a.to_bits(); assert_eq! (a_bits & sign_mask, 0x0 ); assert_eq! (f16::from_bits(a_bits ^ sign_mask), -a); assert_eq! (sign_mask, (- 0.0f16 ).to_bits()); Source pub const EXPONENT_MASK : u16 = 0x7c00 π¬ This is a nightly-only experimental API. ( float_masks #154064 ) The mask of the bits used to encode the exponent of an f16 .
Note that the exponent is stored as a bia
The rest of this page is on the live site.