Struct half::bf16 [−][src]
#[repr(transparent)]pub struct bf16(_);
Expand description
A 16-bit floating point type implementing the bfloat16
format.
The bfloat16
floating point format is a truncated 16-bit version of the IEEE 754 standard
binary32
, a.k.a f32
. bf16
has approximately the same dynamic range as f32
by
having a lower precision than f16
. While f16
has a precision of
11 bits, bf16
has a precision of only 8 bits.
Like f16
, bf16
does not offer arithmetic operations as it is intended for
compact storage rather than calculations. Operations should be performed with f32
or
higher-precision types and converted to/from bf16
as necessary.
Implementations
Constructs a bf16
value from a 32-bit floating point value.
If the 32-bit value is too large to fit, ±∞ will result. NaN values are preserved. Subnormal values that are too tiny to be represented will result in ±0. All other values are truncated and rounded to the nearest representable value.
Constructs a bf16
value from a 64-bit floating point value.
If the 64-bit value is to large to fit, ±∞ will result. NaN values are preserved. 64-bit subnormal values are too tiny to be represented and result in ±0. Exponents that underflow the minimum exponent will result in subnormals or ±0. All other values are truncated and rounded to the nearest representable value.
Returns the memory representation of the underlying bit representation as a byte array in little-endian byte order.
Examples
let bytes = bf16::from_f32(12.5).to_le_bytes();
assert_eq!(bytes, [0x48, 0x41]);
Returns the memory representation of the underlying bit representation as a byte array in big-endian (network) byte order.
Examples
let bytes = bf16::from_f32(12.5).to_be_bytes();
assert_eq!(bytes, [0x41, 0x48]);
Returns the memory representation of the underlying bit representation as a byte array in native byte order.
As the target platform’s native endianness is used, portable code should use
to_be_bytes
or to_le_bytes
, as appropriate,
instead.
Examples
let bytes = bf16::from_f32(12.5).to_ne_bytes();
assert_eq!(bytes, if cfg!(target_endian = "big") {
[0x41, 0x48]
} else {
[0x48, 0x41]
});
Creates a floating point value from its representation as a byte array in little endian.
Examples
let value = bf16::from_le_bytes([0x48, 0x41]);
assert_eq!(value, bf16::from_f32(12.5));
Creates a floating point value from its representation as a byte array in big endian.
Examples
let value = bf16::from_be_bytes([0x41, 0x48]);
assert_eq!(value, bf16::from_f32(12.5));
Creates a floating point value from its representation as a byte array in native endian.
As the target platform’s native endianness is used, portable code likely wants to use
from_be_bytes
or from_le_bytes
, as
appropriate instead.
Examples
let value = bf16::from_ne_bytes(if cfg!(target_endian = "big") {
[0x41, 0x48]
} else {
[0x48, 0x41]
});
assert_eq!(value, bf16::from_f32(12.5));
Returns true
if this value is NaN and false
otherwise.
Examples
let nan = bf16::NAN;
let f = bf16::from_f32(7.0_f32);
assert!(nan.is_nan());
assert!(!f.is_nan());
Returns true
if this value is ±∞ and false
otherwise.
Examples
let f = bf16::from_f32(7.0f32);
let inf = bf16::INFINITY;
let neg_inf = bf16::NEG_INFINITY;
let nan = bf16::NAN;
assert!(!f.is_infinite());
assert!(!nan.is_infinite());
assert!(inf.is_infinite());
assert!(neg_inf.is_infinite());
Returns true
if this number is neither infinite nor NaN.
Examples
let f = bf16::from_f32(7.0f32);
let inf = bf16::INFINITY;
let neg_inf = bf16::NEG_INFINITY;
let nan = bf16::NAN;
assert!(f.is_finite());
assert!(!nan.is_finite());
assert!(!inf.is_finite());
assert!(!neg_inf.is_finite());
Returns true
if the number is neither zero, infinite, subnormal, or NaN.
Examples
let min = bf16::MIN_POSITIVE;
let max = bf16::MAX;
let lower_than_min = bf16::from_f32(1.0e-39_f32);
let zero = bf16::from_f32(0.0_f32);
assert!(min.is_normal());
assert!(max.is_normal());
assert!(!zero.is_normal());
assert!(!bf16::NAN.is_normal());
assert!(!bf16::INFINITY.is_normal());
// Values between 0 and `min` are subnormal.
assert!(!lower_than_min.is_normal());
Returns the floating point category of the number.
If only one property is going to be tested, it is generally faster to use the specific predicate instead.
Examples
use std::num::FpCategory;
let num = bf16::from_f32(12.4_f32);
let inf = bf16::INFINITY;
assert_eq!(num.classify(), FpCategory::Normal);
assert_eq!(inf.classify(), FpCategory::Infinite);
Returns a number that represents the sign of self
.
- 1.0 if the number is positive, +0.0 or
INFINITY
- −1.0 if the number is negative, −0.0
or [
NEG_INFINITY`]bf16::NEG_INFINITY NAN
if the number is NaN
Examples
let f = bf16::from_f32(3.5_f32);
assert_eq!(f.signum(), bf16::from_f32(1.0));
assert_eq!(bf16::NEG_INFINITY.signum(), bf16::from_f32(-1.0));
assert!(bf16::NAN.signum().is_nan());
Returns true
if and only if self
has a positive sign, including +0.0, NaNs with a
positive sign bit and +∞.
Examples
let nan = bf16::NAN;
let f = bf16::from_f32(7.0_f32);
let g = bf16::from_f32(-7.0_f32);
assert!(f.is_sign_positive());
assert!(!g.is_sign_positive());
// NaN can be either positive or negative
assert!(nan.is_sign_positive() != nan.is_sign_negative());
Returns true
if and only if self
has a negative sign, including −0.0, NaNs with a
negative sign bit and −∞.
Examples
let nan = bf16::NAN;
let f = bf16::from_f32(7.0f32);
let g = bf16::from_f32(-7.0f32);
assert!(!f.is_sign_negative());
assert!(g.is_sign_negative());
// NaN can be either positive or negative
assert!(nan.is_sign_positive() != nan.is_sign_negative());
Returns a number composed of the magnitude of self
and the sign of sign
.
Equal to self
if the sign of self
and sign
are the same, otherwise equal to -self
.
If self
is NaN, then NaN with the sign of sign
is returned.
Examples
let f = bf16::from_f32(3.5);
assert_eq!(f.copysign(bf16::from_f32(0.42)), bf16::from_f32(3.5));
assert_eq!(f.copysign(bf16::from_f32(-0.42)), bf16::from_f32(-3.5));
assert_eq!((-f).copysign(bf16::from_f32(0.42)), bf16::from_f32(3.5));
assert_eq!((-f).copysign(bf16::from_f32(-0.42)), bf16::from_f32(-3.5));
assert!(bf16::NAN.copysign(bf16::from_f32(1.0)).is_nan());
Returns the maximum of the two numbers.
If one of the arguments is NaN, then the other argument is returned.
Examples
let x = bf16::from_f32(1.0);
let y = bf16::from_f32(2.0);
assert_eq!(x.max(y), y);
Returns the minimum of the two numbers.
If one of the arguments is NaN, then the other argument is returned.
Examples
let x = bf16::from_f32(1.0);
let y = bf16::from_f32(2.0);
assert_eq!(x.min(y), x);
Restrict a value to a certain interval unless it is NaN.
Returns max
if self
is greater than max
, and min
if self
is less than min
.
Otherwise this returns self
.
Note that this function returns NaN if the initial value was NaN as well.
Panics
Panics if min > max
, min
is NaN, or max
is NaN.
Examples
assert!(bf16::from_f32(-3.0).clamp(bf16::from_f32(-2.0), bf16::from_f32(1.0)) == bf16::from_f32(-2.0));
assert!(bf16::from_f32(0.0).clamp(bf16::from_f32(-2.0), bf16::from_f32(1.0)) == bf16::from_f32(0.0));
assert!(bf16::from_f32(2.0).clamp(bf16::from_f32(-2.0), bf16::from_f32(1.0)) == bf16::from_f32(1.0));
assert!(bf16::NAN.clamp(bf16::from_f32(-2.0), bf16::from_f32(1.0)).is_nan());
bf16
machine epsilon value
This is the difference between 1.0 and the next largest representable number.
Number of bf16
significant digits in base 2
Maximum possible bf16
power of 10 exponent
Minimum possible normal bf16
power of 10 exponent
Smallest positive normal bf16
value
bf16
negative infinity (-∞).
Minimum positive subnormal bf16
value
Maximum subnormal bf16
value
bf16
1/√2
bf16
2/√π
Trait Implementations
Performs the +=
operation. Read more
Performs the +=
operation. Read more
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
__D: Deserializer<'de>,
Deserialize this value from the given Serde deserializer. Read more
Performs the /=
operation. Read more
Performs the /=
operation. Read more
Returns the negative infinite value. Read more
Returns the smallest finite value that this type can represent. Read more
Returns the smallest positive, normalized value that this type can represent. Read more
Returns true
if this value is positive infinity or negative infinity and
false otherwise. Read more
Returns the floating point category of the number. If only one property is going to be tested, it is generally faster to use the specific predicate instead. Read more
Returns the nearest integer to a number. Round half-way cases away from
0.0
. Read more
Computes the absolute value of self
. Returns Float::nan()
if the
number is Float::nan()
. Read more
Returns true
if self
is positive, including +0.0
,
Float::infinity()
, and since Rust 1.20 also Float::nan()
. Read more
Returns true
if self
is negative, including -0.0
,
Float::neg_infinity()
, and since Rust 1.20 also -Float::nan()
. Read more
Fused multiply-add. Computes (self * a) + b
with only one rounding
error, yielding a more accurate result than an unfused multiply-add. Read more
Returns the logarithm of the number with respect to an arbitrary base. Read more
Converts radians to degrees. Read more
Converts degrees to radians. Read more
Calculate the length of the hypotenuse of a right-angle triangle given
legs of length x
and y
. Read more
Computes the arcsine of a number. Return value is in radians in the range [-pi/2, pi/2] or NaN if the number is outside the range [-1, 1]. Read more
Computes the arccosine of a number. Return value is in radians in the range [0, pi] or NaN if the number is outside the range [-1, 1]. Read more
Computes the arctangent of a number. Return value is in radians in the range [-pi/2, pi/2]; Read more
Computes the four quadrant arctangent of self
(y
) and other
(x
). Read more
Simultaneously computes the sine and cosine of the number, x
. Returns
(sin(x), cos(x))
. Read more
Returns e^(self) - 1
in a way that is accurate even if the
number is close to zero. Read more
Returns ln(1+n)
(natural logarithm) more accurately than if
the operations were performed separately. Read more
Return 1.0 / sqrt(2.0)
.
Return 2.0 / sqrt(π)
.
Returns negative infinity. Read more
Returns the smallest finite value that this type can represent. Read more
Returns the smallest positive, normalized value that this type can represent. Read more
Returns true
if the number is infinite. Read more
Returns true
if the number is neither zero, infinite, subnormal or NaN. Read more
Returns the floating point category of the number. If only one property is going to be tested, it is generally faster to use the specific predicate instead. Read more
Returns the nearest integer to a number. Round half-way cases away from 0.0
. Read more
Computes the absolute value of self
. Returns FloatCore::nan()
if the
number is FloatCore::nan()
. Read more
Returns true
if self
is positive, including +0.0
and
FloatCore::infinity()
, and since Rust 1.20 also
FloatCore::nan()
. Read more
Returns true
if self
is negative, including -0.0
and
FloatCore::neg_infinity()
, and since Rust 1.20 also
-FloatCore::nan()
. Read more
Converts to degrees, assuming the number is in radians. Read more
Converts to radians, assuming the number is in degrees. Read more
Converts an i64
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts an u64
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts an i8
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts an u8
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts an i16
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts an u16
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts an i32
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts an u32
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts a f32
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts a f64
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts an isize
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts an i128
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
Converts a usize
to return an optional value of this type. If the
value cannot be represented by this type, then None
is returned. Read more
type Err = ParseFloatError
type Err = ParseFloatError
The associated error which can be returned from parsing.
Performs the *=
operation. Read more
Performs the *=
operation. Read more
type FromStrRadixErr = <f32 as Num>::FromStrRadixErr
Convert from a string and radix (typically 2..=36
). Read more
Creates a number from another value that can be converted into
a primitive via the ToPrimitive
trait. If the source value cannot be
represented by the target type, then None
is returned. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
Performs the %=
operation. Read more
Performs the %=
operation. Read more
Performs the -=
operation. Read more
Performs the -=
operation. Read more
Converts the value of self
to an i64
. If the value cannot be
represented by an i64
, then None
is returned. Read more
Converts the value of self
to a u64
. If the value cannot be
represented by a u64
, then None
is returned. Read more
Converts the value of self
to an i8
. If the value cannot be
represented by an i8
, then None
is returned. Read more
Converts the value of self
to a u8
. If the value cannot be
represented by a u8
, then None
is returned. Read more
Converts the value of self
to an i16
. If the value cannot be
represented by an i16
, then None
is returned. Read more
Converts the value of self
to a u16
. If the value cannot be
represented by a u16
, then None
is returned. Read more
Converts the value of self
to an i32
. If the value cannot be
represented by an i32
, then None
is returned. Read more
Converts the value of self
to a u32
. If the value cannot be
represented by a u32
, then None
is returned. Read more
Converts the value of self
to an f32
. Overflows may map to positive
or negative inifinity, otherwise None
is returned if the value cannot
be represented by an f32
. Read more
Converts the value of self
to an f64
. Overflows may map to positive
or negative inifinity, otherwise None
is returned if the value cannot
be represented by an f64
. Read more
Converts the value of self
to an isize
. If the value cannot be
represented by an isize
, then None
is returned. Read more
Converts the value of self
to an i128
. If the value cannot be
represented by an i128
(i64
under the default implementation), then
None
is returned. Read more
Converts the value of self
to a usize
. If the value cannot be
represented by a usize
, then None
is returned. Read more
Auto Trait Implementations
impl RefUnwindSafe for bf16
impl UnwindSafe for bf16
Blanket Implementations
Mutably borrows from an owned value. Read more
Returns the smallest finite value that this type can represent. Read more
Returns the smallest positive, normalized value that this type can represent. Read more
Returns the largest finite value that this type can represent. Read more
Returns the smallest integer greater than or equal to a number. Read more
Returns the nearest integer to a number. Round half-way cases away from
0.0
. Read more
Computes the absolute value of self
. Returns Float::nan()
if the
number is Float::nan()
. Read more
Returns true
if self
is positive, including +0.0
,
Float::infinity()
, and with newer versions of Rust f64::NAN
. Read more
Returns true
if self
is negative, including -0.0
,
Float::neg_infinity()
, and with newer versions of Rust -f64::NAN
. Read more
Fused multiply-add. Computes (self * a) + b
with only one rounding
error, yielding a more accurate result than an unfused multiply-add. Read more
Returns the logarithm of the number with respect to an arbitrary base. Read more
Converts radians to degrees. Read more
Converts degrees to radians. Read more
Calculate the length of the hypotenuse of a right-angle triangle given
legs of length x
and y
. Read more
Computes the arcsine of a number. Return value is in radians in the range [-pi/2, pi/2] or NaN if the number is outside the range [-1, 1]. Read more
Computes the arccosine of a number. Return value is in radians in the range [0, pi] or NaN if the number is outside the range [-1, 1]. Read more
Computes the arctangent of a number. Return value is in radians in the range [-pi/2, pi/2]; Read more
Computes the four quadrant arctangent of self
(y
) and other
(x
). Read more
Simultaneously computes the sine and cosine of the number, x
. Returns
(sin(x), cos(x))
. Read more
Returns e^(self) - 1
in a way that is accurate even if the
number is close to zero. Read more
Returns ln(1+n)
(natural logarithm) more accurately than if
the operations were performed separately. Read more