Trait ieee754::Ieee754

source ·
pub trait Ieee754: Copy + PartialEq + PartialOrd {
    type Bits: Bits;
    type Exponent;
    type RawExponent;
    type Significand;

    fn upto(self, lim: Self) -> Iter<Self> ;
    fn next(self) -> Self;
    fn ulp(self) -> Option<Self>;
    fn prev(self) -> Self;
    fn bits(self) -> Self::Bits;
    fn from_bits(x: Self::Bits) -> Self;
    fn exponent_bias() -> Self::Exponent;
    fn decompose_raw(self) -> (bool, Self::RawExponent, Self::Significand);
    fn recompose_raw(
        sign: bool,
        expn: Self::RawExponent,
        signif: Self::Significand
    ) -> Self; fn decompose(self) -> (bool, Self::Exponent, Self::Significand); fn recompose(
        sign: bool,
        expn: Self::Exponent,
        signif: Self::Significand
    ) -> Self; }
Expand description

Types that are IEEE754 floating point numbers.

Required Associated Types§

A type that represents the raw bits of Self.

A type large enough to store the true exponent of Self.

A type large enough to store the raw exponent (i.e. with the bias).

A type large enough to store the significand of Self.

Required Methods§

Iterate over each value of Self in [self, lim].

The returned iterator will include subnormal numbers, and will only include one of -0.0 and 0.0.

Panics

Panics if self > lim, or if either are NaN.

Examples
use ieee754::Ieee754;

// there are 840 single-precision floats in between 1.0 and 1.0001
// (inclusive).
assert_eq!(1_f32.upto(1.0001).count(), 840);

Return the next value after self.

Calling this on NaN or positive infinity will yield nonsense.

Examples
use ieee754::Ieee754;
let x: f32 = 1.0;
assert_eq!(x.next(), 1.000000119209);

Return the unit-in-the-last-place ulp of self. That is, x.abs().next() - x.abs(), but handling overflow properly.

Returns None if self is not finite.

Return the previous value before self.

Calling this on NaN or negative infinity will yield nonsense.

Examples
use ieee754::Ieee754;
let x: f32 = 1.0;
assert_eq!(x.prev(), 0.99999995);

View self as a collection of bits.

Examples
use ieee754::Ieee754;
let x: f32 = 1.0;
assert_eq!(x.bits(), 0x3f80_0000);

View a collections of bits as a floating point number.

Examples
use ieee754::Ieee754;
let float: f32 = Ieee754::from_bits(0xbf80_0000);
assert_eq!(float, -1.0);

Get the bias of the stored exponent.

Examples
use ieee754::Ieee754;

assert_eq!(f32::exponent_bias(), 127);
assert_eq!(f64::exponent_bias(), 1023);

Break self into the three constituent parts of an IEEE754 float.

The exponent returned is the raw bits, use exponent_bias to compute the offset required or use decompose to obtain this in precomputed form.

Examples

Single precision:

use ieee754::Ieee754;

assert_eq!(1_f32.decompose_raw(), (false, 127, 0));
assert_eq!(1234.567_f32.decompose_raw(), (false, 137, 0x1a5225));

assert_eq!((-0.525_f32).decompose_raw(), (true, 126, 0x66666));

assert_eq!(std::f32::INFINITY.decompose_raw(), (false, 255, 0));

let (sign, expn, signif) = std::f32::NAN.decompose_raw();
assert_eq!((sign, expn), (false, 255));
assert!(signif != 0);

Double precision:

use ieee754::Ieee754;

assert_eq!(1_f64.decompose_raw(), (false, 1023, 0));
assert_eq!(1234.567_f64.decompose_raw(), (false, 1033, 0x34a449ba5e354));

assert_eq!((-0.525_f64).decompose_raw(), (true, 1022, 0xcccc_cccc_cccd));

assert_eq!(std::f64::INFINITY.decompose_raw(), (false, 2047, 0));

let (sign, expn, signif) = std::f64::NAN.decompose_raw();
assert_eq!((sign, expn), (false, 2047));
assert!(signif != 0);

Create a Self out of the three constituent parts of an IEEE754 float.

The exponent should be the raw bits, use exponent_bias to compute the offset required, or use recompose to feed in the unbiased exponent.

Examples

Single precision:

use ieee754::Ieee754;

assert_eq!(f32::recompose_raw(false, 127, 0), 1.0);
assert_eq!(f32::recompose_raw(false, 137, 0x1a5225), 1234.567);
assert_eq!(f32::recompose_raw(true, 126, 0x66666), -0.525);

assert_eq!(f32::recompose_raw(false, 255, 0), std::f32::INFINITY);

assert!(f32::recompose_raw(false, 255, 1).is_nan());

Double precision:

use ieee754::Ieee754;

assert_eq!(f64::recompose_raw(false, 1023, 0), 1.0);
assert_eq!(f64::recompose_raw(false, 1033, 0x34a449ba5e354), 1234.567);
assert_eq!(f64::recompose_raw(true, 1022, 0xcccc_cccc_cccd), -0.525);

assert_eq!(f64::recompose_raw(false, 2047, 0), std::f64::INFINITY);

assert!(f64::recompose_raw(false, 2047, 1).is_nan());

Break self into the three constituent parts of an IEEE754 float.

The exponent returned is the true exponent, after accounting for the bias it is stored with. The significand does not include the implicit highest bit (if it exists), e.g. the 24-bit for single precision.

Examples

Single precision:

use ieee754::Ieee754;

assert_eq!(1_f32.decompose(), (false, 0, 0));
assert_eq!(1234.567_f32.decompose(), (false, 10, 0x1a5225));

assert_eq!((-0.525_f32).decompose(), (true, -1, 0x66666));

assert_eq!(std::f32::INFINITY.decompose(), (false, 128, 0));

let (sign, expn, signif) = std::f32::NAN.decompose();
assert_eq!((sign, expn), (false, 128));
assert!(signif != 0);

Double precision:

use ieee754::Ieee754;

assert_eq!(1_f64.decompose(), (false, 0, 0));
assert_eq!(1234.567_f64.decompose(), (false, 10, 0x34a449ba5e354));

assert_eq!((-0.525_f64).decompose(), (true, -1, 0xcccc_cccc_cccd));

assert_eq!(std::f64::INFINITY.decompose(), (false, 1024, 0));

let (sign, expn, signif) = std::f64::NAN.decompose();
assert_eq!((sign, expn), (false, 1024));
assert!(signif != 0);

Create a Self out of the three constituent parts of an IEEE754 float.

The exponent should be true exponent, not accounting for any bias. The significand should not include the implicit highest bit (if it exists), e.g. the 24-th bit for signle precision.

Examples

Single precision:

use ieee754::Ieee754;

assert_eq!(f32::recompose(false, 0, 0), 1.0);
assert_eq!(f32::recompose(false, 10, 0x1a5225), 1234.567);
assert_eq!(f32::recompose(true, -1, 0x66666), -0.525);

assert_eq!(f32::recompose(false, 128, 0), std::f32::INFINITY);

assert!(f32::recompose(false, 128, 1).is_nan());

Double precision:

use ieee754::Ieee754;

assert_eq!(f64::recompose(false, 0, 0), 1.0);
assert_eq!(f64::recompose(false, 10, 0x34a449ba5e354), 1234.567);
assert_eq!(f64::recompose(true, -1, 0xcccc_cccc_cccd), -0.525);

assert_eq!(f64::recompose(false, 1024, 0), std::f64::INFINITY);

assert!(f64::recompose(false, 1024, 1).is_nan());

Implementations on Foreign Types§

Implementors§