[−][src]Trait float_eq::FloatEq

pub trait FloatEq<Rhs: ?Sized = Self> {
    type Epsilon: ?Sized + FloatEqUlpsEpsilon;
    fn eq_abs(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool;
    fn eq_rmax(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool;
    fn eq_rmin(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool;
    fn eq_r1st(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool;
    fn eq_r2nd(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool;
    fn eq_ulps(
        &self, 
        other: &Rhs, 
        max_diff: &UlpsEpsilon<Self::Epsilon>
    ) -> bool;

    fn ne_abs(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool { ... }
    fn eq_rel(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool { ... }
    fn ne_rel(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool { ... }
    fn ne_rmax(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool { ... }
    fn ne_rmin(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool { ... }
    fn ne_r1st(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool { ... }
    fn ne_r2nd(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool { ... }
    fn ne_ulps(
        &self, 
        other: &Rhs, 
        max_diff: &UlpsEpsilon<Self::Epsilon>
    ) -> bool { ... }
}

Compare IEEE floating point values for equality using per-field thresholds.

This trait is used in the implementation of the float_eq! and assert_float_eq! families of macros.

Derivable

This trait can be used with #[derive]. The easiest way to do so is to use the #[derive_float_eq] helper macro, see the top level docs for example usage.

If you wish to derive this trait by itself, you must first implement FloatEqUlpsEpsilon, which may also be derived. You will also need a #[float_eq] attribute and provide ulps_epsilon, which should match the name of the UlpsEpsilon type. Two instances are equal if all fields are equal, and not equal if any are not. This trait may not be derived for enums or generic structs at present.

#[derive(Debug, Clone, Copy, PartialEq, FloatEqUlpsEpsilon, FloatEq)]
#[float_eq(ulps_epsilon = "PointUlps")]
struct Point {
    x: f32,
    y: f32,
}

let a = Point { x: 1.0, y: -2.0 };
let b = Point { x: 1.5, y: -3.0 };
assert!(a.eq_abs(&b, &Point { x: 0.5, y: 1.0 }));
assert!(a.ne_abs(&b, &Point { x: 0.4, y: 1.0 }));
assert!(a.ne_abs(&b, &Point { x: 0.5, y: 0.9 }));

let c = Point { x: 1.000_000_1, y: -2.000_000_5 };
assert!(a.eq_ulps(&c, &PointUlps { x: 1, y: 2 }));
assert!(a.ne_ulps(&c, &PointUlps { x: 0, y: 2 }));
assert!(a.ne_ulps(&c, &PointUlps { x: 1, y: 1 }));

How can I implement `FloatEq`?

You will need to implement FloatEqUlpsEpsilon for your type. Implementation is then usually a matter of calling through to an underlying FloatEq method for each field in turn. If not, you will need to take a close look at the descriptions of the algorithms on a method by method basis:

#[derive(Debug, Copy, Clone, PartialEq)]
struct MyComplex32 {
    re: f32,
    im: f32,
}

#[derive(Debug, Copy, Clone, PartialEq)]
struct MyComplex32Ulps {
    re: UlpsEpsilon<f32>,
    im: UlpsEpsilon<f32>,
}

impl FloatEqUlpsEpsilon for MyComplex32 {
    type UlpsEpsilon = MyComplex32Ulps;   
}

impl FloatEq for MyComplex32 {
    type Epsilon = MyComplex32;

    fn eq_abs(&self, other: &Self, max_diff: &MyComplex32) -> bool {
        self.re.eq_abs(&other.re, &max_diff.re) && self.im.eq_abs(&other.im, &max_diff.im)
    }

    fn eq_rmax(&self, other: &Self, max_diff: &MyComplex32) -> bool {
        self.re.eq_rmax(&other.re, &max_diff.re) && self.im.eq_rmax(&other.im, &max_diff.im)
    }

    fn eq_rmin(&self, other: &Self, max_diff: &MyComplex32) -> bool {
        self.re.eq_rmin(&other.re, &max_diff.re) && self.im.eq_rmin(&other.im, &max_diff.im)
    }

    fn eq_r1st(&self, other: &Self, max_diff: &MyComplex32) -> bool {
        self.re.eq_r1st(&other.re, &max_diff.re) && self.im.eq_r1st(&other.im, &max_diff.im)
    }

    fn eq_r2nd(&self, other: &Self, max_diff: &MyComplex32) -> bool {
        self.re.eq_r2nd(&other.re, &max_diff.re) && self.im.eq_r2nd(&other.im, &max_diff.im)
    }

    fn eq_ulps(&self, other: &Self, max_diff: &UlpsEpsilon<MyComplex32>) -> bool {
        self.re.eq_ulps(&other.re, &max_diff.re) && self.im.eq_ulps(&other.im, &max_diff.im)
    }
}

let a = MyComplex32 { re: 1.0, im: 2.000_003_6, };
let b = MyComplex32 { re: 1.000_000_1, im: 2.0, };

assert!(a.eq_abs(&b, &MyComplex32 { re: 0.000_000_15, im: 0.000_003_6 }));
assert!(a.ne_abs(&b, &MyComplex32 { re: 0.000_000_05, im: 0.000_003_6 }));
assert!(a.ne_abs(&b, &MyComplex32 { re: 0.000_000_15, im: 0.000_003_5 }));

assert!(a.eq_rel(&b, &MyComplex32 { re: 0.000_000_15, im: 0.000_001_8 }));
assert!(a.ne_rel(&b, &MyComplex32 { re: 0.000_000_05, im: 0.000_001_8 }));
assert!(a.ne_rel(&b, &MyComplex32 { re: 0.000_000_15, im: 0.000_001_7 }));

assert!(a.eq_ulps(&b, &MyComplex32Ulps { re: 1, im: 15 }));
assert!(a.ne_ulps(&b, &MyComplex32Ulps { re: 0, im: 15 }));
assert!(a.ne_ulps(&b, &MyComplex32Ulps { re: 1, im: 14 }));

Examples

assert!(4.0_f32.eq_abs(&4.000_001_5, &0.000_001_6));
assert!(4.0_f32.ne_abs(&4.000_001_5, &0.000_001_4));

assert!(4.0_f32.eq_rel(&4.000_001_5, &0.000_000_4));
assert!(4.0_f32.ne_rel(&4.000_001_5, &0.000_000_3));

assert!(4.0_f32.eq_ulps(&4.000_001_5, &3));
assert!(4.0_f32.ne_ulps(&4.000_001_5, &2));

Associated Types

`type Epsilon: ?Sized + FloatEqUlpsEpsilon`

Type of the maximum allowed difference between two values for them to be considered equal.

Loading content...

Required methods

`fn eq_abs(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool`

Check whether self is equal to other, using an absolute epsilon comparison.

Implementations should be the equivalent of:

// the PartialEq check covers equality of infinities
self == other || (self - other).abs().le(max_diff)

`fn eq_rmax(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool`

Check whether self is equal to other, using a relative epsilon comparison, scaled to the granularity of the input with the largest magnitude.