mathru/algebra/abstr/
relative_eq.rs

1use crate::algebra::abstr::abs_diff_eq::AbsDiffEq;
2
3/// The requisite parameters for testing for approximate equality using a
4/// relative based comparison.
5///
6/// This is not normally used directly, rather via the
7/// `assert_relative_{eq|ne}!` and `relative_{eq|ne}!` macros.
8///
9/// # Example
10///
11/// ```rust
12/// use mathru::algebra::abstr::Relative;
13///
14/// Relative::default().eq(&1.0, &1.0);
15/// Relative::default().epsilon(f64::EPSILON).eq(&1.0, &1.0);
16/// Relative::default().max_relative(1.0).eq(&1.0, &1.0);
17/// Relative::default().epsilon(f64::EPSILON).max_relative(1.0).eq(&1.0, &1.0);
18/// Relative::default().max_relative(1.0).epsilon(f64::EPSILON).eq(&1.0, &1.0);
19/// ```
20pub struct Relative<A, B = A>
21where
22    A: RelativeEq<B> + ?Sized,
23    B: ?Sized,
24{
25    /// The tolerance to use when testing values that are close together.
26    pub epsilon: A::Epsilon,
27    /// The relative tolerance for testing values that are far-apart.
28    pub max_relative: A::Epsilon,
29}
30
31impl<A, B> Default for Relative<A, B>
32where
33    A: RelativeEq<B> + ?Sized,
34    B: ?Sized,
35{
36    fn default() -> Relative<A, B> {
37        Relative {
38            epsilon: A::default_epsilon(),
39            max_relative: A::default_max_relative(),
40        }
41    }
42}
43
44impl<A, B> Relative<A, B>
45where
46    A: RelativeEq<B> + ?Sized,
47    B: ?Sized,
48{
49    /// Replace the epsilon value with the one specified.
50    pub fn epsilon(self, epsilon: A::Epsilon) -> Relative<A, B> {
51        Relative { epsilon, ..self }
52    }
53
54    /// Replace the maximum relative value with the one specified.
55    pub fn max_relative(self, max_relative: A::Epsilon) -> Relative<A, B> {
56        Relative {
57            max_relative,
58            ..self
59        }
60    }
61
62    /// Perform the equality comparison
63    pub fn eq(self, lhs: &A, rhs: &B) -> bool {
64        A::relative_eq(lhs, rhs, self.epsilon, self.max_relative)
65    }
66
67    /// Perform the inequality comparison
68    pub fn ne(self, lhs: &A, rhs: &B) -> bool {
69        A::relative_ne(lhs, rhs, self.epsilon, self.max_relative)
70    }
71}
72
73/// Equality comparisons between two numbers using both the absolute difference and
74/// relative based comparisons.
75pub trait RelativeEq<Rhs = Self>: AbsDiffEq<Rhs>
76where
77    Rhs: ?Sized,
78{
79    /// The default relative tolerance for testing values that are far-apart.
80    ///
81    /// This is used when no `max_relative` value is supplied to the relative_eq macro.
82    fn default_max_relative() -> Self::Epsilon;
83
84    /// A test for equality that uses a relative comparison if the values are far apart.
85    fn relative_eq(&self, other: &Rhs, epsilon: Self::Epsilon, max_relative: Self::Epsilon)
86        -> bool;
87
88    /// The inverse of [`RelativeEq::relative_eq`].
89    fn relative_ne(
90        &self,
91        other: &Rhs,
92        epsilon: Self::Epsilon,
93        max_relative: Self::Epsilon,
94    ) -> bool {
95        !Self::relative_eq(self, other, epsilon, max_relative)
96    }
97}
98
99///////////////////////////////////////////////////////////////////////////////////////////////////
100// Base implementations
101///////////////////////////////////////////////////////////////////////////////////////////////////
102
103// Implementation based on: [Comparing Floating Point Numbers, 2012 Edition]
104// (https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/)
105macro_rules! impl_relative_eq_float {
106    ($T:ident, $U:ident) => {
107        impl RelativeEq for $T {
108            fn default_max_relative() -> $T {
109                $T::EPSILON
110            }
111
112            fn relative_eq(&self, other: &$T, epsilon: $T, max_relative: $T) -> bool {
113                // Handle same infinities
114                if self == other {
115                    return true;
116                }
117
118                // Handle remaining infinities
119                if $T::is_infinite(*self) || $T::is_infinite(*other) {
120                    return false;
121                }
122
123                let abs_diff = $T::abs(self - other);
124
125                // For when the numbers are really close together
126                if abs_diff <= epsilon {
127                    return true;
128                }
129
130                let abs_self = $T::abs(*self);
131                let abs_other = $T::abs(*other);
132
133                let largest = if abs_other > abs_self {
134                    abs_other
135                } else {
136                    abs_self
137                };
138
139                // Use a relative difference comparison
140                abs_diff <= largest * max_relative
141            }
142        }
143    };
144}
145
146impl_relative_eq_float!(f32, i32);
147impl_relative_eq_float!(f64, i64);
148
149/// Approximate equality using both the absolute difference and relative based comparisons.
150#[macro_export]
151macro_rules! relative_eq {
152    ($lhs:expr, $rhs:expr $(, $opt:ident = $val:expr)*) => {
153        $crate::algebra::abstr::Relative::default()$(.$opt($val))*.eq(&$lhs, &$rhs)
154    };
155    ($lhs:expr, $rhs:expr $(, $opt:ident = $val:expr)*,) => {
156        $crate::algebra::abstr::Relative::default()$(.$opt($val))*.eq(&$lhs, &$rhs)
157    };
158}
159
160/// Approximate inequality using both the absolute difference and relative based comparisons.
161#[macro_export]
162macro_rules! relative_ne {
163    ($lhs:expr, $rhs:expr $(, $opt:ident = $val:expr)*) => {
164        $crate::algebra::abstr::Relative::default()$(.$opt($val))*.ne(&$lhs, &$rhs)
165    };
166    ($lhs:expr, $rhs:expr $(, $opt:ident = $val:expr)*,) => {
167        $crate::algebra::abstr::Relative::default()$(.$opt($val))*.ne(&$lhs, &$rhs)
168    };
169}
170
171/// An assertion that delegates to relative_eq!, and panics with a helpful error on failure.
172#[macro_export(local_inner_macros)]
173macro_rules! assert_relative_eq {
174    ($given:expr, $expected:expr $(, $opt:ident = $val:expr)*) => {
175        __assert_approx!(relative_eq, $given, $expected $(, $opt = $val)*)
176    };
177    ($given:expr, $expected:expr $(, $opt:ident = $val:expr)*,) => {
178        __assert_approx!(relative_eq, $given, $expected $(, $opt = $val)*)
179    };
180}
181
182/// An assertion that delegates to [`relative_ne!`], and panics with a helpful error on failure.
183#[macro_export(local_inner_macros)]
184macro_rules! assert_relative_ne {
185    ($given:expr, $expected:expr $(, $opt:ident = $val:expr)*) => {
186        __assert_approx!(relative_ne, $given, $expected $(, $opt = $val)*)
187    };
188    ($given:expr, $expected:expr $(, $opt:ident = $val:expr)*,) => {
189        __assert_approx!(relative_ne, $given, $expected $(, $opt = $val)*)
190    };
191}
mathru/algebra/abstr/relative_eq.rs

mathru/algebra/abstr/
relative_eq.rs
