//! The **[`NumCmp`](./trait.NumCmp.html)** trait for comparison between differently typed numbers.
//!
//! ```rust
//! use std::f32;
//! use std::cmp::Ordering;
//! use num_cmp::NumCmp;
//!
//! assert!(NumCmp::num_eq(3u64, 3.0f32));
//! assert!(NumCmp::num_lt(-4.7f64, -4i8));
//! assert!(!NumCmp::num_ge(-3i8, 1u16));
//!
//! // 40_000_000 can be exactly represented in f32, 40_000_001 cannot
//! assert_eq!(NumCmp::num_cmp(40_000_000.0f32, 40_000_000u32), Some(Ordering::Equal));
//! assert_ne!(NumCmp::num_cmp(40_000_001.0f32, 40_000_001u32), Some(Ordering::Equal));
//! assert_eq!(NumCmp::num_cmp(f32::NAN, 40_000_002u32), None);
//! ```
//!
//! The `i128` Cargo feature can be enabled in nightly
//! to get support for `i128` and `u128` types as well,
//! which is being implemented in [Rust issue #35118][issue-35118].
//!
//! [issue-35118]: https://github.com/rust-lang/rust/issues/35118
#![cfg_attr(feature = "i128", feature(i128_type))]
#![deny(missing_docs)]
use std::cmp::Ordering;
/// A trait for comparison between differently typed numbers.
///
/// This trait is implemented for every pair of integer and floating-point types available,
/// including `isize`, `usize` and also (when the `i128` feature is enabled) `i128` and `u128`.
pub trait NumCmp<Other: Copy>: Copy {
// only used for testing
#[cfg(test)] fn num_cmp_strategy(self, other: Other) -> &'static str;
/// Same to `self.partial_cmp(&other)`
/// but can be used for different numeric types for `self` and `other`.
fn num_cmp(self, other: Other) -> Option<Ordering>;
/// Same to `self == other` but can be used for different numeric types for `self` and `other`.
fn num_eq(self, other: Other) -> bool;
/// Same to `self != other` but can be used for different numeric types for `self` and `other`.
fn num_ne(self, other: Other) -> bool;
/// Same to `self < other` but can be used for different numeric types for `self` and `other`.
fn num_lt(self, other: Other) -> bool;
/// Same to `self > other` but can be used for different numeric types for `self` and `other`.
fn num_gt(self, other: Other) -> bool;
/// Same to `self <= other` but can be used for different numeric types for `self` and `other`.
fn num_le(self, other: Other) -> bool;
/// Same to `self >= other` but can be used for different numeric types for `self` and `other`.
fn num_ge(self, other: Other) -> bool;
}
// strategy 1: for the same type T, delegate to normal operators.
macro_rules! impl_for_equal_types {
($($ty:ty;)*) => ($(
impl NumCmp<$ty> for $ty {
#[cfg(test)]
fn num_cmp_strategy(self, _other: $ty) -> &'static str {
"strategy 1"
}
#[inline]
fn num_cmp(self, other: $ty) -> Option<Ordering> {
self.partial_cmp(&other)
}
#[inline]
fn num_eq(self, other: $ty) -> bool {
self == other
}
#[inline]
fn num_ne(self, other: $ty) -> bool {
self != other
}
#[inline]
fn num_lt(self, other: $ty) -> bool {
self < other
}
#[inline]
fn num_gt(self, other: $ty) -> bool {
self > other
}
#[inline]
fn num_le(self, other: $ty) -> bool {
self <= other
}
#[inline]
fn num_ge(self, other: $ty) -> bool {
self >= other
}
}
)*);
}
// strategy 2: for two types where one of them is isize or usize,
// delegate to implementations for the equivalently sized types.
macro_rules! impl_for_size_types {
($($size:ty => $nonsize:ty, $other:ty;)*) => ($(
impl NumCmp<$other> for $size {
#[cfg(test)]
fn num_cmp_strategy(self, _other: $other) -> &'static str {
"strategy 2, size vs other"
}
#[inline]
fn num_cmp(self, other: $other) -> Option<Ordering> {
(self as $nonsize).num_cmp(other)
}
#[inline]
fn num_eq(self, other: $other) -> bool {
(self as $nonsize).num_eq(other)
}
#[inline]
fn num_ne(self, other: $other) -> bool {
(self as $nonsize).num_ne(other)
}
#[inline]
fn num_lt(self, other: $other) -> bool {
(self as $nonsize).num_lt(other)
}
#[inline]
fn num_gt(self, other: $other) -> bool {
(self as $nonsize).num_gt(other)
}
#[inline]
fn num_le(self, other: $other) -> bool {
(self as $nonsize).num_le(other)
}
#[inline]
fn num_ge(self, other: $other) -> bool {
(self as $nonsize).num_ge(other)
}
}
impl NumCmp<$size> for $other {
#[cfg(test)]
fn num_cmp_strategy(self, _other: $size) -> &'static str {
"strategy 2, nonsize vs size"
}
#[inline]
fn num_cmp(self, other: $size) -> Option<Ordering> {
self.num_cmp(other as $nonsize)
}
#[inline]
fn num_eq(self, other: $size) -> bool {
self.num_eq(other as $nonsize)
}
#[inline]
fn num_ne(self, other: $size) -> bool {
self.num_ne(other as $nonsize)
}
#[inline]
fn num_lt(self, other: $size) -> bool {
self.num_lt(other as $nonsize)
}
#[inline]
fn num_gt(self, other: $size) -> bool {
self.num_gt(other as $nonsize)
}
#[inline]
fn num_le(self, other: $size) -> bool {
self.num_le(other as $nonsize)
}
#[inline]
fn num_ge(self, other: $size) -> bool {
self.num_ge(other as $nonsize)
}
}
)*);
}
// strategy 3: for two types T and U,
// (without loss of generality) when T can be always exactly casted to U,
// compare them by casting T to U.
macro_rules! impl_for_nonequal_types_with_casting {
($($big:ty, $small:ty;)*) => ($(
impl NumCmp<$small> for $big {
#[cfg(test)]
fn num_cmp_strategy(self, _other: $small) -> &'static str {
"strategy 3, big vs small"
}
#[inline]
fn num_cmp(self, other: $small) -> Option<Ordering> {
self.partial_cmp(&(other as $big))
}
#[inline]
fn num_eq(self, other: $small) -> bool {
self == other as $big
}
#[inline]
fn num_ne(self, other: $small) -> bool {
self != other as $big
}
#[inline]
fn num_lt(self, other: $small) -> bool {
self < other as $big
}
#[inline]
fn num_gt(self, other: $small) -> bool {
self > other as $big
}
#[inline]
fn num_le(self, other: $small) -> bool {
self <= other as $big
}
#[inline]
fn num_ge(self, other: $small) -> bool {
self >= other as $big
}
}
impl NumCmp<$big> for $small {
#[cfg(test)]
fn num_cmp_strategy(self, _other: $big) -> &'static str {
"strategy 3, small vs big"
}
#[inline]
fn num_cmp(self, other: $big) -> Option<Ordering> {
(self as $big).partial_cmp(&other)
}
#[inline]
fn num_eq(self, other: $big) -> bool {
self as $big == other
}
#[inline]
fn num_ne(self, other: $big) -> bool {
self as $big != other
}
#[inline]
fn num_lt(self, other: $big) -> bool {
(self as $big) < other
}
#[inline]
fn num_gt(self, other: $big) -> bool {
self as $big > other
}
#[inline]
fn num_le(self, other: $big) -> bool {
self as $big <= other
}
#[inline]
fn num_ge(self, other: $big) -> bool {
self as $big >= other
}
}
)*);
}
// strategy 4: for unsigned type T and signed type U,
// if bit size of T is no less than that of U,
// check if both operands are positive before doing the normal comparison in unsigned type.
macro_rules! impl_for_nonequal_types_with_different_signedness {
($($unsigned:ty, $signed:ty;)*) => ($(
impl NumCmp<$signed> for $unsigned {
#[cfg(test)]
fn num_cmp_strategy(self, _other: $signed) -> &'static str {
"strategy 4, unsigned vs signed"
}
#[inline]
fn num_cmp(self, other: $signed) -> Option<Ordering> {
if other < 0 {
Some(Ordering::Greater)
} else {
self.partial_cmp(&(other as $unsigned))
}
}
#[inline]
fn num_eq(self, other: $signed) -> bool {
other >= 0 && self == other as $unsigned
}
#[inline]
fn num_ne(self, other: $signed) -> bool {
other < 0 || self != other as $unsigned
}
#[inline]
fn num_lt(self, other: $signed) -> bool {
other > 0 && self < other as $unsigned
}
#[inline]
fn num_gt(self, other: $signed) -> bool {
other < 0 || self > other as $unsigned
}
#[inline]
fn num_le(self, other: $signed) -> bool {
other >= 0 && self <= other as $unsigned
}
#[inline]
fn num_ge(self, other: $signed) -> bool {
other <= 0 || self >= other as $unsigned
}
}
impl NumCmp<$unsigned> for $signed {
#[cfg(test)]
fn num_cmp_strategy(self, _other: $unsigned) -> &'static str {
"strategy 4, signed vs unsigned"
}
#[inline]
fn num_cmp(self, other: $unsigned) -> Option<Ordering> {
if self < 0 {
Some(Ordering::Less)
} else {
(self as $unsigned).partial_cmp(&other)
}
}
#[inline]
fn num_eq(self, other: $unsigned) -> bool {
self >= 0 && self as $unsigned == other
}
#[inline]
fn num_ne(self, other: $unsigned) -> bool {
self < 0 || self as $unsigned != other
}
#[inline]
fn num_lt(self, other: $unsigned) -> bool {
self < 0 || (self as $unsigned) < other
}
#[inline]
fn num_gt(self, other: $unsigned) -> bool {
self > 0 && self as $unsigned > other
}
#[inline]
fn num_le(self, other: $unsigned) -> bool {
self <= 0 || self as $unsigned <= other
}
#[inline]
fn num_ge(self, other: $unsigned) -> bool {
self >= 0 && self as $unsigned >= other
}
}
)*);
}
// strategy 5: for two types T and U,
// when T can be casted to U but it may result in precision loss,
// first bound the operand in type U to the domain of type T;
// when testing equality the bound failure means the inequality,
// otherwise we convert to the appropriate value in type T so that the comparison can continue.
//
// since all integral conversion does not lose precision (but can be out of range),
// T is guaranteed to be integral while U is guaranteed to be floating-point.
// it is possible that bounds themselves can be overflown (especially when T=u128, U=f32).
//
// for general comparison we have the following useful observation:
//
// where `a cmp b` is a general partial ordering operator (like `PartialOrd::partial_cmp`)
// and `trunc(x)` is `x` rounded towards zero (i.e. trunc(3.5) = 3, trunc(-3.5) = -3),
// if `a` is an integer, `a cmp b` equals to `(a, trunc(b)) cmp (trunc(b), b)`.
// (we assume that the tuple is ordered lexicographically.)
//
// the proof involves an equality `floor(x) <= trunc(x) <= ceil(x)`,
// and inequalities `n < x <=> n < ceil(x)` and `x < n <=> floor(x) < n` for integer `n`.
// when `a < trunc(b)` it follows that `a < trunc(b) <= ceil(b)`, which implies `a < b`;
// when `a > trunc(b)` it follows that `a > trunc(b) >= floor(b)`, which implies `a > b`;
// when `a = trunc(b)` any inequality `trunc(b) op b` follows that `a = trunc(b) op b`,
// which clearly implies `a op b` as intended. Q.E.D.
//
// since `a` and `trunc(b)` can be made into the same type after bounds checking,
// this gives very uniform and simple way to compare numbers.
// we of course rely on the fact that the range of `trunc(a)` is smaller than the domain of `a`.
// requires that the float operand is not NaN and in the ($lb, $ub) range
macro_rules! trunc_cmp {
(int $lhs:expr, $method:ident, float $rhs:expr;
($lb:expr) <= ($intty:ty) < ($ub:expr)) => ({
let rhsint = $rhs.trunc();
debug_assert!($lb <= rhsint && rhsint < $ub);
($lhs, rhsint).$method(&(rhsint as $intty, $rhs))
});
(float $lhs:expr, $method:ident, int $rhs:expr;
($lb:expr) <= ($intty:ty) < ($ub:expr)) => ({
let lhsint = $lhs.trunc();
debug_assert!($lb <= lhsint && lhsint < $ub);
(lhsint as $intty, $lhs).$method(&($rhs, lhsint))
});
}
macro_rules! impl_for_int_and_float_types_with_bounds_check {
($($float:ty, $int:ty, ($lb:expr) <= _ < ($ub:expr);)*) => ($(
impl NumCmp<$int> for $float {
#[cfg(test)]
fn num_cmp_strategy(self, _other: $int) -> &'static str {
"strategy 5, float vs int"
}
#[inline]
fn num_cmp(self, other: $int) -> Option<Ordering> {
if self < $lb {
Some(Ordering::Less)
} else if $ub <= self {
Some(Ordering::Greater)
} else if self == self {
trunc_cmp!(float self, partial_cmp, int other; ($lb) <= ($int) < ($ub))
} else {
None
}
}
#[inline]
fn num_eq(self, other: $int) -> bool {
$lb <= self && self < $ub && trunc_cmp!(float self, eq, int other;
($lb) <= ($int) < ($ub))
}
#[inline]
fn num_ne(self, other: $int) -> bool {
// we cannot blindly apply De Morgan's law; we need to catch NaN early on
!($lb <= self && self < $ub) || trunc_cmp!(float self, ne, int other;
($lb) <= ($int) < ($ub))
}
#[inline]
fn num_lt(self, other: $int) -> bool {
self < $ub && (self < $lb || trunc_cmp!(float self, lt, int other;
($lb) <= ($int) < ($ub)))
}
#[inline]
fn num_gt(self, other: $int) -> bool {
$lb <= self && ($ub <= self || trunc_cmp!(float self, gt, int other;
($lb) <= ($int) < ($ub)))
}
#[inline]
fn num_le(self, other: $int) -> bool {
self < $ub && (self < $lb || trunc_cmp!(float self, le, int other;
($lb) <= ($int) < ($ub)))
}
#[inline]
fn num_ge(self, other: $int) -> bool {
$lb <= self && ($ub <= self || trunc_cmp!(float self, ge, int other;
($lb) <= ($int) < ($ub)))
}
}
impl NumCmp<$float> for $int {
#[cfg(test)]
fn num_cmp_strategy(self, _other: $float) -> &'static str {
"strategy 5, int vs float"
}
#[inline]
fn num_cmp(self, other: $float) -> Option<Ordering> {
if other < $lb {
Some(Ordering::Greater)
} else if $ub <= other {
Some(Ordering::Less)
} else if other == other {
trunc_cmp!(int self, partial_cmp, float other; ($lb) <= ($int) < ($ub))
} else {
None
}
}
#[inline]
fn num_eq(self, other: $float) -> bool {
$lb <= other && other < $ub && trunc_cmp!(int self, eq, float other;
($lb) <= ($int) < ($ub))
}
#[inline]
fn num_ne(self, other: $float) -> bool {
// we cannot blindly apply De Morgan's law; we need to catch NaN early on
!($lb <= other && other < $ub) || trunc_cmp!(int self, ne, float other;
($lb) <= ($int) < ($ub))
}
#[inline]
fn num_lt(self, other: $float) -> bool {
$lb <= other && ($ub <= other || trunc_cmp!(int self, lt, float other;
($lb) <= ($int) < ($ub)))
}
#[inline]
fn num_gt(self, other: $float) -> bool {
other < $ub && (other < $lb || trunc_cmp!(int self, gt, float other;
($lb) <= ($int) < ($ub)))
}
#[inline]
fn num_le(self, other: $float) -> bool {
$lb <= other && ($ub <= other || trunc_cmp!(int self, le, float other;
($lb) <= ($int) < ($ub)))
}
#[inline]
fn num_ge(self, other: $float) -> bool {
other < $ub && (other < $lb || trunc_cmp!(int self, ge, float other;
($lb) <= ($int) < ($ub)))
}
}
)*);
}
// actual implementations.
// there should be 12 * 12 = 144 implementations for the NumCmp trait
// (or 14 * 14 = 196 implementations if the `i128` feature is enabled).
impl_for_equal_types! {
u8; u16; u32; u64; usize;
i8; i16; i32; i64; isize;
f32; f64;
}
#[cfg(feature = "i128")]
impl_for_equal_types! {
u128;
i128;
}
#[cfg(target_pointer_width = "32")]
impl_for_size_types! {
usize => u32, u8; isize => i32, u8;
usize => u32, u16; isize => i32, u16;
usize => u32, u32; isize => i32, u32;
usize => u32, u64; isize => i32, u64;
usize => u32, i8; isize => i32, i8;
usize => u32, i16; isize => i32, i16;
usize => u32, i32; isize => i32, i32;
usize => u32, i64; isize => i32, i64;
usize => u32, f32; isize => i32, f32;
usize => u32, f64; isize => i32, f64;
}
#[cfg(target_pointer_width = "64")]
impl_for_size_types! {
usize => u64, u8; isize => i64, u8;
usize => u64, u16; isize => i64, u16;
usize => u64, u32; isize => i64, u32;
usize => u64, u64; isize => i64, u64;
usize => u64, i8; isize => i64, i8;
usize => u64, i16; isize => i64, i16;
usize => u64, i32; isize => i64, i32;
usize => u64, i64; isize => i64, i64;
usize => u64, f32; isize => i64, f32;
usize => u64, f64; isize => i64, f64;
}
#[cfg(all(target_pointer_width = "32", feature = "i128"))]
impl_for_size_types! {
usize => u32, u128; isize => i32, u128;
usize => u32, i128; isize => i32, i128;
}
#[cfg(all(target_pointer_width = "64", feature = "i128"))]
impl_for_size_types! {
usize => u64, u128; isize => i64, u128;
usize => u64, i128; isize => i64, i128;
}
impl_for_nonequal_types_with_casting! {
// uN, uM for N > M
u64, u8; u32, u8; u16, u8;
u64, u16; u32, u16;
u64, u32;
// iN, iM for N > M
i64, i8; i32, i8; i16, i8;
i64, i16; i32, i16;
i64, i32;
// iN, uM for N > M
i64, u8; i32, u8; i16, u8;
i64, u16; i32, u16;
i64, u32;
// fN, fM for N > M
f64, f32;
// f32, uM for 24 >= M, since f32 can exactly represent all integers (-2^24,2^24)
// f64, uM for 53 >= M, since f64 can exactly represent all integers (-2^53,2^53)
f32, u8; f32, u16;
f64, u8; f64, u16; f64, u32;
// f32, iM for 24 >= M
// f64, iM for 53 >= M
// since iM's range [-2^(M-1),2^(M-1)) includes -2^(M-1), bounds do not change
f32, i8; f32, i16;
f64, i8; f64, i16; f64, i32;
}
#[cfg(feature = "i128")]
impl_for_nonequal_types_with_casting! {
u128, u8; u128, u16; u128, u32; u128, u64;
i128, u8; i128, u16; i128, u32; i128, u64;
i128, i8; i128, i16; i128, i32; i128, i64;
}
impl_for_nonequal_types_with_different_signedness! {
u64, i8; u32, i8; u16, i8; u8, i8;
u64, i16; u32, i16; u16, i16;
u64, i32; u32, i32;
u64, i64;
usize, isize;
}
#[cfg(feature = "i128")]
impl_for_nonequal_types_with_different_signedness! {
u128, i8;
u128, i16;
u128, i32;
u128, i64;
u128, i128;
}
const U32_BOUND_IN_F32: f32 = 4294967296.0;
const I32_BOUND_IN_F32: f32 = 2147483648.0;
const U64_BOUND_IN_F32: f32 = 18446744073709551616.0;
const U64_BOUND_IN_F64: f64 = 18446744073709551616.0;
const I64_BOUND_IN_F32: f32 = 9223372036854775808.0;
const I64_BOUND_IN_F64: f64 = 9223372036854775808.0;
impl_for_int_and_float_types_with_bounds_check! {
// f32, uM for 24 < M
// f64, uM for 53 < M
f32, u32, (0.0) <= _ < (U32_BOUND_IN_F32);
f32, u64, (0.0) <= _ < (U64_BOUND_IN_F32);
f64, u64, (0.0) <= _ < (U64_BOUND_IN_F64);
// f32, iM for 24 < M
// f64, iM for 53 < M
f32, i32, (-I32_BOUND_IN_F32) <= _ < (I32_BOUND_IN_F32);
f32, i64, (-I64_BOUND_IN_F32) <= _ < (I64_BOUND_IN_F32);
f64, i64, (-I64_BOUND_IN_F64) <= _ < (I64_BOUND_IN_F64);
}
#[cfg(feature = "i128")] const U128_BOUND_IN_F32: f32 = std::f32::INFINITY;
#[cfg(feature = "i128")] const U128_BOUND_IN_F64: f64 = 340282366920938463463374607431768211456.0;
#[cfg(feature = "i128")] const I128_BOUND_IN_F32: f32 = 170141183460469231731687303715884105728.0;
#[cfg(feature = "i128")] const I128_BOUND_IN_F64: f64 = 170141183460469231731687303715884105728.0;
#[cfg(feature = "i128")]
impl_for_int_and_float_types_with_bounds_check! {
f32, u128, (0.0) <= _ < (U128_BOUND_IN_F32);
f64, u128, (0.0) <= _ < (U128_BOUND_IN_F64);
f32, i128, (-I128_BOUND_IN_F32) <= _ < (I128_BOUND_IN_F32);
f64, i128, (-I128_BOUND_IN_F64) <= _ < (I128_BOUND_IN_F64);
}
#[cfg(test)] mod tests;
