Trait std::cmp::PartialOrd
1.0.0 · source · pub trait PartialOrd<Rhs = Self>: PartialEq<Rhs>where
Rhs: ?Sized,{
// Required method
fn partial_cmp(&self, other: &Rhs) -> Option<Ordering>;
// Provided methods
fn lt(&self, other: &Rhs) -> bool { ... }
fn le(&self, other: &Rhs) -> bool { ... }
fn gt(&self, other: &Rhs) -> bool { ... }
fn ge(&self, other: &Rhs) -> bool { ... }
}
Expand description
Trait for types that form a partial order.
The lt
, le
, gt
, and ge
methods of this trait can be called using
the <
, <=
, >
, and >=
operators, respectively.
The methods of this trait must be consistent with each other and with those of PartialEq
.
The following conditions must hold:
a == b
if and only ifpartial_cmp(a, b) == Some(Equal)
.a < b
if and only ifpartial_cmp(a, b) == Some(Less)
a > b
if and only ifpartial_cmp(a, b) == Some(Greater)
a <= b
if and only ifa < b || a == b
a >= b
if and only ifa > b || a == b
a != b
if and only if!(a == b)
.
Conditions 2–5 above are ensured by the default implementation.
Condition 6 is already ensured by PartialEq
.
If Ord
is also implemented for Self
and Rhs
, it must also be consistent with
partial_cmp
(see the documentation of that trait for the exact requirements). It’s
easy to accidentally make them disagree by deriving some of the traits and manually
implementing others.
The comparison must satisfy, for all a
, b
and c
:
- transitivity:
a < b
andb < c
impliesa < c
. The same must hold for both==
and>
. - duality:
a < b
if and only ifb > a
.
Note that these requirements mean that the trait itself must be implemented symmetrically and
transitively: if T: PartialOrd<U>
and U: PartialOrd<V>
then U: PartialOrd<T>
and T: PartialOrd<V>
.
Violating these requirements is a logic error. The behavior resulting from a logic error is not
specified, but users of the trait must ensure that such logic errors do not result in
undefined behavior. This means that unsafe
code must not rely on the correctness of these
methods.
§Corollaries
The following corollaries follow from the above requirements:
- irreflexivity of
<
and>
:!(a < a)
,!(a > a)
- transitivity of
>
: ifa > b
andb > c
thena > c
- duality of
partial_cmp
:partial_cmp(a, b) == partial_cmp(b, a).map(Ordering::reverse)
§Strict and non-strict partial orders
The <
and >
operators behave according to a strict partial order.
However, <=
and >=
do not behave according to a non-strict
partial order.
That is because mathematically, a non-strict partial order would require
reflexivity, i.e. a <= a
would need to be true for every a
. This isn’t
always the case for types that implement PartialOrd
, for example:
let a = f64::sqrt(-1.0);
assert_eq!(a <= a, false);
Run§Derivable
This trait can be used with #[derive]
.
When derive
d on structs, it will produce a
lexicographic ordering
based on the top-to-bottom declaration order of the struct’s members.
When derive
d on enums, variants are primarily ordered by their discriminants.
Secondarily, they are ordered by their fields.
By default, the discriminant is smallest for variants at the top, and
largest for variants at the bottom. Here’s an example:
#[derive(PartialEq, PartialOrd)]
enum E {
Top,
Bottom,
}
assert!(E::Top < E::Bottom);
RunHowever, manually setting the discriminants can override this default behavior:
#[derive(PartialEq, PartialOrd)]
enum E {
Top = 2,
Bottom = 1,
}
assert!(E::Bottom < E::Top);
Run§How can I implement PartialOrd
?
PartialOrd
only requires implementation of the partial_cmp
method, with the others
generated from default implementations.
However it remains possible to implement the others separately for types which do not have a
total order. For example, for floating point numbers, NaN < 0 == false
and NaN >= 0 == false
(cf. IEEE 754-2008 section 5.11).
PartialOrd
requires your type to be PartialEq
.
If your type is Ord
, you can implement partial_cmp
by using cmp
:
use std::cmp::Ordering;
#[derive(Eq)]
struct Person {
id: u32,
name: String,
height: u32,
}
impl PartialOrd for Person {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
Some(self.cmp(other))
}
}
impl Ord for Person {
fn cmp(&self, other: &Self) -> Ordering {
self.height.cmp(&other.height)
}
}
impl PartialEq for Person {
fn eq(&self, other: &Self) -> bool {
self.height == other.height
}
}
RunYou may also find it useful to use partial_cmp
on your type’s fields. Here
is an example of Person
types who have a floating-point height
field that
is the only field to be used for sorting:
use std::cmp::Ordering;
struct Person {
id: u32,
name: String,
height: f64,
}
impl PartialOrd for Person {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
self.height.partial_cmp(&other.height)
}
}
impl PartialEq for Person {
fn eq(&self, other: &Self) -> bool {
self.height == other.height
}
}
Run§Examples
let x: u32 = 0;
let y: u32 = 1;
assert_eq!(x < y, true);
assert_eq!(x.lt(&y), true);
RunRequired Methods§
sourcefn partial_cmp(&self, other: &Rhs) -> Option<Ordering>
fn partial_cmp(&self, other: &Rhs) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists.
§Examples
use std::cmp::Ordering;
let result = 1.0.partial_cmp(&2.0);
assert_eq!(result, Some(Ordering::Less));
let result = 1.0.partial_cmp(&1.0);
assert_eq!(result, Some(Ordering::Equal));
let result = 2.0.partial_cmp(&1.0);
assert_eq!(result, Some(Ordering::Greater));
RunWhen comparison is impossible:
let result = f64::NAN.partial_cmp(&1.0);
assert_eq!(result, None);
RunProvided Methods§
Implementors§
impl PartialOrd for AsciiChar
impl PartialOrd for Infallible
impl PartialOrd for ErrorKind
impl PartialOrd for IpAddr
impl PartialOrd for SocketAddr
impl PartialOrd for Ordering
impl PartialOrd for bool
impl PartialOrd for char
impl PartialOrd for f32
impl PartialOrd for f64
impl PartialOrd for i8
impl PartialOrd for i16
impl PartialOrd for i32
impl PartialOrd for i64
impl PartialOrd for i128
impl PartialOrd for isize
impl PartialOrd for !
impl PartialOrd for str
Implements comparison operations on strings.
Strings are compared lexicographically by their byte values. This compares Unicode code
points based on their positions in the code charts. This is not necessarily the same as
“alphabetical” order, which varies by language and locale. Comparing strings according to
culturally-accepted standards requires locale-specific data that is outside the scope of
the str
type.
impl PartialOrd for u8
impl PartialOrd for u16
impl PartialOrd for u32
impl PartialOrd for u64
impl PartialOrd for u128
impl PartialOrd for ()
impl PartialOrd for usize
impl PartialOrd for CpuidResult
impl PartialOrd for TypeId
impl PartialOrd for CStr
impl PartialOrd for CString
impl PartialOrd for OsStr
impl PartialOrd for OsString
impl PartialOrd for Error
impl PartialOrd for PhantomPinned
impl PartialOrd for Ipv4Addr
impl PartialOrd for Ipv6Addr
impl PartialOrd for SocketAddrV4
impl PartialOrd for SocketAddrV6
impl PartialOrd for NonZero<i8>
impl PartialOrd for NonZero<i16>
impl PartialOrd for NonZero<i32>
impl PartialOrd for NonZero<i64>
impl PartialOrd for NonZero<i128>
impl PartialOrd for NonZero<isize>
impl PartialOrd for NonZero<u8>
impl PartialOrd for NonZero<u16>
impl PartialOrd for NonZero<u32>
impl PartialOrd for NonZero<u64>
impl PartialOrd for NonZero<u128>
impl PartialOrd for NonZero<usize>
impl PartialOrd for Path
impl PartialOrd for PathBuf
impl PartialOrd for Alignment
impl PartialOrd for String
impl PartialOrd for Duration
impl PartialOrd for Instant
impl PartialOrd for SystemTime
impl PartialOrd<IpAddr> for Ipv4Addr
impl PartialOrd<IpAddr> for Ipv6Addr
impl PartialOrd<str> for OsStr
impl PartialOrd<str> for OsString
impl PartialOrd<OsStr> for Path
impl PartialOrd<OsStr> for PathBuf
impl PartialOrd<OsString> for Path
impl PartialOrd<OsString> for PathBuf
impl PartialOrd<Ipv4Addr> for IpAddr
impl PartialOrd<Ipv6Addr> for IpAddr
impl PartialOrd<Path> for OsStr
impl PartialOrd<Path> for OsString
impl PartialOrd<Path> for PathBuf
impl PartialOrd<PathBuf> for OsStr
impl PartialOrd<PathBuf> for OsString
impl PartialOrd<PathBuf> for Path
impl<'a> PartialOrd for Component<'a>
impl<'a> PartialOrd for Prefix<'a>
impl<'a> PartialOrd for Location<'a>
impl<'a> PartialOrd for Components<'a>
impl<'a> PartialOrd for PrefixComponent<'a>
impl<'a> PartialOrd<&'a OsStr> for Path
impl<'a> PartialOrd<&'a OsStr> for PathBuf
impl<'a> PartialOrd<&'a Path> for OsStr
impl<'a> PartialOrd<&'a Path> for OsString
impl<'a> PartialOrd<&'a Path> for PathBuf
impl<'a> PartialOrd<Cow<'a, OsStr>> for Path
impl<'a> PartialOrd<Cow<'a, OsStr>> for PathBuf
impl<'a> PartialOrd<Cow<'a, Path>> for OsStr
impl<'a> PartialOrd<Cow<'a, Path>> for OsString
impl<'a> PartialOrd<Cow<'a, Path>> for Path
impl<'a> PartialOrd<Cow<'a, Path>> for PathBuf
impl<'a> PartialOrd<OsStr> for &'a Path
impl<'a> PartialOrd<OsStr> for Cow<'a, Path>
impl<'a> PartialOrd<OsString> for &'a Path
impl<'a> PartialOrd<OsString> for Cow<'a, Path>
impl<'a> PartialOrd<Path> for &'a OsStr
impl<'a> PartialOrd<Path> for Cow<'a, OsStr>
impl<'a> PartialOrd<Path> for Cow<'a, Path>
impl<'a> PartialOrd<PathBuf> for &'a OsStr
impl<'a> PartialOrd<PathBuf> for &'a Path
impl<'a> PartialOrd<PathBuf> for Cow<'a, OsStr>
impl<'a> PartialOrd<PathBuf> for Cow<'a, Path>
impl<'a, 'b> PartialOrd<&'a OsStr> for OsString
impl<'a, 'b> PartialOrd<&'a Path> for Cow<'b, OsStr>
impl<'a, 'b> PartialOrd<&'b OsStr> for Cow<'a, OsStr>
impl<'a, 'b> PartialOrd<&'b OsStr> for Cow<'a, Path>
impl<'a, 'b> PartialOrd<&'b Path> for Cow<'a, Path>
impl<'a, 'b> PartialOrd<Cow<'a, OsStr>> for &'b OsStr
impl<'a, 'b> PartialOrd<Cow<'a, OsStr>> for OsStr
impl<'a, 'b> PartialOrd<Cow<'a, OsStr>> for OsString
impl<'a, 'b> PartialOrd<Cow<'a, Path>> for &'b OsStr
impl<'a, 'b> PartialOrd<Cow<'a, Path>> for &'b Path
impl<'a, 'b> PartialOrd<Cow<'b, OsStr>> for &'a Path
impl<'a, 'b> PartialOrd<OsStr> for Cow<'a, OsStr>
impl<'a, 'b> PartialOrd<OsStr> for OsString
impl<'a, 'b> PartialOrd<OsString> for &'a OsStr
impl<'a, 'b> PartialOrd<OsString> for Cow<'a, OsStr>
impl<'a, 'b> PartialOrd<OsString> for OsStr
impl<'a, B> PartialOrd for Cow<'a, B>
impl<A, B> PartialOrd<&B> for &A
impl<A, B> PartialOrd<&mut B> for &mut A
impl<Dyn> PartialOrd for DynMetadata<Dyn>where
Dyn: ?Sized,
impl<F> PartialOrd for Fwhere
F: FnPtr,
impl<K, V, A> PartialOrd for BTreeMap<K, V, A>
impl<Ptr, Q> PartialOrd<Pin<Q>> for Pin<Ptr>
impl<T> PartialOrd for Option<T>where
T: PartialOrd,
impl<T> PartialOrd for Poll<T>where
T: PartialOrd,
impl<T> PartialOrd for *const Twhere
T: ?Sized,
impl<T> PartialOrd for *mut Twhere
T: ?Sized,
impl<T> PartialOrd for [T]where
T: PartialOrd,
Implements comparison of vectors lexicographically.
impl<T> PartialOrd for (T₁, T₂, …, Tₙ)where
T: PartialOrd + ?Sized,
This trait is implemented for tuples up to twelve items long.
impl<T> PartialOrd for Cell<T>where
T: PartialOrd + Copy,
impl<T> PartialOrd for RefCell<T>where
T: PartialOrd + ?Sized,
impl<T> PartialOrd for PhantomData<T>where
T: ?Sized,
impl<T> PartialOrd for ManuallyDrop<T>where
T: PartialOrd + ?Sized,
impl<T> PartialOrd for Saturating<T>where
T: PartialOrd,
impl<T> PartialOrd for Wrapping<T>where
T: PartialOrd,
impl<T> PartialOrd for NonNull<T>where
T: ?Sized,
impl<T> PartialOrd for Reverse<T>where
T: PartialOrd,
impl<T, A1, A2> PartialOrd<Vec<T, A2>> for Vec<T, A1>
Implements comparison of vectors, lexicographically.