pub trait Ord: Eq + PartialOrd {
// Required method
fn cmp(&self, other: &Self) -> Ordering;
// Provided methods
fn max(self, other: Self) -> Self
where Self: Sized { ... }
fn min(self, other: Self) -> Self
where Self: Sized { ... }
fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized { ... }
fn clamp_to<R>(self, range: R) -> Self
where Self: Sized,
R: ClampBounds<Self> { ... }
}mtls and std only.Expand description
Trait for types that form a total order.
Implementations must be consistent with the PartialOrd implementation, and ensure max,
min, and clamp are consistent with cmp:
partial_cmp(a, b) == Some(cmp(a, b)).max(a, b) == max_by(a, b, cmp)(ensured by the default implementation).min(a, b) == min_by(a, b, cmp)(ensured by the default implementation).- For
a.clamp(min, max), see the method docs (ensured by the default implementation).
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
From the above and the requirements of PartialOrd, it follows that for all a, b and c:
- exactly one of
a < b,a == bora > bis true; and <is transitive:a < bandb < cimpliesa < c. The same must hold for both==and>.
Mathematically speaking, the < operator defines a strict weak order. In cases where ==
conforms to mathematical equality, it also defines a strict total order.
§Derivable
This trait can be used with #[derive].
When derived on structs, it will produce a
lexicographic ordering based on the
top-to-bottom declaration order of the struct’s members.
When derived on enums, variants are ordered primarily 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, Eq, PartialOrd, Ord)]
enum E {
Top,
Bottom,
}
assert!(E::Top < E::Bottom);However, manually setting the discriminants can override this default behavior:
#[derive(PartialEq, Eq, PartialOrd, Ord)]
enum E {
Top = 2,
Bottom = 1,
}
assert!(E::Bottom < E::Top);§Lexicographical comparison
Lexicographical comparison is an operation with the following properties:
- Two sequences are compared element by element.
- The first mismatching element defines which sequence is lexicographically less or greater than the other.
- If one sequence is a prefix of another, the shorter sequence is lexicographically less than the other.
- If two sequences have equivalent elements and are of the same length, then the sequences are lexicographically equal.
- An empty sequence is lexicographically less than any non-empty sequence.
- Two empty sequences are lexicographically equal.
§How can I implement Ord?
Ord requires that the type also be PartialOrd, PartialEq, and Eq.
Because Ord implies a stronger ordering relationship than PartialOrd, and both Ord and
PartialOrd must agree, you must choose how to implement Ord first. You can choose to
derive it, or implement it manually. If you derive it, you should derive all four traits. If you
implement it manually, you should manually implement all four traits, based on the
implementation of Ord.
Here’s an example where you want to define the Character comparison by health and
experience only, disregarding the field mana:
use std::cmp::Ordering;
struct Character {
health: u32,
experience: u32,
mana: f32,
}
impl Ord for Character {
fn cmp(&self, other: &Self) -> Ordering {
self.experience
.cmp(&other.experience)
.then(self.health.cmp(&other.health))
}
}
impl PartialOrd for Character {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
Some(self.cmp(other))
}
}
impl PartialEq for Character {
fn eq(&self, other: &Self) -> bool {
self.health == other.health && self.experience == other.experience
}
}
impl Eq for Character {}If all you need is to slice::sort a type by a field value, it can be simpler to use
slice::sort_by_key.
§Examples of incorrect Ord implementations
use std::cmp::Ordering;
#[derive(Debug)]
struct Character {
health: f32,
}
impl Ord for Character {
fn cmp(&self, other: &Self) -> std::cmp::Ordering {
if self.health < other.health {
Ordering::Less
} else if self.health > other.health {
Ordering::Greater
} else {
Ordering::Equal
}
}
}
impl PartialOrd for Character {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
Some(self.cmp(other))
}
}
impl PartialEq for Character {
fn eq(&self, other: &Self) -> bool {
self.health == other.health
}
}
impl Eq for Character {}
let a = Character { health: 4.5 };
let b = Character { health: f32::NAN };
// Mistake: floating-point values do not form a total order and using the built-in comparison
// operands to implement `Ord` irregardless of that reality does not change it. Use
// `f32::total_cmp` if you need a total order for floating-point values.
// Reflexivity requirement of `Ord` is not given.
assert!(a == a);
assert!(b != b);
// Antisymmetry requirement of `Ord` is not given. Only one of a < c and c < a is allowed to be
// true, not both or neither.
assert_eq!((a < b) as u8 + (b < a) as u8, 0);use std::cmp::Ordering;
#[derive(Debug)]
struct Character {
health: u32,
experience: u32,
}
impl PartialOrd for Character {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
Some(self.cmp(other))
}
}
impl Ord for Character {
fn cmp(&self, other: &Self) -> std::cmp::Ordering {
if self.health < 50 {
self.health.cmp(&other.health)
} else {
self.experience.cmp(&other.experience)
}
}
}
// For performance reasons implementing `PartialEq` this way is not the idiomatic way, but it
// ensures consistent behavior between `PartialEq`, `PartialOrd` and `Ord` in this example.
impl PartialEq for Character {
fn eq(&self, other: &Self) -> bool {
self.cmp(other) == Ordering::Equal
}
}
impl Eq for Character {}
let a = Character {
health: 3,
experience: 5,
};
let b = Character {
health: 10,
experience: 77,
};
let c = Character {
health: 143,
experience: 2,
};
// Mistake: The implementation of `Ord` compares different fields depending on the value of
// `self.health`, the resulting order is not total.
// Transitivity requirement of `Ord` is not given. If a is smaller than b and b is smaller than
// c, by transitive property a must also be smaller than c.
assert!(a < b && b < c && c < a);
// Antisymmetry requirement of `Ord` is not given. Only one of a < c and c < a is allowed to be
// true, not both or neither.
assert_eq!((a < c) as u8 + (c < a) as u8, 2);The documentation of PartialOrd contains further examples, for example it’s wrong for
PartialOrd and PartialEq to disagree.
Required Methods§
1.0.0 (const: unstable) · Sourcefn cmp(&self, other: &Self) -> Ordering
fn cmp(&self, other: &Self) -> Ordering
This method returns an Ordering between self and other.
By convention, self.cmp(&other) returns the ordering matching the expression
self <operator> other if true.
§Examples
use std::cmp::Ordering;
assert_eq!(5.cmp(&10), Ordering::Less);
assert_eq!(10.cmp(&5), Ordering::Greater);
assert_eq!(5.cmp(&5), Ordering::Equal);Provided Methods§
1.21.0 (const: unstable) · Sourcefn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
Compares and returns the maximum of two values.
Returns the second argument if the comparison determines them to be equal.
§Examples
assert_eq!(1.max(2), 2);
assert_eq!(2.max(2), 2);use std::cmp::Ordering;
#[derive(Eq)]
struct Equal(&'static str);
impl PartialEq for Equal {
fn eq(&self, other: &Self) -> bool { true }
}
impl PartialOrd for Equal {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> { Some(Ordering::Equal) }
}
impl Ord for Equal {
fn cmp(&self, other: &Self) -> Ordering { Ordering::Equal }
}
assert_eq!(Equal("self").max(Equal("other")).0, "other");1.21.0 (const: unstable) · Sourcefn min(self, other: Self) -> Selfwhere
Self: Sized,
fn min(self, other: Self) -> Selfwhere
Self: Sized,
Compares and returns the minimum of two values.
Returns the first argument if the comparison determines them to be equal.
§Examples
assert_eq!(1.min(2), 1);
assert_eq!(2.min(2), 2);use std::cmp::Ordering;
#[derive(Eq)]
struct Equal(&'static str);
impl PartialEq for Equal {
fn eq(&self, other: &Self) -> bool { true }
}
impl PartialOrd for Equal {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> { Some(Ordering::Equal) }
}
impl Ord for Equal {
fn cmp(&self, other: &Self) -> Ordering { Ordering::Equal }
}
assert_eq!(Equal("self").min(Equal("other")).0, "self");Sourcefn clamp_to<R>(self, range: R) -> Selfwhere
Self: Sized,
R: ClampBounds<Self>,
🔬This is a nightly-only experimental API. (clamp_to)
fn clamp_to<R>(self, range: R) -> Selfwhere
Self: Sized,
R: ClampBounds<Self>,
clamp_to)Restrict a value to a certain range.
This is equal to max, min, or clamp, depending on whether the range is min..,
..=max, or min..=max, respectively. Exclusive ranges are not permitted.
§Panics
Panics on min..=max if min > max.
§Examples
#![feature(clamp_to)]
assert_eq!((-3).clamp_to(-2..=1), -2);
assert_eq!(0.clamp_to(-2..=1), 0);
assert_eq!(2.clamp_to(..=1), 1);
assert_eq!(5.clamp_to(7..), 7);Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".
Implementors§
impl Ord for !
impl Ord for ()
impl Ord for ASN1DateTime
impl Ord for ASN1Time
impl Ord for ASN1TimeZone
impl Ord for ATerm
impl Ord for Alignment
impl Ord for AnyDelimiterCodec
impl Ord for AsciiChar
impl Ord for Attribute
impl Ord for B0
impl Ord for B1
impl Ord for BStr
impl Ord for BigEndian
impl Ord for BigInt
impl Ord for BigUint
impl Ord for Braced
impl Ord for ByteBuf
impl Ord for ByteStr
impl Ord for ByteString
impl Ord for ByteUnit
impl Ord for bytes::bytes::Bytes
impl Ord for winnow::stream::bytes::Bytes
impl Ord for BytesCodec
impl Ord for BytesMut
impl Ord for CStr
impl Ord for CString
impl Ord for CharCase
impl Ord for Color
impl Ord for Components<'_>
impl Ord for Condition
impl Ord for ConnectionHandle
impl Ord for ConnectionId
impl Ord for CpuidResult
impl Ord for toml_datetime::datetime::Date
impl Ord for time::date::Date
impl Ord for Datetime
impl Ord for Dir
impl Ord for Direction
impl Ord for Duration
impl Ord for Empty
impl Ord for Equal
impl Ord for Errno
impl Ord for rocket::mtls::oid::asn1_rs::nom::lib::std::fmt::Error
impl Ord for aead::Error
impl Ord for ErrorKind
impl Ord for FieldId
impl Ord for FipsStatus
impl Ord for FmtSpan
impl Ord for GeneralizedTime
impl Ord for Greater
impl Ord for HeaderValue
impl Ord for HttpDate
impl Ord for Hyphenated
impl Ord for Id
impl Ord for IdleTimeout
impl Ord for InlinableString
impl Ord for std::time::Instant
impl Ord for tokio::time::instant::Instant
impl Ord for Interest
impl Ord for InternalString
impl Ord for IpAddr
impl Ord for Ipv4Addr
impl Ord for Ipv6Addr
impl Ord for Ipv6MulticastScope
impl Ord for Key
impl Ord for Less
impl Ord for log::Level
impl Ord for rocket::trace::Level
impl Ord for log::LevelFilter
impl Ord for rocket::trace::LevelFilter
impl Ord for LinesCodec
impl Ord for LittleEndian
impl Ord for Location<'_>
impl Ord for Method
impl Ord for Mime
impl Ord for Month
impl Ord for NonNilUuid
impl Ord for Offset
impl Ord for OffsetDateTime
impl Ord for Order
impl Ord for Ordering
impl Ord for OsStr
impl Ord for OsString
impl Ord for PacketDecodeError
impl Ord for Path
impl Ord for PathBuf
impl Ord for PhantomPinned
impl Ord for PlainDateTime
impl Ord for PrefixComponent<'_>
impl Ord for Profile
impl Ord for Quirk
impl Ord for RawStr
impl Ord for RawStrBuf
impl Ord for ReadError
impl Ord for ReadableError
impl Ord for Ready
impl Ord for ReasonPhrase
impl Ord for SendDatagramError
impl Ord for Side
impl Ord for SigId
impl Ord for Sign
impl Ord for SignedDuration
impl Ord for Simple
impl Ord for SocketAddr
impl Ord for SocketAddrV4
impl Ord for SocketAddrV6
impl Ord for Status
impl Ord for StatusCode
impl Ord for h3::proto::stream::StreamId
impl Ord for quinn_proto::StreamId
impl Ord for String
impl Ord for Style
impl Ord for SystemTime
impl Ord for Tag
impl Ord for toml_datetime::datetime::Time
impl Ord for time::time::Time
impl Ord for Timespec
impl Ord for Timestamp
impl Ord for Token
impl Ord for TypeId
impl Ord for UTerm
impl Ord for Uncased<'_>
impl Ord for UncasedStr
impl Ord for UnixTime
impl Ord for Urn
impl Ord for UtcDateTime
impl Ord for UtcOffset
impl Ord for UtcTime
impl Ord for Uuid
impl Ord for VarInt
impl Ord for VariantId
impl Ord for Version
impl Ord for WriteError
impl Ord for Z0
impl Ord for bool
impl Ord for char
impl Ord for i8
impl Ord for i16
impl Ord for i32
impl Ord for i64
impl Ord for i128
impl Ord for isize
1.0.0 (const: unstable) · Source§impl Ord for str
Implements ordering of strings.
impl Ord for str
Implements ordering of strings.
Strings are ordered lexicographically by their byte values. This orders 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. Sorting strings according to
culturally-accepted standards requires locale-specific data that is outside the scope of
the str type.
impl Ord for u8
impl Ord for u16
impl Ord for u32
impl Ord for u64
impl Ord for u128
impl Ord for usize
impl<'a> Ord for rmp::decode::bytes::Bytes<'a>
impl<'a> Ord for Component<'a>
impl<'a> Ord for LocalName<'a>
impl<'a> Ord for Metadata<'a>
impl<'a> Ord for MetadataBuilder<'a>
impl<'a> Ord for Name<'a>
impl<'a> Ord for Namespace<'a>
impl<'a> Ord for PhantomContravariantLifetime<'a>
impl<'a> Ord for PhantomCovariantLifetime<'a>
impl<'a> Ord for PhantomInvariantLifetime<'a>
impl<'a> Ord for std::path::Prefix<'a>
impl<'a> Ord for quick_xml::name::Prefix<'a>
impl<'a> Ord for PrefixDeclaration<'a>
impl<'a> Ord for QName<'a>
impl<'i> Ord for BytesCData<'i>
impl<'i> Ord for BytesDecl<'i>
impl<'i> Ord for BytesEnd<'i>
impl<'i> Ord for BytesPI<'i>
impl<'i> Ord for BytesRef<'i>
impl<'i> Ord for BytesStart<'i>
impl<'i> Ord for BytesText<'i>
impl<'i> Ord for Event<'i>
impl<'k> Ord for KeyMut<'k>
impl<'s, T> Ord for SliceVec<'s, T>where
T: Ord,
impl<'s> Ord for TomlKey<'s>
impl<'s> Ord for TomlString<'s>
impl<A, B> Ord for figment::value::magic::Either<A, B>
impl<A> Ord for &A
impl<A> Ord for &mut A
impl<A> Ord for ArrayVec<A>
impl<A> Ord for SmallVec<A>
impl<A> Ord for TinyVec<A>
impl<B> Ord for Cow<'_, B>
impl<Dyn> Ord for DynMetadata<Dyn>where
Dyn: ?Sized,
impl<F> Ord for Fwhere
F: FnPtr,
impl<I> Ord for LocatingSlice<I>where
I: Ord,
impl<I> Ord for Partial<I>where
I: Ord,
impl<K, V, A> Ord for BTreeMap<K, V, A>
impl<K, V> Ord for indexmap::map::slice::Slice<K, V>
impl<L, R> Ord for either::Either<L, R>
impl<O> Ord for I16<O>where
O: ByteOrder,
impl<O> Ord for I32<O>where
O: ByteOrder,
impl<O> Ord for I64<O>where
O: ByteOrder,
impl<O> Ord for I128<O>where
O: ByteOrder,
impl<O> Ord for Isize<O>where
O: ByteOrder,
impl<O> Ord for U16<O>where
O: ByteOrder,
impl<O> Ord for U32<O>where
O: ByteOrder,
impl<O> Ord for U64<O>where
O: ByteOrder,
impl<O> Ord for U128<O>where
O: ByteOrder,
impl<O> Ord for Usize<O>where
O: ByteOrder,
impl<Ptr> Ord for Pin<Ptr>
impl<S: Ord, E: Ord, F: Ord> Ord for Outcome<S, E, F>
impl<Storage> Ord for __BindgenBitfieldUnit<Storage>where
Storage: Ord,
impl<T, A> Ord for Arc<T, A>
impl<T, A> Ord for BTreeSet<T, A>where
T: Ord,
A: AllocatorClone,
impl<T, A> Ord for Box<T, A>
impl<T, A> Ord for LinkedList<T, A>
impl<T, A> Ord for Rc<T, A>
impl<T, A> Ord for UniqueArc<T, A>
impl<T, A> Ord for UniqueRc<T, A>
impl<T, A> Ord for Vec<T, A>
Implements ordering of vectors, lexicographically.
impl<T, A> Ord for VecDeque<T, A>
impl<T, B> Ord for Ref<B, T>
impl<T, E> Ord for Result<T, E>
impl<T, N> Ord for GenericArray<T, N>where
T: Ord,
N: ArrayLength<T>,
impl<T, S> Ord for Checkpoint<T, S>where
T: Ord,
impl<T, const N: usize> Ord for Simd<T, N>where
T: SimdElement + Ord,
Lexicographic order. For the SIMD elementwise minimum and maximum, use simd_min and simd_max instead.
impl<T, const N: usize> Ord for [T; N]where
T: Ord,
Implements comparison of arrays lexicographically.
impl<T, const VARIANT: u32, const FIELD: u32> Ord for FieldRepresentingType<T, VARIANT, FIELD>where
T: ?Sized,
impl<T: Ord + Send + Sync + 'static> Ord for State<T>
impl<T: Ord, const COMPACT: bool> Ord for MsgPack<T, COMPACT>
msgpack only.impl<T: Ord> Ord for Form<T>
impl<T: Ord> Ord for Json<T>
json only.impl<T: Ord> Ord for Lenient<T>
impl<T: Ord> Ord for Strict<T>
impl<T: Ord> Ord for Xml<T>
xml only.impl<T> Ord for (T₁, T₂, …, Tₙ)where
T: Ord,
This trait is implemented for tuples up to twelve items long.
impl<T> Ord for *const Twhere
T: ?Sized,
For thin pointers, comparison is by address, as produced by the <*const T>::addr method.
impl<T> Ord for *mut Twhere
T: ?Sized,
For thin pointers, comparison is by address, as produced by the <*mut T>::addr method.
impl<T> Ord for AllowStdIo<T>where
T: Ord,
impl<T> Ord for Attr<T>where
T: Ord,
impl<T> Ord for Cell<T>
impl<T> Ord for DiscriminantOrd<T>
impl<T> Ord for ManuallyDrop<T>
impl<T> Ord for NonNull<T>where
T: ?Sized,
impl<T> Ord for NonZero<T>where
T: ZeroablePrimitive + Ord,
impl<T> Ord for Option<T>where
T: Ord,
impl<T> Ord for PhantomContravariant<T>where
T: ?Sized,
impl<T> Ord for PhantomCovariant<T>where
T: ?Sized,
impl<T> Ord for PhantomData<T>where
T: ?Sized,
impl<T> Ord for PhantomInvariant<T>where
T: ?Sized,
impl<T> Ord for Poll<T>where
T: Ord,
impl<T> Ord for ReadOnly<T>
impl<T> Ord for RefCell<T>
impl<T> Ord for Reverse<T>where
T: Ord,
impl<T> Ord for Saturating<T>where
T: Ord,
impl<T> Ord for indexmap::set::slice::Slice<T>where
T: Ord,
impl<T> Ord for Spanned<T>where
T: Ord,
impl<T> Ord for SyncView<T>
impl<T> Ord for Unalign<T>
impl<T> Ord for Wrapping<T>where
T: Ord,
impl<T> Ord for [T]where
T: Ord,
Implements comparison of slices lexicographically.