num_order/
lib.rs

Help
1//!
2//! `num-order` implements numerically consistent [Eq][core::cmp::Eq], [Ord][core::cmp::Ord] and
3//! [Hash][core::hash::Hash] for various `num` types.
4//!
5//! ```rust
6//! use std::cmp::Ordering;
7//! use std::hash::Hasher;
8//! use std::collections::hash_map::DefaultHasher;
9//! use num_order::NumOrd;
10//!
11//! assert!(NumOrd::num_eq(&3u64, &3.0f32));
12//! assert!(NumOrd::num_lt(&-4.7f64, &-4i8));
13//! assert!(!NumOrd::num_ge(&-3i8, &1u16));
14//!
15//! // 40_000_000 can be exactly represented in f32, 40_000_001 cannot
16//! // 40_000_001 becames 40_000_000.0 in f32
17//! assert_eq!(NumOrd::num_cmp(&40_000_000f32, &40_000_000u32), Ordering::Equal);
18//! assert_ne!(NumOrd::num_cmp(&40_000_001f32, &40_000_001u32), Ordering::Equal);
19//! assert_eq!(NumOrd::num_partial_cmp(&f32::NAN, &40_000_002u32), None);
20//!
21//! use num_order::NumHash;
22//! // same hash values are guaranteed for equal numbers
23//! let mut hasher1 = DefaultHasher::new();
24//! 3u64.num_hash(&mut hasher1);
25//! let mut hasher2 = DefaultHasher::new();
26//! 3.0f32.num_hash(&mut hasher2);
27//! assert_eq!(hasher1.finish(), hasher2.finish())
28//! ```
29//!
30//! This crate can serve applications where [float-ord](https://crates.io/crates/float-ord),
31//! [num-cmp](https://crates.io/crates/num-cmp), [num-ord](https://crates.io/crates/num-ord) are used.
32//! Meanwhile it also supports hashing and more numeric types (`num-bigint`, etc.).
33//!
34//! # Optional Features
35//! - `std`: enable std library
36//! - `num-bigint`: Support comparing against and hashing `num-bigint::{BigInt, BigUint}`
37//! - `num-rational`: Support comparing against and hashing `num-rational::Ratio<I>`, where `I` can be
38//!     `i8`, `i16`, `i32`, `i64`, `i128` and `isize`. `Ratio<BigInt>` is supported when both `num-bigint`
39//!     and `num-rational` is enabled
40//! - `num-complex`: Support comparing against and hashing `num-complex::{Complex32, Complex64}`
41//!
42
43#![no_std]
44#[cfg(any(feature = "std", test))]
45extern crate std;
46
47use core::cmp::Ordering;
48use core::hash::Hasher;
49
50/// Consistent comparison among different numeric types.
51pub trait NumOrd<Other> {
52    /// [PartialOrd::partial_cmp] on different numeric types
53    fn num_partial_cmp(&self, other: &Other) -> Option<Ordering>;
54
55    #[inline]
56    /// [PartialEq::eq] on different numeric types
57    fn num_eq(&self, other: &Other) -> bool {
58        matches!(self.num_partial_cmp(other), Some(Ordering::Equal))
59    }
60    #[inline]
61    /// [PartialEq::ne] on different numeric types
62    fn num_ne(&self, other: &Other) -> bool {
63        !self.num_eq(other)
64    }
65    #[inline]
66    /// [PartialOrd::lt] on different numeric types
67    fn num_lt(&self, other: &Other) -> bool {
68        matches!(self.num_partial_cmp(other), Some(Ordering::Less))
69    }
70    #[inline]
71    /// [PartialOrd::le] on different numeric types
72    fn num_le(&self, other: &Other) -> bool {
73        matches!(
74            self.num_partial_cmp(other),
75            Some(Ordering::Equal) | Some(Ordering::Less)
76        )
77    }
78    #[inline]
79    /// [PartialOrd::gt] on different numeric types
80    fn num_gt(&self, other: &Other) -> bool {
81        matches!(self.num_partial_cmp(other), Some(Ordering::Greater))
82    }
83    #[inline]
84    /// [PartialOrd::ge] on different numeric types
85    fn num_ge(&self, other: &Other) -> bool {
86        matches!(
87            self.num_partial_cmp(other),
88            Some(Ordering::Equal) | Some(Ordering::Greater)
89        )
90    }
91    #[inline]
92    /// [Ord::cmp] on different numeric types. It panics if either of the numeric values contains NaN.
93    fn num_cmp(&self, other: &Other) -> Ordering {
94        self.num_partial_cmp(other).unwrap()
95    }
96}
97
98/// Consistent hash implementation among different numeric types.
99///
100/// It's ensured that if `a.num_eq(b)`, then `a` and `b` will result in the same hash. Although the other direction is
101/// not ensured because it's infeasible, the hash function is still designed to be as sparse as possible.
102pub trait NumHash {
103    /// Consistent [Hash::hash][core::hash::Hash::hash] on different numeric types.
104    ///
105    /// This function will ensures if `a.num_eq(b)`, then `a.num_hash()` and `b.num_hash()` manipulate the state in the same way.
106    fn num_hash<H: Hasher>(&self, state: &mut H);
107}
108
109mod hash;
110mod ord;
111#[cfg(test)]
112mod tests;
113
114// TODO: support num-irrational::{QuadraticSurd, QuadraticInt} when their API is stablized
num_order/lib.rs

num_order/
lib.rs
