Struct half::bf16

pub struct bf16(/* private fields */);

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

pub const fn from_bits(bits: u16) -> bf16

Constructs a bf16 value from the raw bits.

pub fn from_f32(value: f32) -> bf16

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

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

Converts a bf16 into the underlying bit representation.

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

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]

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]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

pub const DIGITS: u32 = 2u32

Approximate number of bf16 significant digits in base 10.

pub const EPSILON: bf16 = _

bf16 machine epsilon value.

This is the difference between 1.0 and the next largest representable number.

pub const INFINITY: bf16 = _

bf16 positive Infinity (+∞).

pub const MANTISSA_DIGITS: u32 = 8u32

Number of bf16 significant digits in base 2.

pub const MAX: bf16 = _

Largest finite bf16 value.

pub const MAX_10_EXP: i32 = 38i32

Maximum possible bf16 power of 10 exponent.

pub const MAX_EXP: i32 = 128i32

Maximum possible bf16 power of 2 exponent.

pub const MIN: bf16 = _

Smallest finite bf16 value.

pub const MIN_10_EXP: i32 = -37i32

Minimum possible normal bf16 power of 10 exponent.

pub const MIN_EXP: i32 = -125i32

One greater than the minimum possible normal bf16 power of 2 exponent.

pub const MIN_POSITIVE: bf16 = _

Smallest positive normal bf16 value.

pub const NAN: bf16 = _

bf16 Not a Number (NaN).

pub const NEG_INFINITY: bf16 = _

bf16 negative infinity (-∞).

pub const RADIX: u32 = 2u32

The radix or base of the internal representation of bf16.

pub const MIN_POSITIVE_SUBNORMAL: bf16 = _

Minimum positive subnormal bf16 value.

pub const MAX_SUBNORMAL: bf16 = _

Maximum subnormal bf16 value.

pub const ONE: bf16 = _

bf16 1

pub const ZERO: bf16 = _

bf16 0

pub const NEG_ZERO: bf16 = _

bf16 -0

pub const E: bf16 = _

bf16 Euler’s number (ℯ).

pub const PI: bf16 = _

bf16 Archimedes’ constant (π).

pub const FRAC_1_PI: bf16 = _

bf16 1/π

pub const FRAC_1_SQRT_2: bf16 = _

bf16 1/√2

pub const FRAC_2_PI: bf16 = _

bf16 2/π

pub const FRAC_2_SQRT_PI: bf16 = _

bf16 2/√π

pub const FRAC_PI_2: bf16 = _

bf16 π/2

pub const FRAC_PI_3: bf16 = _

bf16 π/3

pub const FRAC_PI_4: bf16 = _

bf16 π/4

pub const FRAC_PI_6: bf16 = _

bf16 π/6

pub const FRAC_PI_8: bf16 = _

bf16 π/8

pub const LN_10: bf16 = _

bf16 𝗅𝗇 10

pub const LN_2: bf16 = _

bf16 𝗅𝗇 2

pub const LOG10_E: bf16 = _

bf16 𝗅𝗈𝗀₁₀ℯ

pub const LOG10_2: bf16 = _

bf16 𝗅𝗈𝗀₁₀2

pub const LOG2_E: bf16 = _

bf16 𝗅𝗈𝗀₂ℯ

pub const LOG2_10: bf16 = _

bf16 𝗅𝗈𝗀₂10

pub const SQRT_2: bf16 = _

bf16 √2

Trait Implementations

impl Clone for bf16

fn clone(&self) -> bf16

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for bf16

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for bf16

fn default() -> bf16

Returns the “default value” for a type.

impl Display for bf16

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<bf16> for f32

fn from(x: bf16) -> f32

Converts to this type from the input type.

impl From<bf16> for f64

fn from(x: bf16) -> f64

Converts to this type from the input type.

impl From<i8> for bf16

fn from(x: i8) -> bf16

Converts to this type from the input type.

impl From<u8> for bf16

fn from(x: u8) -> bf16

Converts to this type from the input type.

impl FromStr for bf16

type Err = ParseFloatError

The associated error which can be returned from parsing.

fn from_str(src: &str) -> Result<bf16, ParseFloatError>

Parses a string s to return a value of this type.

impl LowerExp for bf16

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for bf16

fn eq(&self, other: &bf16) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for bf16

fn partial_cmp(&self, other: &bf16) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &bf16) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &bf16) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &bf16) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &bf16) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl UpperExp for bf16

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Copy for bf16