Struct half::bf16[−][src]

#[repr(transparent)]
pub struct bf16(_);

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

`impl bf16`[src]

`pub const fn from_bits(bits: u16) -> bf16`[src]

Constructs a bf16 value from the raw bits.

`pub fn from_f32(value: f32) -> bf16`[src]

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.

`pub fn from_f64(value: f64) -> bf16`[src]

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.

`pub const fn to_bits(self) -> u16`[src]

Converts a bf16 into the underlying bit representation.

`pub fn to_le_bytes(self) -> [u8; 2]`[src]

Return 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]);

`pub fn to_be_bytes(self) -> [u8; 2]`[src]

Return 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]);

`pub fn to_ne_bytes(self) -> [u8; 2]`[src]

Return 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]
});

`pub fn from_le_bytes(bytes: [u8; 2]) -> bf16`[src]

Create 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));

`pub fn from_be_bytes(bytes: [u8; 2]) -> bf16`[src]

Create 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));

`pub fn from_ne_bytes(bytes: [u8; 2]) -> bf16`[src]

Create 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));

`pub fn to_f32(self) -> f32`[src]

Converts a bf16 value into an f32 value.

This conversion is lossless as all values can be represented exactly in f32.

`pub fn to_f64(self) -> f64`[src]

Converts a bf16 value into an f64 value.

This conversion is lossless as all values can be represented exactly in f64.

`pub const fn is_nan(self) -> bool`[src]

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());

`pub const fn is_infinite(self) -> bool`[src]

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());

`pub const fn is_finite(self) -> bool`[src]

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());

`pub fn is_normal(self) -> bool`[src]

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());

`pub fn classify(self) -> FpCategory`[src]

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);

`pub fn signum(self) -> bf16`[src]

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.0orNEG_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());

`pub const fn is_sign_positive(self) -> bool`[src]

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());

`pub const fn is_sign_negative(self) -> bool`[src]

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());