Struct f256

pub struct f256 { /* private fields */ }

A 256-bit floating point type (specifically, the “binary256” type defined in IEEE 754-2008).

For details see above.

Implementations

impl f256

pub fn asin(&self) -> Self

Computes the arcsinus of a number (in radians).

Return value is in radians in the range [-½π, ½π], or NaN if the number is outside the range [-1, 1].

pub fn acos(&self) -> Self

Computes the arccosinus of a number (in radians).

Return value is in radians in the range [0, π], or NaN if the number is outside the range [-1, 1].

impl f256

pub fn atan(&self) -> Self

Computes the arctangent of a number (in radians).

Return value is in radians in the range [-½π, ½π].

pub fn atan2(&self, other: &Self) -> Self

Computes the four quadrant arctangent of self (y) and other (x) in radians.

• x = 0, y = 0: 0
• x >= 0: arctan(y/x) -> [-½π, ½π]
• y >= 0: arctan(y/x) + π -> (½π, π]
• y < 0: arctan(y/x) - π -> (-π, -½π)

impl f256

pub fn cos(&self) -> Self

Computes the cosine of a number (in radians).

impl f256

pub fn sin(&self) -> Self

Computes the sine of a number (in radians).

impl f256

pub fn sin_cos(&self) -> (Self, Self)

Simultaneously computes the sine and cosine of the number x (in radians).

Returns (sin(x), cos(x)).

impl f256

pub fn tan(&self) -> Self

Computes the tangent of a number (in radians).

impl f256

pub fn exp(&self) -> Self

Returns e^(self), (the exponential function).

pub fn exp_m1(&self) -> Self

Returns e^(self) - 1 in a way that is accurate even if the number is close to zero.

pub fn exp2(&self) -> Self

Returns 2^(self).

impl f256

pub fn log(&self, base: &Self) -> Self

Returns the logarithm of the number with respect to an arbitrary base.

The result might not be correctly rounded owing to implementation details; self.log2() can produce more accurate results for base 2, and self.log10() can produce more accurate results for base 10.

pub fn ln(&self) -> Self

Returns the natural logarithm of the number.

pub fn ln_1p(&self) -> Self

Returns ln(1+n) (natural logarithm) more accurately than if the operations were performed separately.

pub fn log2(&self) -> Self

Returns the base 2 logarithm of the number.

pub fn log10(&self) -> Self

Returns the base 10 logarithm of the number.

impl f256

pub fn powi(&self, n: i32) -> Self

Raises a number to an integer power.

pub fn powf(&self, exp: &Self) -> Self

Raises a number to a floating point power.

impl f256

pub fn sqrt(self) -> Self

Returns the square root of self.

Returns NaN if self is a negative number other than -0.0.

Examples

let f = f256::from(1822500);
assert_eq!(f.sqrt(), f256::from(1350));
assert!(f256::NEG_ONE.sqrt().is_nan());
assert_eq!(f256::NEG_ZERO.sqrt(), f256::NEG_ZERO);

impl f256

pub const RADIX: u32 = 2u32

The radix or base of the internal representation of f256.

pub const MANTISSA_DIGITS: u32 = 237u32

Number of significant digits in base 2: 237.

pub const SIGNIFICANT_DIGITS: u32 = 237u32

Number of significant digits in base 2: 237.

pub const DIGITS: u32 = 71u32

Approximate number of significant digits in base 10: ⌊log₁₀(2²³⁷)⌋.

pub const EPSILON: Self = EPSILON

The difference between 1.0 and the next larger representable number: 2⁻²³⁶ ≈ 9.055679 × 10⁻⁷².

pub const MAX: Self = MAX

Largest finite f256 value: 2²⁶²¹⁴⁴ − 2²⁶¹⁹⁰⁷ ≈ 1.6113 × 10⁷⁸⁹¹³.

pub const MIN: Self = MIN

Smallest finite f256 value: 2²⁶¹⁹⁰⁷ - 2²⁶²¹⁴⁴ ≈ -1.6113 × 10⁷⁸⁹¹³.

