[−][src]Trait float_eq::FloatEq

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

    fn ne_abs(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool { ... }
    fn ne_rel(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool { ... }
    fn ne_ulps(&self, other: &Rhs, max_diff: &Self::UlpsEpsilon) -> 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 to provide abs, rel and ulps checks. It may be called directly, but the macros usually provide a friendlier interface.

How can I implement `FloatEq`?

You will need some way to represent difference in ULPs for your type, following the same structure as the type itself. 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(Copy, Clone)]
struct MyComplex32 {
    re: f32,
    im: f32,
}

#[derive(Copy, Clone)]
struct MyComplex32Ulps {
    re: <f32 as FloatDiff>::UlpsDiff,
    im: <f32 as FloatDiff>::UlpsDiff,
}

impl FloatEq for MyComplex32 {
    type Epsilon = MyComplex32;
    type UlpsEpsilon = MyComplex32Ulps;

    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_rel(&self, other: &Self, max_diff: &MyComplex32) -> bool {
        self.re.eq_rel(&other.re, &max_diff.re) && self.im.eq_rel(&other.im, &max_diff.im)
    }

    fn eq_ulps(&self, other: &Self, max_diff: &MyComplex32Ulps) -> 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 }));

How can I compare two different types?

The type to be compared with is controlled by FloatEq's parameter. Following on from our previous example, if we wanted to treat f32 as a complex number with an imaginary component of 0.0:

impl FloatEq<f32> for MyComplex32 {
    type Epsilon = MyComplex32;
    type UlpsEpsilon = MyComplex32Ulps;

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

    fn eq_rel(&self, other: &f32, max_diff: &MyComplex32) -> bool {
        self.re.eq_rel(other, &max_diff.re) && self.im.eq_rel(&0.0, &max_diff.im)
    }

    fn eq_ulps(&self, other: &f32, max_diff: &MyComplex32Ulps) -> bool {
        self.re.eq_ulps(other, &max_diff.re) && self.im.eq_ulps(&0.0, &max_diff.im)
    }
}

let a = MyComplex32 { re: 4.000_000_5, im: 0.0 };
let b = 4.0_f32;

assert!(a.eq_abs(&b, &MyComplex32 { re: 0.000_000_8, im: 0.0 }));
assert!(a.ne_abs(&b, &MyComplex32 { re: 0.000_000_4, im: 0.0 }));

assert!(a.eq_rel(&b, &MyComplex32 { re: 0.000_000_12, im: 0.0 }));
assert!(a.ne_rel(&b, &MyComplex32 { re: 0.000_000_11, im: 0.0 }));

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

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`

Type of the maximum allowed difference between two values for them to be considered equal in terms of their native type.

This is the type of the max_diff parameter passed to abs and rel checks in methods and via the float_eq! macros. This should be structurally similar to the most complex type being compared, most implementations will just use Self.

`type UlpsEpsilon`

Type of the maximum allowed difference between two values for them to be considered equal in terms of an ULPs comparison.

This is the type of the max_diff parameter passed to ulps checks in methods and via the float_eq! macros. This should be structurally similar to the most complex type being compared, most implementations will define an Ulps type that mirrors the fields of Self.

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_rel(&self, other: &Rhs, max_diff: &Self::Epsilon) -> bool`

Check whether self is equal to other, using a relative epsilon comparison.

The implementation should be the equivalent of:

// the PartialEq check covers equality of infinities
self == other || {
    let largest = self.abs().max(other.abs());
    let epsilon = largest * max_diff;
    (self - other).abs() <= epsilon
}

`fn eq_ulps(&self, other: &Rhs, max_diff: &Self::UlpsEpsilon) -> bool`

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

The implementation should be the equivalent of:

if self.is_nan() || other.is_nan() {
    false // NaNs are never equal
}
else if self.is_sign_positive() != other.is_sign_positive() {
    self == other // account for zero == negative zero
} else {
    let a = self.to_bits();
    let b = other.to_bits();
    let max = a.max(b);
    let min = a.min(b);
    (max - min).le(max_diff)
}