devela/num/ord/
compare.rs

Help
1// devela::num::ord::compare
2//
3//! Helper wrapper for comparing.
4//
5// TOC
6// - Compare definition
7// - impl core traits
8// - impl Compare for T: PartialOrd
9// - impl Compare for primitives
10//   - int
11//   - float
12// - tests
13
14use crate::Ordering::{self, Equal, Greater, Less};
15#[allow(unused_imports)]
16use crate::{iif, paste};
17
18#[allow(unused_imports)]
19#[cfg(_float··)]
20use crate::Float;
21#[allow(unused_imports)]
22#[cfg(feature = "nightly_float")]
23use ::core::{f128, f16};
24
25#[doc = crate::TAG_NAMESPACE!()]
26/// Provides comparing methods for `T`.
27///
28/// It provides the non-*const* methods `pclamp`, `pmax`, `pmin`
29/// for comparing [`PartialOrd`]ered values.
30///
31/// It provides the following *const* methods for comparing primitives:
32/// `clamp`, `max`, `min`, `eq`, `ne`, `lt`, `le`, `gt`, `ge`.
33///
34/// In the case of floating-point primitives:
35/// - total ordering is used.
36/// - aditional methods are provided:
37///  `is_positive`, `is_negative`, `is_finite`, `is_infinite`, `is_nan`.
38#[repr(transparent)]
39pub struct Compare<T>(pub T);
40
41#[rustfmt::skip]
42mod core_impls {
43    use {super::{Compare, Ordering}, core::fmt};
44
45    impl<T: Clone> Clone for Compare<T> { fn clone(&self) -> Self { Self(self.0.clone()) } }
46    impl<T: Copy> Copy for Compare<T> {}
47
48    impl<T: PartialEq> PartialEq for Compare<T> {
49        fn eq(&self, other: &Self) -> bool { self.0.eq(&other.0) }
50    }
51    impl<T: Eq> Eq for Compare<T> {}
52    impl<T: PartialOrd> PartialOrd for Compare<T> {
53        fn partial_cmp(&self, other: &Self) -> Option<Ordering> { self.0.partial_cmp(&other.0) }
54    }
55    impl<T: Ord> Ord for Compare<T> {
56        fn cmp(&self, other: &Self) -> Ordering { self.0.cmp(&other.0) }
57    }
58
59    impl<T: fmt::Display> fmt::Display for Compare<T> {
60        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fmt::Display::fmt(&self.0, f) }
61    }
62    impl<T: fmt::Debug> fmt::Debug for Compare<T> {
63        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
64            f.debug_tuple("Compare").field(&self.0).finish()
65        }
66    }
67}
68
69#[rustfmt::skip]
70impl<T: PartialOrd> Compare<T> {
71    /// Compares and returns a [`PartialOrd`]ered `value` clamped between `min` and `max`.
72    ///
73    /// Returns `None` if comparisons are indeterminate.
74    ///
75    /// # Examples
76    /// ```
77    /// # use devela::Compare;
78    /// assert_eq![Some(0.4), Compare(1.0).pclamp(0.2, 0.4)];
79    /// assert_eq![Some(0.2), Compare(0.0).pclamp(0.2, 0.4)];
80    /// //
81    /// assert_eq![None, Compare(1.0).pclamp(f32::NAN, f32::NAN)];
82    /// assert_eq![None, Compare(1.0).pclamp(f32::NAN, 0.4)];
83    /// assert_eq![None, Compare(1.0).pclamp(0.2, f32::NAN)];
84    /// ```
85    #[must_use]
86    pub fn pclamp(self, min: T, max: T) -> Option<T> {
87        match self.0.partial_cmp(&min) {
88            Some(Less) => Some(min),
89            Some(Greater | Equal) => match self.0.partial_cmp(&max) {
90                Some(Greater) => Some(max),
91                Some(Less | Equal) => Some(self.0),
92                None => None,
93            },
94            None => None,
95        }
96    }
97
98    /// Compares and returns the maximum of two [`PartialOrd`]ered values.
99    ///
100    /// Returns `None` if comparisons are indeterminate.
101    ///
102    /// Complements `core::cmp::`[`max`][`core::cmp::max] which requires [`Ord`]
103    /// # Examples
104    /// ```
105    /// # use devela::Compare;
106    /// assert_eq![Some(0.4), Compare(0.2).pmax(0.4)];
107    /// //
108    /// assert_eq![None, Compare(0.2).pmax(f32::NAN)];
109    /// assert_eq![None, Compare(f32::NAN).pmax(0.4)];
110    /// ```
111    #[must_use]
112    pub fn pmax(self, other: T) -> Option<T> {
113        match self.0.partial_cmp(&other) {
114            Some(Less) => Some(other),
115            Some(Greater | Equal) => Some(self.0),
116            None => None,
117        }
118    }
119
120    /// Compares and returns the minimum of two [`PartialOrd`]ered values.
121    ///
122    /// Returns `None` if comparisons are indeterminate.
123    ///
124    /// Complements `core::cmp::`[`min`][`core::cmp::min] which requires [`Ord`]
125    /// # Example
126    /// ```
127    /// # use devela::Compare;
128    /// assert_eq![Some(0.2), Compare(0.2).pmin(0.4)];
129    /// //
130    /// assert_eq![None, Compare(0.2).pmin(f32::NAN)];
131    /// assert_eq![None, Compare(f32::NAN).pmin(0.4)];
132    /// ```
133    #[must_use]
134    pub fn pmin(self, other: T) -> Option<T> {
135        match self.0.partial_cmp(&other) {
136            Some(Greater) => Some(other),
137            Some(Less | Equal) => Some(self.0),
138            None => None,
139        }
140    }
141}
142
143/// Implement [`Comparing`] for primitives.
144macro_rules! impl_comparing {
145    () => {
146        impl_comparing![int:
147            u8:"_cmp_u8",
148            u16:"_cmp_u16",
149            u32:"_cmp_u32",
150            u64:"_cmp_u64",
151            u128:"_cmp_u128",
152            usize, // always compiled
153            i8:"_cmp_i8",
154            i16:"_cmp_i16",
155            i32:"_cmp_i32",
156            i64:"_cmp_i64",
157            i128:"_cmp_i128",
158            isize:"_cmp_isize"
159        ];
160        impl_comparing![float:
161            f32:"_cmp_f32":32:31,
162            f64:"_cmp_f64":64:63
163        ];
164        #[cfg(feature = "nightly_float")]
165        impl_comparing![float:
166            f16:"_cmp_f16":16:15,
167            f128:"_cmp_f128":128:127
168        ];
169    };
170    (
171    // $p: the integer type
172    // $cap: the capability feature associated with the `$f` type. E.g "_cmp_u8".
173    int: $($p:ty $(: $cap:literal)? ),+) => { $( impl_comparing![@int: $p $(:$cap)? ]; )+ };
174    (@int: $p:ty $(: $cap:literal)? ) => {
175        $( #[cfg(feature = $cap)] )?
176        impl Compare<$p> {
177            /// Compares and returns `self` clamped between `min` and `max`.
178            #[must_use]
179            pub const fn clamp(self, min: $p, max: $p) -> $p {
180                if self.0 < min { min } else if self.0 > max { max } else { self.0 }
181            }
182
183            /// Compares and returns the maximum between `self` and `other`.
184            #[must_use]
185            pub const fn max(self, other: $p) -> $p { if self.0 > other { self.0 } else { other } }
186
187            /// Compares and returns the minimum between `self` and `other`.
188            #[must_use]
189            pub const fn min(self, other: $p) -> $p { if self.0 < other { self.0 } else { other } }
190
191            /// Returns `true` if `self == other`.
192            #[must_use]
193            pub const fn eq(self, other: $p) -> bool { self.0 == other }
194            /// Returns `true` if `self != other`.
195            #[must_use]
196            pub const fn ne(self, other: $p) -> bool { self.0 != other }
197            /// Returns `true` if `self < other`.
198            #[must_use]
199            pub const fn lt(self, other: $p) -> bool { self.0 < other }
200            /// Returns `true` if `self <= other`.
201            #[must_use]
202            pub const fn le(self, other: $p) -> bool { self.0 <= other }
203            /// Returns `true` if `self > other`.
204            #[must_use]
205            pub const fn gt(self, other: $p) -> bool { self.0 > other }
206            /// Returns `true` if `self >= other`.
207            #[must_use]
208            pub const fn ge(self, other: $p) -> bool { self.0 >= other }
209        }
210    };
211    (
212    // $f:    the floating-point type
213    // $fcap: the capability feature associated with the `$f` type. E.g "_cmp_f32".
214    // $b:    the bits of the floating-point primitive
215    // $sh:   the shift amount for the given bits ($b - 1)
216    float: $($f:ty:$fcap:literal:$b:literal:$sh:literal),+) => {
217        $( impl_comparing![@float: $f:$fcap:$b:$sh]; )+
218    };
219    (@float: $f:ty:$fcap:literal:$b:literal:$sh:literal) => { paste! {
220        #[cfg(feature = $fcap)]
221        impl Compare<$f> {
222            #[doc = "A (`const`) port of `" $f "::`[`total_cmp`][" $f "#method.total_cmp]."]
223            #[must_use]
224            pub const fn total_cmp(self, other: $f) -> Ordering {
225                let mut left = self.0.to_bits() as [<i $b>];
226                let mut right = other.to_bits() as [<i $b>];
227
228                left ^= (((left >> $sh) as [<u $b>]) >> 1) as [<i $b>];
229                right ^= (((right >> $sh) as [<u $b>]) >> 1) as [<i $b>];
230
231                iif![left < right; Less; iif![left > right; Greater; Equal]]
232            }
233
234            /// Compares and returns a clamped *total ordered* `self` between `min` and `max`.
235            ///
236            /// # Examples
237            /// ```
238            #[cfg_attr(feature = "nightly_float", doc = "# #![feature(f16, f128)]")]
239            /// # use devela::Compare;
240            #[doc = "assert_eq![2.0, Compare(5.0" $f ").clamp(-1.0, 2.0)];"]
241            #[doc = "assert_eq![-1.0, Compare(-5.0" $f ").clamp(-1.0, 2.0)];"]
242            /// ```
243            #[must_use]
244            pub const fn clamp(self, min: $f, max: $f) -> $f { self.0.clamp(min, max) }
245
246            /// Compares and returns the *total ordered* maximum between `self` and `other`.
247            ///
248            /// # Examples
249            /// ```
250            #[cfg_attr(feature = "nightly_float", doc = "# #![feature(f16, f128)]")]
251            /// # use devela::Compare;
252            #[doc = "assert_eq![2.0, Compare(2.0" $f ").max(-1.0)];"]
253            #[doc = "assert_eq![2.0, Compare(1.0" $f ").max(2.0)];"]
254            #[doc = "assert_eq![0.0, Compare(-0.0" $f ").max(0.0)];"]
255            #[doc = "assert_eq![" $f "::INFINITY, Compare(" $f "::INFINITY).max("
256                $f "::NEG_INFINITY)];"]
257            /// ```
258            #[must_use]
259            pub const fn max(self, other: $f) -> $f { self.0.max(other) }
260
261            /// Compares and returns the *total ordered* minimum between `self` and `other`.
262            ///
263            /// # Examples
264            /// ```
265            #[cfg_attr(feature = "nightly_float", doc = "# #![feature(f16, f128)]")]
266            /// # use devela::Compare;
267            #[doc = "assert_eq![-1.0, Compare(2.0" $f ").min(-1.0)];"]
268            #[doc = "assert_eq![1.0, Compare(1.0" $f ").min(2.0)];"]
269            #[doc = "assert_eq![-0.0, Compare(-0.0" $f ").min(0.0)];"]
270            #[doc = "assert_eq![" $f "::NEG_INFINITY, Compare(" $f "::INFINITY).min("
271                $f "::NEG_INFINITY)];"]
272            /// ```
273            #[must_use]
274            pub const fn min(self, other: $f) -> $f { self.0.min(other) }
275
276            /// Returns `true` if `self == other` using total order.
277            #[must_use]
278            pub const fn eq(self, other: $f) -> bool { matches!(self.total_cmp(other), Equal) }
279
280            /// Returns `true` if `self != other` using total order.
281            #[must_use]
282            pub const fn ne(self, other: $f) -> bool { !matches!(self.total_cmp(other), Equal) }
283
284            /// Returns `true` if `self < other` using total order.
285            #[must_use]
286            pub const fn lt(self, other: $f) -> bool { matches!(self.total_cmp(other), Less) }
287
288            /// Returns `true` if `self <= other` using total order.
289            #[must_use]
290            pub const fn le(self, other: $f) -> bool {
291                matches!(self.total_cmp(other), Less | Equal) }
292
293            /// Returns `true` if `self > other` using total order.
294            #[must_use]
295            pub const fn gt(self, other: $f) -> bool { matches!(self.total_cmp(other), Greater) }
296
297            /// Returns `true` if `self >= other` using total order.
298            #[must_use]
299            pub const fn ge(self, other: $f) -> bool {
300                matches!(self.total_cmp(other), Greater | Equal) }
301
302            /// Returns `true` if `self` is sign positive.
303            #[must_use]
304            pub const fn is_positive(self) -> bool { self.0.is_sign_positive() }
305
306            /// Returns `true` if `self` is sign negative.
307            #[must_use]
308            pub const fn is_negative(self) -> bool { self.0.is_sign_negative() }
309
310            /// Returns `true` if `self` is infinite (either negative or positive).
311            #[must_use]
312            pub const fn is_infinite(self) -> bool { self.0.is_infinite() }
313
314            /// Returns `true` if `self` is nether infinite nor NaN.
315            #[must_use]
316            pub const fn is_finite(self) -> bool { self.0.is_finite() }
317
318            /// Returns `true` if `self` is NaN.
319            #[must_use]
320            pub const fn is_nan(self) -> bool { self.0.is_nan() }
321
322            /// Returns `true` if `self` is subnormal.
323            #[must_use]
324            pub const fn is_subnormal(self) -> bool { self.0.is_subnormal() }
325
326            /// Returns `true` if `self` is neither zero, infinite, subnormal, or NaN.
327            #[must_use]
328            pub const fn is_normal(self) -> bool { self.0.is_normal() }
329        }
330    }};
331}
332impl_comparing!();
333
334#[cfg(test)]
335mod test_min_max_clamp {
336    use super::Compare as C;
337
338    #[test]
339    fn min_max_clamp() {
340        assert_eq![Some(2), C(2).pmin(5)];
341        assert_eq![Some(2), C(5).pmin(2)];
342        assert_eq![Some(2.), C(2.).pmin(5.)];
343
344        assert_eq![Some(5), C(2).pmax(5)];
345        assert_eq![Some(5), C(5).pmax(2)];
346        assert_eq![Some(5.), C(2.).pmax(5.)];
347
348        assert_eq![Some(3), C(3).pclamp(2, 5)];
349        assert_eq![Some(3.), C(3.).pclamp(2., 5.)];
350        assert_eq![Some(2), C(1).pclamp(2, 5)];
351        assert_eq![Some(5), C(7).pclamp(2, 5)];
352    }
353
354    #[test]
355    fn float() {
356        let (zero, negzero, one, negone) = (C(0.0_f32), C(-0.0_f32), C(1.0_f32), C(-1.0_f32));
357        let (nan1, nan2) = (C(f32::NAN), C(0.0_f32 / 0.0_f32));
358        let (inf, neginf) = (C(f32::INFINITY), C(f32::NEG_INFINITY));
359        let sub = C(1.401298464e-45_f32);
360        let (min, negmin) = (C(f32::MIN_POSITIVE), C(-f32::MIN_POSITIVE));
361
362        assert![nan1.0.is_nan()];
363        assert![nan2.0.is_nan()];
364        assert![!zero.0.is_nan()];
365        assert![!negzero.0.is_nan()];
366        assert![!one.0.is_nan()];
367        assert![!negone.0.is_nan()];
368        assert![!inf.0.is_nan()];
369        assert![!neginf.0.is_nan()];
370        assert![!min.0.is_nan()];
371        assert![!negmin.0.is_nan()];
372
373        assert![negone.0.is_sign_negative()];
374        assert![negzero.0.is_sign_negative()];
375        assert![neginf.0.is_sign_negative()];
376        assert![!negone.0.is_sign_positive()];
377        assert![!negzero.0.is_sign_positive()];
378        assert![!neginf.0.is_sign_positive()];
379
380        assert![sub.0.is_subnormal() && !sub.0.is_normal()];
381        assert![!zero.0.is_subnormal() && !zero.0.is_normal()];
382        assert![one.0.is_normal() && !one.0.is_subnormal()];
383        assert![min.0.is_normal() && !min.0.is_subnormal()];
384        assert![negmin.0.is_normal() && !negmin.0.is_subnormal()];
385    }
386}
devela/num/ord/compare.rs

devela/num/ord/
compare.rs
