Struct result_float::ResultFloat

pub struct ResultFloat<F>(_);

A floating point number that cannot store NaN.

Usually there is no need to access this struct directly, and instead one of aliases like Rf32 or Rf64 could be used instead.

Methods

impl<F> ResultFloat<F> where     F: FloatCore,

pub fn new(v: F) -> Result<F>

Constructs a ResultFloat with the given value.

Returns Err if the value is NaN.

use result_float::{rf, ResultFloat};

assert_eq!(ResultFloat::new(1.0)?, rf(1.0)?);

pub fn raw(self) -> F

Returns the underlying float value.

use result_float::rf;

assert_eq!(rf(3.14)?.raw(), 3.14);

pub fn is_infinite(self) -> bool

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

use result_float::rf;
use std::f64;

let f = rf(7.0)?;
let inf = rf(f64::INFINITY)?;
let neg_inf = rf(f64::NEG_INFINITY)?;

assert!(!f.is_infinite());
assert!(inf.is_infinite());
assert!(neg_inf.is_infinite());

pub fn is_finite(self) -> bool

Returns true if this number is not infinite.

use result_float::rf;
use std::f64;

let f = rf(7.0f64)?;
let inf = rf(f64::INFINITY)?;
let neg_inf = rf(f64::NEG_INFINITY)?;

