[−][src]Trait float_eq::FloatDiff

pub trait FloatDiff<Rhs: ?Sized = Self> {
    type AbsDiff;
    type UlpsDiff;
    fn abs_diff(&self, other: &Rhs) -> Self::AbsDiff;
    fn ulps_diff(&self, other: &Rhs) -> Option<Self::UlpsDiff>;
}

Compute the difference between IEEE floating point values.

This trait is used by the family of assert_float_eq! macros to provide debug context information when they fail, but may also be called directly. Types are displayed to the user with fmt::Debug.

Note: the definition of this trait is very much tailored to float_eq's debug context requirements, and may not be ideal for general use.

How can I implement `FloatDiff`?

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 FloatDiff 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, Clone, Copy, PartialEq)]
struct MyComplex32 {
    re: f32,
    im: f32,
}

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

impl FloatDiff for MyComplex32 {
    type AbsDiff = Self;
    type UlpsDiff = MyComplex32Ulps;

    fn abs_diff(&self, other: &Self) -> Self::AbsDiff {
        MyComplex32 {
            re: self.re.abs_diff(&other.re),
            im: self.im.abs_diff(&other.im),
        }
    }

    fn ulps_diff(&self, other: &Self) -> Option<Self::UlpsDiff> {
        Some(MyComplex32Ulps {
            re: self.re.ulps_diff(&other.re)?,
            im: self.im.ulps_diff(&other.im)?,
        })
    }
}

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

assert_eq!(
    a.abs_diff(&b),
    MyComplex32 {
        re: 0.000_000_119_209_29,
        im: 0.000_003_576_278_7,
    }
);

assert_eq!(a.ulps_diff(&b), Some(MyComplex32Ulps { re: 1, im: 15 }));

How can I compare two different types?

The type you can diff with is controlled by FloatDiff'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 FloatDiff<f32> for MyComplex32 {
    type AbsDiff = MyComplex32;
    type UlpsDiff = MyComplex32Ulps;

    fn abs_diff(&self, other: &f32) -> Self::AbsDiff {
        MyComplex32 {
            re: self.re.abs_diff(other),
            im: self.im.abs_diff(&0.0),
        }
    }

    fn ulps_diff(&self, other: &f32) -> Option<Self::UlpsDiff> {
        Some(MyComplex32Ulps {
            re: self.re.ulps_diff(other)?,
            im: self.im.ulps_diff(&0.0)?,
        })
    }
}

impl FloatDiff<MyComplex32> for f32 {
    type AbsDiff = <MyComplex32 as FloatDiff<f32>>::AbsDiff;
    type UlpsDiff = <MyComplex32 as FloatDiff<f32>>::UlpsDiff;

    fn abs_diff(&self, other: &MyComplex32) -> Self::AbsDiff {
        other.abs_diff(self)
    }

    fn ulps_diff(&self, other: &MyComplex32) -> Option<Self::UlpsDiff> {
        other.ulps_diff(self)
    }
}

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

assert_eq!(
    a.abs_diff(&b),
    MyComplex32 {
        re: 0.000_000_119_209_29,
        im: 2.000_003_6,
    }
);

assert_eq!(a.ulps_diff(&b), Some(MyComplex32Ulps { re: 1, im: 1_073_741_839 }));

Examples

assert_eq!(1.0f32.abs_diff(&-1.0), 2.0);
assert_eq!(1.0f64.abs_diff(&-1.0), 2.0);

assert_eq!(1.0f32.ulps_diff(&1.000_000_1), Some(1));
assert_eq!(1.0f64.ulps_diff(&1.000_000_000_000_000_2), Some(1));

assert_eq!(1.0f32.ulps_diff(&-1.0), None);
assert_eq!(1.0f64.ulps_diff(&-1.0), None);

let a = [0.0_f32, 2.0, -2.0];
let b = [0.0_f32, -1.0, 2.0];
assert_eq!(a.abs_diff(&b), [0.0, 3.0, 4.0]);
assert_eq!(a.ulps_diff(&b), None);

let c = [1.000_000_1f32, -2.0];
let d = [1.0f32, -2.000_000_5];
assert_eq!(c.ulps_diff(&d), Some([1, 2]));

Associated Types

`type AbsDiff`

Type of the absolute difference between two values.

This is often Self, unless comparing two different types. Composite types should probably use a type that follows the same structure as the inputs, to make error messages more legible.

`type UlpsDiff`

Type of the absolute difference between two values in terms of ULPs.

This should be an unsigned integer of the same size as the underlying floating point type, for example f32 uses u32. Composite types should probably use a type that follows the same structure as the inputs, to make error messages more legible.

Loading content...

Required methods

`fn abs_diff(&self, other: &Rhs) -> Self::AbsDiff`

Always positive absolute difference between two values.

Implementations should be the equivalent of:

(self - other).abs()

`fn ulps_diff(&self, other: &Rhs) -> Option<Self::UlpsDiff>`

Always positive absolute difference between two values in terms of ULPs.

A partial function that returns:

Some(0) if either argument is 0.0 or -0.0
None if either argument is NaN
None if the arguments have differing signs
Some(bitwise-difference) otherwise

Implementations on composite types should return None if any of their parts is an ulps_diff of None.

Implementations should be the equivalent of (using f32 as an example):

if self == other {
    Some(0)
} else if self.is_nan() || other.is_nan() {
    None
} else if self.is_sign_positive() != other.is_sign_positive() {
    None
} else {
    let a = self.to_bits();
    let b = other.to_bits();
    let max = a.max(b);
    let min = a.min(b);
    Some(max - min)
}