pub const MIN_POSITIVE: Self = MIN_POSITIVE

Smallest positive normal f256 value: 2⁻²⁶²¹⁴² ≈ 2.4824 × 10⁻⁷⁸⁹¹³.

pub const MIN_GT_ZERO: Self = MIN_GT_ZERO

Smallest positive subnormal f256 value: 2⁻²⁶²³⁷⁸ ≈ 2.248 × 10⁻⁷⁸⁹⁸⁴.

pub const MAX_EXP: i32 = 262_144i32

Maximum possible power of 2 exponent: Eₘₐₓ + 1 = 2¹⁸ = 262144.

pub const MIN_EXP: i32 = -262_141i32

One greater than the minimum possible normal power of 2 exponent: Eₘᵢₙ + 1 = -262141.

pub const MAX_10_EXP: i32 = 78_913i32

Maximum possible power of 10 exponent: ⌊(Eₘₐₓ + 1) × log₁₀(2)⌋.

pub const MIN_10_EXP: i32 = -78_912i32

Minimum possible normal power of 10 exponent: ⌊(Eₘᵢₙ + 1) × log₁₀(2)⌋.

pub const NAN: Self = NAN

Not a Number (NaN).

Note that IEEE-745 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). This implementation does not make such a difference and uses exactly one bit pattern for NaN.

pub const INFINITY: Self = INFINITY

Infinity (∞).

pub const NEG_INFINITY: Self = NEG_INFINITY

Negative infinity (−∞).

pub const ZERO: Self = ZERO

Additive identity (0.0).

pub const NEG_ZERO: Self = NEG_ZERO

Negative additive identity (-0.0).

pub const ONE: Self = ONE

Multiplicative identity (1.0).

pub const NEG_ONE: Self = NEG_ONE

Multiplicative negator (-1.0).

pub const TWO: Self = TWO

Equivalent of binary base (2.0).

pub const TEN: Self = TEN

Equivalent of decimal base (10.0).

pub const fn is_nan(self) -> bool

Returns true if this value is NaN.

pub const fn is_infinite(self) -> bool

Returns true if this value is positive infinity or negative infinity, and false otherwise.

pub const fn is_finite(self) -> bool

Returns true if this number is neither infinite nor NaN.

pub const fn is_subnormal(self) -> bool

Returns true if the number is subnormal.

pub const fn is_normal(self) -> bool

Returns true if the number is neither zero, infinite, subnormal, or NaN.

pub const 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.

pub const fn eq_zero(self) -> bool

Returns true if self is equal to +0.0 or -0.0.

pub const fn is_special(self) -> bool

Returns true if self is either not a number, infinite or equal to zero.

pub const fn is_sign_positive(self) -> bool

Returns true if self has a positive sign, including +0.0, positive infinity and NaN.

pub const fn is_sign_negative(self) -> bool

Returns true if self has a negative sign, including -0.0 and negative infinity.

pub fn ulp(&self) -> Self

Returns the unit in the last place of self.

ULP denotes the magnitude of the last significand digit of self.

pub fn recip(self) -> Self

Returns the reciprocal (multiplicative inverse) of self.

Examples

let f = f256::from(16);
let r = f256::from(0.0625);
assert_eq!(f.recip(), r);

assert_eq!(f256::INFINITY.recip(), f256::ZERO);
assert_eq!(f256::NEG_ZERO.recip(), f256::NEG_INFINITY);
assert!(f256::NAN.recip().is_nan());

pub fn to_degrees(self) -> Self

Converts radians to degrees.

Returns self * (180 / π)

pub fn to_radians(self) -> Self

Converts degrees to radians.

Returns self * (π / 180)

pub fn max(self, other: Self) -> Self

Returns the maximum of the two numbers, ignoring NaN.

If one of the arguments is NaN, then the other argument is returned. This follows the IEEE-754 2008 semantics for maxNum, except for handling of signaling NaNs; this function handles all NaNs the same way and avoids maxNum’s problems with associativity.