assert!(f.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, or subnormal.

use result_float::rf;
use std::f64;

let min = rf(f64::MIN_POSITIVE)?; // 2.2250738585072014e-308f64
let max = rf(f64::MAX)?;
let lower_than_min = rf(1.0e-308_f64)?;
let zero = rf(0.0f64)?;

assert!(min.is_normal());
assert!(max.is_normal());

assert!(!zero.is_normal());
assert!(!rf(f64::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.

use result_float::rf;
use std::num::FpCategory;
use std::f64;

let num = rf(12.4)?;
let inf = rf(f64::INFINITY)?;

assert_eq!(num.classify(), FpCategory::Normal);
assert_eq!(inf.classify(), FpCategory::Infinite);

pub fn floor(self) -> Self

Returns the largest integer less than or equal to a number.

use result_float::rf;

let f = rf(3.99)?;
let g = rf(3.0)?;

assert_eq!(f.floor(), rf(3.0)?);
assert_eq!(g.floor(), rf(3.0)?);

pub fn ceil(self) -> Self

Returns the smallest integer greater than or equal to a number.

use result_float::rf;

let f = rf(3.01)?;
let g = rf(4.0)?;

assert_eq!(f.ceil(), rf(4.0)?);
assert_eq!(g.ceil(), rf(4.0)?);

pub fn round(self) -> Self

Returns the nearest integer to a number. Round half-way cases away from 0.0.

use result_float::rf;

let f = rf(3.3)?;
let g = rf(-3.3)?;

assert_eq!(f.round(), rf(3.0)?);
assert_eq!(g.round(), rf(-3.0)?);

pub fn trunc(self) -> Self

Returns the integer part of a number.

use result_float::rf;

let f = rf(3.3)?;
let g = rf(-3.7)?;

assert_eq!(f.trunc(), rf(3.0)?);
assert_eq!(g.trunc(), rf(-3.0)?);

pub fn fract(self) -> Result<F>

Returns the fractional part of a number.

use result_float::rf;

let x = rf(3.5)?;
let y = rf(-3.5)?;
let abs_difference_x = (x.fract()? - rf(0.5)?)?.abs();
let abs_difference_y = (y.fract()? - rf(-0.5)?)?.abs();

assert!(abs_difference_x < rf(1e-10)?);
assert!(abs_difference_y < rf(1e-10)?);

pub fn abs(self) -> Self

Computes the absolute value of self.

use result_float::rf;
use std::f64;

let x = rf(3.5)?;
let y = rf(-3.5)?;

let abs_difference_x = (x.abs() - x)?.abs();
let abs_difference_y = (y.abs() - (-y))?.abs();

assert!(abs_difference_x < rf(1e-10)?);
assert!(abs_difference_y < rf(1e-10)?);

pub fn signum(self) -> Self

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

use result_float::rf;
use std::f64;

let f = rf(3.5)?;

assert_eq!(f.signum(), rf(1.0)?);
assert_eq!(rf(f64::NEG_INFINITY)?.signum(), rf(-1.0)?);

pub fn is_sign_positive(self) -> bool

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

use result_float::rf;
let f = rf(7.0)?;
let g = rf(-7.0)?;

assert!(f.is_sign_positive());
assert!(!g.is_sign_positive());

pub fn is_sign_negative(self) -> bool

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

use result_float::rf;

let f = rf(7.0)?;
let g = rf(-7.0)?;

assert!(!f.is_sign_negative());
assert!(g.is_sign_negative());

pub fn recip(self) -> Self

Takes the reciprocal (inverse) of a number, 1/x.

use result_float::rf;

let x = rf(2.0)?;
let abs_difference = (x.recip() - (rf(1.0)?/x)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

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

Raises a number to an integer power.

Using this function is generally faster than using powf. Additionally, this function cannot return an error value.

use result_float::rf;

let x = rf(2.0)?;
let abs_difference = (x.powi(2) - (x*x)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn to_degrees(self) -> Result<F>

Converts degrees to radians.

use result_float::rf;
use std::f64::consts::PI;

let angle = rf(180.0)?;

let abs_difference = (angle.to_radians()? - rf(PI)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn to_radians(self) -> Result<F>

Converts degrees to radians.

use result_float::rf;
use std::f64::consts::PI;

let angle = rf(180.0)?;

let abs_difference = (angle.to_radians()? - rf(PI)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

impl<F> ResultFloat<F> where     F: FloatCore + Float,

pub fn mul_add(self, a: Self, b: Self) -> Result<F>

Fused multiply-add. Computes (self * a) + b with only one rounding error. This produces a more accurate result with better performance than a separate multiplication operation followed by an add.

use result_float::rf;

let m = rf(10.0)?;
let x = rf(4.0)?;
let b = rf(60.0)?;

// 100.0
let abs_difference = (m.mul_add(x, b)? - ((m*x)? + b)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn powf(self, n: Self) -> Result<F>

Raises a number to a floating point power.

use result_float::rf;

let x = rf(2.0)?;
let abs_difference = (x.powf(rf(2.0)?)? - (x*x)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn sqrt(self) -> Result<F>

Takes the square root of a number.

Returns NaN if self is a negative number.

Examples

use result_float::rf;

let positive = rf(4.0)?;
let negative = rf(-4.0)?;

let abs_difference = (positive.sqrt()? - rf(2.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);
assert!(negative.sqrt().is_err());

pub fn exp(self) -> Self

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

Examples

use result_float::rf;

let one = rf(1.0)?;
// e^1
let e = one.exp();

// ln(e) - 1 == 0
let abs_difference = (e.ln()? - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn exp2(self) -> Self

Returns 2^(self).

Examples

use result_float::rf;

let f = rf(2.0)?;

// 2^2 - 4 == 0
let abs_difference = (f.exp2() - rf(4.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn ln(self) -> Result<F>

Returns the natural logarithm of the number.

Examples

use result_float::rf;

let one = rf(1.0)?;
// e^1
let e = one.exp();

// ln(e) - 1 == 0
let abs_difference = (e.ln()? - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn log(self, base: Self) -> Result<F>

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

The result may 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.

Examples

use result_float::rf;

let five = rf(5.0)?;

// log5(5) - 1 == 0
let abs_difference = (five.log(rf(5.0)?)? - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn log2(self) -> Result<F>

Returns the base 2 logarithm of the number.

Examples

use result_float::rf;

let two = rf(2.0)?;

// log2(2) - 1 == 0
let abs_difference = (two.log2()? - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn log10(self) -> Result<F>

Returns the base 10 logarithm of the number.

Examples

use result_float::rf;

let ten = rf(10.0)?;

// log10(10) - 1 == 0
let abs_difference = (ten.log10()? - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn cbrt(self) -> Self

Takes the cubic root of a number.

Examples

use result_float::rf;

let x = rf(8.0)?;

// x^(1/3) - 2 == 0
let abs_difference = (x.cbrt() - rf(2.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

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

Calculates the length of the hypotenuse of a right-angle triangle given legs of length x and y.

Examples

use result_float::rf;

let x = rf(2.0)?;
let y = rf(3.0)?;

// sqrt(x^2 + y^2)
let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2))?.sqrt()?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn sin(self) -> Result<F>

Computes the sine of a number (in radians).

Examples

use result_float::rf;
use std::f64;

let x = (rf(f64::consts::PI)? / rf(2.0)?)?;

let abs_difference = (x.sin()? - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn cos(self) -> Result<F>

Computes the cosine of a number (in radians).

Examples

use result_float::rf;
use std::f64;

let x = (rf(2.0)? * rf(f64::consts::PI)?)?;

let abs_difference = (x.cos()? - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn tan(self) -> Result<F>

Computes the tangent of a number (in radians).

Examples

use result_float::rf;
use std::f64;

let x = (rf(f64::consts::PI)? / rf(4.0)?)?;
let abs_difference = (x.tan()? - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-14)?);

pub fn asin(self) -> Result<F>

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].

Examples

use result_float::rf;
use std::f64;

let f = (rf(f64::consts::PI)? / rf(2.0)?)?;

// asin(sin(pi/2))
let abs_difference = (f.sin()?.asin()? - (rf(f64::consts::PI)? / rf(2.0)?)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn acos(self) -> Result<F>

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].

Examples

use result_float::rf;
use std::f64;

let f = (rf(f64::consts::PI)? / rf(4.0)?)?;

// acos(cos(pi/4))
let abs_difference = (f.cos()?.acos()? - (rf(f64::consts::PI)? / rf(4.0)?)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn atan(self) -> Self

Computes the arctangent of a number. Return value is in radians in the range [-pi/2, pi/2];

Examples

use result_float::rf;

let f = rf(1.0)?;

// atan(tan(1))
let abs_difference = (f.tan()?.atan() - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

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) -> [-pi/2, pi/2]
• y >= 0: arctan(y/x) + pi -> (pi/2, pi]
• y < 0: arctan(y/x) - pi -> (-pi, -pi/2)

Examples

use result_float::rf;
use std::f64;

let pi = rf(f64::consts::PI)?;
// Positive angles measured counter-clockwise
// from positive x axis
// -pi/4 radians (45 deg clockwise)
let x1 = rf(3.0)?;
let y1 = -rf(3.0)?;

// 3pi/4 radians (135 deg counter-clockwise)
let x2 = -rf(3.0)?;
let y2 = rf(3.0)?;

let abs_difference_1 = (y1.atan2(x1) - (-pi/rf(4.0)?)?)?.abs();
let abs_difference_2 = (y2.atan2(x2) - ((rf(3.0)?*pi)?/rf(4.0)?)?)?.abs();

assert!(abs_difference_1 < rf(1e-10)?);
assert!(abs_difference_2 < rf(1e-10)?);

pub fn sin_cos(self) -> Result<(Self, Self), NaN>

Simultaneously computes the sine and cosine of the number, x. Returns (sin(x), cos(x)).

Examples

use result_float::rf;
use std::f64;

let x = (rf(f64::consts::PI)?/rf(4.0)?)?;
let f = x.sin_cos()?;

let abs_difference_0 = (f.0 - x.sin()?)?.abs();
let abs_difference_1 = (f.1 - x.cos()?)?.abs();

assert!(abs_difference_0 < rf(1e-10)?);
assert!(abs_difference_1 < rf(1e-10)?);

pub fn exp_m1(self) -> Self

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

Examples

use result_float::rf;

let x = rf(7.0)?;

// e^(ln(7)) - 1
let abs_difference = (x.ln()?.exp_m1() - rf(6.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn ln_1p(self) -> Result<F>

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

Examples

use result_float::rf;
use std::f64;

let x = (rf(f64::consts::E)? - rf(1.0)?)?;

// ln(1 + (e - 1)) == ln(e) == 1
let abs_difference = (x.ln_1p()? - rf(1.0)?)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn sinh(self) -> Self

Hyperbolic sine function.

Examples

use result_float::rf;
use std::f64;

let e = rf(f64::consts::E)?;
let x = rf(1.0)?;

let f = x.sinh();
// Solving sinh() at 1 gives `(e^2-1)/(2e)`
let g = ((e.powi(2) - rf(1.0)?)?/(rf(2.0)?*e)?)?;
let abs_difference = (f - g)?.abs();

assert!(abs_difference < rf(1e-10)?);

pub fn cosh(self) -> Self

Hyperbolic cosine function.

Examples

use result_float::rf;
use std::f64;

let e = rf(f64::consts::E)?;
let x = rf(1.0)?;
let f = x.cosh();
// Solving cosh() at 1 gives this result
let g = ((e.powi(2) + rf(1.0)?)?/(rf(2.0)?*e)?)?;
let abs_difference = (f - g)?.abs();

// Same result
assert!(abs_difference < rf(1.0e-10)?);

pub fn tanh(self) -> Self

Hyperbolic tangent function.

Examples

use result_float::rf;
use std::f64;

let e = rf(f64::consts::E)?;
let x = rf(1.0)?;

let f = x.tanh();
// Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))`
let g = ((rf(1.0)? - e.powi(-2))?/(rf(1.0)? + e.powi(-2))?)?;
let abs_difference = (f - g)?.abs();

assert!(abs_difference < rf(1.0e-10)?);

pub fn asinh(self) -> Self

Inverse hyperbolic sine function.

Examples

use result_float::rf;

let x = rf(1.0)?;
let f = x.sinh().asinh();

let abs_difference = (f - x)?.abs();

assert!(abs_difference < rf(1.0e-10)?);

pub fn acosh(self) -> Result<F>

Inverse hyperbolic cosine function.

use result_float::rf;

let x = rf(1.0)?;
let f = x.cosh().acosh()?;

let abs_difference = (f - x)?.abs();

assert!(abs_difference < rf(1.0e-10)?);

pub fn atanh(self) -> Result<F>

Inverse hyperbolic tangent function.

use result_float::rf;
use std::f64;

let e = rf(f64::consts::E)?;
let f = e.tanh().atanh()?;

let abs_difference = (f - e)?.abs();

assert!(abs_difference < rf(1.0e-10)?);

impl ResultFloat<f32>

pub fn to_bits(self) -> u32

Raw transmutation to u32.

This is currently identical to transmute::<f32, u32>(self.raw()) on all platforms.

Note that this function is distinct from as casting, which attempts to preserve the numeric value, and not the bitwise value.

Examples

use result_float::rf;
assert!(rf(1f32)?.to_bits() != 1f32 as u32); // to_bits() is not casting!
assert_eq!(rf(12.5f32)?.to_bits(), 0x41480000);

pub fn from_bits(v: u32) -> Result<f32>

Raw transmutation from u32.

This is currently identical to rf(transmute::<u32, f32>(v)) on all platforms. It turns out this is incredibly portable, for two reasons:

• Floats and Ints have the same endianness on all supported platforms.
• IEEE-754 very precisely specifies the bit layout of floats.

Note that this function is distinct from as casting, which attempts to preserve the numeric value, and not the bitwise value.

Examples

use result_float::{rf, Rf32};
let v = Rf32::from_bits(0x41480000)?;
let difference = (v - rf(12.5)?)?.abs();
assert!(difference <= rf(1e-5)?);

impl ResultFloat<f64>

pub fn to_bits(self) -> u64

Raw transmutation to u64.

This is currently identical to transmute::<f64, u64>(self.raw()) on all platforms.

Note that this function is distinct from as casting, which attempts to preserve the numeric value, and not the bitwise value.

Examples

use result_float::rf;
assert!(rf(1f64)?.to_bits() != 1f64 as u64); // to_bits() is not casting!
assert_eq!(rf(12.5f64)?.to_bits(), 0x4029000000000000);

pub fn from_bits(v: u64) -> Result<f64>

Raw transmutation from u64.

This is currently identical to rf(transmute::<u64, f64>(v)) on all platforms. It turns out this is incredibly portable, for two reasons:

• Floats and Ints have the same endianness on all supported platforms.
• IEEE-754 very precisely specifies the bit layout of floats.

Note that this function is distinct from as casting, which attempts to preserve the numeric value, and not the bitwise value.

Examples

use result_float::{rf, Rf64};
let v = Rf64::from_bits(0x4029000000000000)?;
let difference = (v - rf(12.5)?)?.abs();
assert!(difference <= rf(1e-5)?);

Trait Implementations

impl<F: Copy> Copy for ResultFloat<F>

impl<F: Clone> Clone for ResultFloat<F>

fn clone(&self) -> ResultFloat<F>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F: Debug> Debug for ResultFloat<F>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<F: PartialEq> PartialEq for ResultFloat<F>

fn eq(&self, other: &ResultFloat<F>) -> bool

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

fn ne(&self, other: &ResultFloat<F>) -> bool

This method tests for !=.

impl<F: PartialOrd> PartialOrd for ResultFloat<F>

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

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

fn lt(&self, other: &ResultFloat<F>) -> bool

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

fn le(&self, other: &ResultFloat<F>) -> bool

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

fn gt(&self, other: &ResultFloat<F>) -> bool

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

fn ge(&self, other: &ResultFloat<F>) -> bool

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

impl<F> Eq for ResultFloat<F> where     F: PartialEq,

impl<F> Ord for ResultFloat<F> where     F: PartialOrd,

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

impl<F> Add for ResultFloat<F> where     F: FloatCore,

type Output = Result<F>

The resulting type after applying the + operator.

fn add(self, other: Self) -> Result<F>

Performs the + operation.

impl<F> Sub for ResultFloat<F> where     F: FloatCore,

type Output = Result<F>

The resulting type after applying the - operator.

fn sub(self, other: Self) -> Result<F>

Performs the - operation.

impl<F> Mul for ResultFloat<F> where     F: FloatCore,

type Output = Result<F>

The resulting type after applying the * operator.

fn mul(self, other: Self) -> Result<F>

Performs the * operation.

impl<F> Div for ResultFloat<F> where     F: FloatCore,

type Output = Result<F>

The resulting type after applying the / operator.

fn div(self, other: Self) -> Result<F>

Performs the / operation.

impl<F> Rem for ResultFloat<F> where     F: FloatCore,

type Output = Result<F>

The resulting type after applying the % operator.

fn rem(self, other: Self) -> Result<F>

Performs the % operation.

impl<F> Neg for ResultFloat<F> where     F: FloatCore,

type Output = ResultFloat<F>

The resulting type after applying the - operator.

fn neg(self) -> ResultFloat<F>

Performs the unary - operation.

impl<F> Display for ResultFloat<F> where     F: Display,

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<F> LowerExp for ResultFloat<F> where     F: LowerExp,

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<F> UpperExp for ResultFloat<F> where     F: UpperExp,

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Hash for ResultFloat<f32>

fn hash<H>(&self, state: &mut H) where     H: Hasher,

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where     H: Hasher,

Feeds a slice of this type into the given [Hasher].

impl Hash for ResultFloat<f64>

fn hash<H>(&self, state: &mut H) where     H: Hasher,

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where     H: Hasher,

Feeds a slice of this type into the given [Hasher].

impl<F> Default for ResultFloat<F> where     F: Default + FloatCore,

fn default() -> ResultFloat<F>

Returns the "default value" for a type.

impl<F> Serialize for ResultFloat<F> where     F: Serialize,

Requires crate feature serde

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where     S: Serializer,

Serialize this value into the given Serde serializer.

impl<'de, F> Deserialize<'de> for ResultFloat<F> where     F: Deserialize<'de> + FloatCore,

Requires crate feature serde

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where     D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.