pub fn min(self, other: Self) -> Self

Returns the minimum of the two numbers, ignoring NaN.

If one of the arguments is NaN, then the other argument is returned. This follows the IEEE-754 2008 semantics for minNum, except for handling of signaling NaNs; this function handles all NaNs the same way and avoids minNum’s problems with associativity.

pub const fn to_bits(&self) -> (u128, u128)

Raw transmutation to (u128, u128) ((self.bits.hi.0, self.bits.lo.0), each in native endian order).

pub const fn from_bits(bits: (u128, u128)) -> Self

Raw transmutation from (u128, u128) ((self.bits.hi.0, self.bits.lo.0), each in native endian order).

pub const fn to_be_bytes(self) -> [u8; 32]

Return the memory representation of this floating point number as a byte array in big-endian (network) byte order.

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

Return the memory representation of this floating point number as a byte array in little-endian byte order.

pub const fn to_ne_bytes(self) -> [u8; 32]

Return the memory representation of this floating point number as a byte array in native byte order.

pub const fn from_be_bytes(bytes: [u8; 32]) -> Self

Create a floating point value from its representation as a byte array in big endian.

pub const fn from_le_bytes(bytes: [u8; 32]) -> Self

Create a floating point value from its representation as a byte array in little endian.

pub const fn from_ne_bytes(bytes: [u8; 32]) -> Self

Create a floating point value from its representation as a byte array in native endian.

pub fn total_cmp(&self, other: &Self) -> Ordering

Return the ordering between self and other.

Unlike the standard partial comparison between floating point numbers, this comparison always produces an ordering in accordance to the totalOrder predicate as defined in the IEEE 754 (2008 revision) floating point standard. The values are ordered in the following sequence:

• negative NaN
• negative infinity
• negative numbers
• negative subnormal numbers
• negative zero
• positive zero
• positive subnormal numbers
• positive numbers
• positive infinity
• positive NaN.

The ordering established by this function does not always agree with the PartialOrd and PartialEq implementations of f256. For example, they consider negative and positive zero equal, while total_cmp doesn’t.

pub fn clamp(self, min: Self, max: Self) -> Self

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

let min = f256::EPSILON;
let max = f256::TWO;
let f = f256::ONE;
assert_eq!(f.clamp(min, max), f);
assert_eq!((-f).clamp(min, max), min);

assert_eq!(f256::INFINITY.clamp(f256::MIN, f256::MAX), f256::MAX);
assert!(f256::NAN.clamp(f256::NEG_INFINITY, f256::INFINITY).is_nan());

pub const fn abs(&self) -> Self

Computes the absolute value of self.

Examples

let f = f256::from(138);
assert_eq!(f.abs(), f);
assert_eq!((-f).abs(), f);

assert_eq!(f256::MIN.abs(), f256::MAX);
assert_eq!(f256::NEG_INFINITY.abs(), f256::INFINITY);
assert!(f256::NAN.abs().is_nan());

pub fn trunc(&self) -> Self

Returns the integer part of self. This means that non-integer numbers are always truncated towards zero.

Examples

let f = f256::from(177);
let g = f256::from(177.503_f64);
let h = -g;

assert_eq!(f.trunc(), f);
assert_eq!(g.trunc(), f);
assert_eq!(h.trunc(), -f);

pub fn fract(&self) -> Self

Returns the fractional part of self.

Examples

let f = f256::from(177);
let g = f256::from(177.503_f64);
let h = -g;

assert_eq!(f.fract(), f256::ZERO);
assert_eq!(g.fract(), g - f);
assert_eq!(h.fract(), f - g);

pub fn split(&self) -> (Self, Self)

Returns the integer and the fractional part of self.

pub fn ceil(&self) -> Self

Returns the smallest integer greater than or equal to self.

Examples

let f = f256::from(28);
let g = f256::from(27.04_f64);
let h = -g;

assert_eq!(f.ceil(), f);
assert_eq!(g.ceil(), f);
assert_eq!(h.ceil(), f256::ONE - f);

pub fn floor(&self) -> Self

Returns the largest integer less than or equal to self.

Examples

let f = f256::from(57);
let g = f256::from(57.009_f64);
let h = -g;

assert_eq!(f.floor(), f);
assert_eq!(g.floor(), f);
assert_eq!(h.floor(), -f - f256::ONE);

pub fn round(&self) -> Self

Returns the nearest integer to self. Rounds half-way cases away from zero.

Examples

let f = f256::from(27);
let g = f256::from(26.704_f64);
let h = f256::from(26.5_f64);
assert_eq!(f.round(), f);
assert_eq!(g.round(), f);
assert_eq!(h.round(), f);

pub fn round_tie_even(&self) -> Self

Returns the nearest integer to self. Rounds half-way cases to the nearest even.

Examples

let f = f256::from(28);
let g = f256::from(27.704_f64);
let h = f256::from(27.5_f64);
let h = f256::from(28.5_f64);
assert_eq!(f.round_tie_even(), f);
assert_eq!(g.round_tie_even(), f);
assert_eq!(h.round_tie_even(), f);

pub fn mul2(&self) -> Self

Returns 2 * self

pub fn mul_pow2(&self, n: u32) -> Self

Returns self * 2ⁿ

pub fn mul_add(self, f: Self, a: Self) -> Self

Fused multiply-add.

Computes (self * f) + a with only one rounding error, yielding a more accurate result than a non-fused multiply-add.

pub fn sum_of_squares(self, other: Self) -> Self

Fused sum of squares.

Computes (self * self) + (other * other) with only one rounding error, yielding a more accurate result than a non-fused sum of squares.

pub fn square(self) -> Self

Computes self * self .

pub fn square_add(self, a: Self) -> Self

Fused square-add.

Computes (self * self) + a with only one rounding error, yielding a more accurate result than a non-fused square-add.

pub fn div2(&self) -> Self

Returns self / 2 (rounded tie to even)

pub fn div_pow2(&self, n: u32) -> Self

Returns self / 2ⁿ (rounded tie to even)

Trait Implementations

impl Add<&f256> for &f256

type Output = <f256 as Add>::Output

The resulting type after applying the + operator.

fn add(self, rhs: &f256) -> Self::Output

Performs the + operation.

impl Add<&f256> for f256

type Output = <f256 as Add>::Output

The resulting type after applying the + operator.

fn add(self, rhs: &f256) -> Self::Output

Performs the + operation.

impl<'a> Add<f256> for &'a f256

type Output = <f256 as Add>::Output

The resulting type after applying the + operator.

fn add(self, rhs: f256) -> Self::Output

Performs the + operation.

impl Add for f256

type Output = f256

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl<T> AddAssign<T> for f256

where f256: Add<T, Output = Self>,

fn add_assign(&mut self, rhs: T)

Performs the += operation.

impl Clone for f256

fn clone(&self) -> f256

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for f256

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

Formats the value using the given formatter.

impl Default for f256

fn default() -> f256

Returns the “default value” for a type.

impl Display for f256

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

Formats the value using the given formatter.

Panics:

• The given precision exceeds 75.

impl Div<&f256> for &f256

type Output = <f256 as Div>::Output

The resulting type after applying the / operator.

fn div(self, rhs: &f256) -> Self::Output

Performs the / operation.

impl Div<&f256> for f256

type Output = <f256 as Div>::Output

The resulting type after applying the / operator.

fn div(self, rhs: &f256) -> Self::Output

Performs the / operation.

impl<'a> Div<f256> for &'a f256

type Output = <f256 as Div>::Output

The resulting type after applying the / operator.

fn div(self, rhs: f256) -> Self::Output

Performs the / operation.

impl Div for f256

type Output = f256

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self::Output

Performs the / operation.

impl<T> DivAssign<T> for f256

where f256: Div<T, Output = Self>,

fn div_assign(&mut self, rhs: T)

Performs the /= operation.

impl<F: Float> From<F> for f256

fn from(f: F) -> Self

Converts to this type from the input type.

impl From<i128> for f256

fn from(i: i128) -> Self

Converts to this type from the input type.

impl From<i16> for f256

fn from(i: i16) -> Self

Converts to this type from the input type.

impl From<i32> for f256

fn from(i: i32) -> Self

Converts to this type from the input type.

impl From<i64> for f256

fn from(i: i64) -> Self

Converts to this type from the input type.

impl From<i8> for f256

fn from(i: i8) -> Self

Converts to this type from the input type.

impl From<u128> for f256

fn from(i: u128) -> Self

Converts to this type from the input type.

impl From<u16> for f256

fn from(i: u16) -> Self

Converts to this type from the input type.

impl From<u32> for f256

fn from(i: u32) -> Self

Converts to this type from the input type.

impl From<u64> for f256

fn from(i: u64) -> Self

Converts to this type from the input type.

impl From<u8> for f256

fn from(i: u8) -> Self

Converts to this type from the input type.

impl FromStr for f256

type Err = ParseFloatError

The associated error which can be returned from parsing.

fn from_str(lit: &str) -> Result<Self, Self::Err>

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

impl LowerExp for f256

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

Formats the value using the given formatter in scientific notation with a lower-case e.

Panics:

• The given precision exceeds 75.

impl Mul<&f256> for &f256

type Output = <f256 as Mul>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &f256) -> Self::Output

Performs the * operation.

impl Mul<&f256> for f256

type Output = <f256 as Mul>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: &f256) -> Self::Output

Performs the * operation.

impl<'a> Mul<f256> for &'a f256

type Output = <f256 as Mul>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: f256) -> Self::Output

Performs the * operation.

impl Mul for f256

type Output = f256

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl<T> MulAssign<T> for f256

where f256: Mul<T, Output = Self>,

fn mul_assign(&mut self, rhs: T)

Performs the *= operation.

impl Neg for &f256

type Output = <f256 as Neg>::Output

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl Neg for f256

type Output = f256

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl PartialEq for f256

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd for f256

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl Rem<&f256> for &f256

type Output = <f256 as Rem>::Output

The resulting type after applying the % operator.

fn rem(self, rhs: &f256) -> Self::Output

Performs the % operation.

impl Rem<&f256> for f256

type Output = <f256 as Rem>::Output

The resulting type after applying the % operator.

fn rem(self, rhs: &f256) -> Self::Output

Performs the % operation.

impl<'a> Rem<f256> for &'a f256

type Output = <f256 as Rem>::Output

The resulting type after applying the % operator.

fn rem(self, rhs: f256) -> Self::Output

Performs the % operation.

impl Rem for f256

type Output = f256

The resulting type after applying the % operator.

fn rem(self, rhs: Self) -> Self::Output

Performs the % operation.

impl<T> RemAssign<T> for f256

where f256: Rem<T, Output = Self>,

fn rem_assign(&mut self, rhs: T)

Performs the %= operation.

impl Sub<&f256> for &f256

type Output = <f256 as Sub>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: &f256) -> Self::Output

Performs the - operation.

impl Sub<&f256> for f256

type Output = <f256 as Sub>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: &f256) -> Self::Output

Performs the - operation.

impl<'a> Sub<f256> for &'a f256

type Output = <f256 as Sub>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: f256) -> Self::Output

Performs the - operation.

impl Sub for f256

type Output = f256

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl<T> SubAssign<T> for f256

where f256: Sub<T, Output = Self>,

fn sub_assign(&mut self, rhs: T)

Performs the -= operation.

impl TryFrom<&f256> for i32

type Error = ()

The type returned in the event of a conversion error.

fn try_from(value: &f256) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&str> for f256

type Error = ParseFloatError

The type returned in the event of a conversion error.

fn try_from(lit: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl UpperExp for f256

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

Formats the value using the given formatter in scientific notation with a lower-case E.

Panics:

• The given precision exceeds 75.

impl Copy for f256