]>
Commit | Line | Data |
---|---|---|
f2b60f7d | 1 | //! Utilities for comparing and ordering values. |
1a4d82fc | 2 | //! |
f2b60f7d | 3 | //! This module contains various tools for comparing and ordering values. In |
0731742a | 4 | //! summary: |
54a0048b | 5 | //! |
0731742a XL |
6 | //! * [`Eq`] and [`PartialEq`] are traits that allow you to define total and |
7 | //! partial equality between values, respectively. Implementing them overloads | |
8 | //! the `==` and `!=` operators. | |
9 | //! * [`Ord`] and [`PartialOrd`] are traits that allow you to define total and | |
10 | //! partial orderings between values, respectively. Implementing them overloads | |
11 | //! the `<`, `<=`, `>`, and `>=` operators. | |
e1599b0c XL |
12 | //! * [`Ordering`] is an enum returned by the main functions of [`Ord`] and |
13 | //! [`PartialOrd`], and describes an ordering. | |
14 | //! * [`Reverse`] is a struct that allows you to easily reverse an ordering. | |
15 | //! * [`max`] and [`min`] are functions that build off of [`Ord`] and allow you | |
16 | //! to find the maximum or minimum of two values. | |
54a0048b | 17 | //! |
0731742a | 18 | //! For more details, see the respective documentation of each item in the list. |
e1599b0c | 19 | //! |
3dfed10e XL |
20 | //! [`max`]: Ord::max |
21 | //! [`min`]: Ord::min | |
1a4d82fc | 22 | |
85aaf69f | 23 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 24 | |
064997fb | 25 | use crate::marker::Destruct; |
f2b60f7d | 26 | use crate::marker::StructuralPartialEq; |
064997fb | 27 | |
1a4d82fc JJ |
28 | use self::Ordering::*; |
29 | ||
62682a34 | 30 | /// Trait for equality comparisons which are [partial equivalence |
3dfed10e | 31 | /// relations](https://en.wikipedia.org/wiki/Partial_equivalence_relation). |
1a4d82fc | 32 | /// |
136023e0 XL |
33 | /// `x.eq(y)` can also be written `x == y`, and `x.ne(y)` can be written `x != y`. |
34 | /// We use the easier-to-read infix notation in the remainder of this documentation. | |
35 | /// | |
62682a34 | 36 | /// This trait allows for partial equality, for types that do not have a full |
9fa01778 | 37 | /// equivalence relation. For example, in floating point numbers `NaN != NaN`, |
5869c6ff | 38 | /// so floating point types implement `PartialEq` but not [`trait@Eq`]. |
1a4d82fc | 39 | /// |
136023e0 XL |
40 | /// Implementations must ensure that `eq` and `ne` are consistent with each other: |
41 | /// | |
f2b60f7d FG |
42 | /// - `a != b` if and only if `!(a == b)`. |
43 | /// | |
44 | /// The default implementation of `ne` provides this consistency and is almost | |
45 | /// always sufficient. It should not be overridden without very good reason. | |
136023e0 XL |
46 | /// |
47 | /// If [`PartialOrd`] or [`Ord`] are also implemented for `Self` and `Rhs`, their methods must also | |
48 | /// be consistent with `PartialEq` (see the documentation of those traits for the exact | |
49 | /// requirements). It's easy to accidentally make them disagree by deriving some of the traits and | |
50 | /// manually implementing others. | |
51 | /// | |
52 | /// The equality relation `==` must satisfy the following conditions | |
53 | /// (for all `a`, `b`, `c` of type `A`, `B`, `C`): | |
1a4d82fc | 54 | /// |
5869c6ff XL |
55 | /// - **Symmetric**: if `A: PartialEq<B>` and `B: PartialEq<A>`, then **`a == b` |
56 | /// implies `b == a`**; and | |
1a4d82fc | 57 | /// |
5869c6ff XL |
58 | /// - **Transitive**: if `A: PartialEq<B>` and `B: PartialEq<C>` and `A: |
59 | /// PartialEq<C>`, then **`a == b` and `b == c` implies `a == c`**. | |
60 | /// | |
61 | /// Note that the `B: PartialEq<A>` (symmetric) and `A: PartialEq<C>` | |
62 | /// (transitive) impls are not forced to exist, but these requirements apply | |
63 | /// whenever they do exist. | |
1a4d82fc | 64 | /// |
3157f602 XL |
65 | /// ## Derivable |
66 | /// | |
67 | /// This trait can be used with `#[derive]`. When `derive`d on structs, two | |
68 | /// instances are equal if all fields are equal, and not equal if any fields | |
923072b8 FG |
69 | /// are not equal. When `derive`d on enums, two instances are equal if they |
70 | /// are the same variant and all fields are equal. | |
3157f602 XL |
71 | /// |
72 | /// ## How can I implement `PartialEq`? | |
73 | /// | |
3157f602 XL |
74 | /// An example implementation for a domain in which two books are considered |
75 | /// the same book if their ISBN matches, even if the formats differ: | |
76 | /// | |
77 | /// ``` | |
b7449926 XL |
78 | /// enum BookFormat { |
79 | /// Paperback, | |
80 | /// Hardback, | |
81 | /// Ebook, | |
82 | /// } | |
83 | /// | |
3157f602 XL |
84 | /// struct Book { |
85 | /// isbn: i32, | |
86 | /// format: BookFormat, | |
87 | /// } | |
88 | /// | |
89 | /// impl PartialEq for Book { | |
532ac7d7 | 90 | /// fn eq(&self, other: &Self) -> bool { |
3157f602 XL |
91 | /// self.isbn == other.isbn |
92 | /// } | |
93 | /// } | |
94 | /// | |
95 | /// let b1 = Book { isbn: 3, format: BookFormat::Paperback }; | |
96 | /// let b2 = Book { isbn: 3, format: BookFormat::Ebook }; | |
97 | /// let b3 = Book { isbn: 10, format: BookFormat::Paperback }; | |
98 | /// | |
99 | /// assert!(b1 == b2); | |
100 | /// assert!(b1 != b3); | |
101 | /// ``` | |
54a0048b | 102 | /// |
b7449926 XL |
103 | /// ## How can I compare two different types? |
104 | /// | |
105 | /// The type you can compare with is controlled by `PartialEq`'s type parameter. | |
106 | /// For example, let's tweak our previous code a bit: | |
107 | /// | |
108 | /// ``` | |
9fa01778 XL |
109 | /// // The derive implements <BookFormat> == <BookFormat> comparisons |
110 | /// #[derive(PartialEq)] | |
b7449926 XL |
111 | /// enum BookFormat { |
112 | /// Paperback, | |
113 | /// Hardback, | |
114 | /// Ebook, | |
115 | /// } | |
116 | /// | |
117 | /// struct Book { | |
118 | /// isbn: i32, | |
119 | /// format: BookFormat, | |
120 | /// } | |
121 | /// | |
9fa01778 | 122 | /// // Implement <Book> == <BookFormat> comparisons |
b7449926 XL |
123 | /// impl PartialEq<BookFormat> for Book { |
124 | /// fn eq(&self, other: &BookFormat) -> bool { | |
9fa01778 XL |
125 | /// self.format == *other |
126 | /// } | |
127 | /// } | |
128 | /// | |
129 | /// // Implement <BookFormat> == <Book> comparisons | |
130 | /// impl PartialEq<Book> for BookFormat { | |
131 | /// fn eq(&self, other: &Book) -> bool { | |
132 | /// *self == other.format | |
b7449926 XL |
133 | /// } |
134 | /// } | |
135 | /// | |
136 | /// let b1 = Book { isbn: 3, format: BookFormat::Paperback }; | |
137 | /// | |
138 | /// assert!(b1 == BookFormat::Paperback); | |
9fa01778 | 139 | /// assert!(BookFormat::Ebook != b1); |
b7449926 XL |
140 | /// ``` |
141 | /// | |
142 | /// By changing `impl PartialEq for Book` to `impl PartialEq<BookFormat> for Book`, | |
9fa01778 | 143 | /// we allow `BookFormat`s to be compared with `Book`s. |
b7449926 | 144 | /// |
60c5eb7d XL |
145 | /// A comparison like the one above, which ignores some fields of the struct, |
146 | /// can be dangerous. It can easily lead to an unintended violation of the | |
147 | /// requirements for a partial equivalence relation. For example, if we kept | |
148 | /// the above implementation of `PartialEq<Book>` for `BookFormat` and added an | |
149 | /// implementation of `PartialEq<Book>` for `Book` (either via a `#[derive]` or | |
150 | /// via the manual implementation from the first example) then the result would | |
151 | /// violate transitivity: | |
152 | /// | |
153 | /// ```should_panic | |
9fa01778 | 154 | /// #[derive(PartialEq)] |
b7449926 XL |
155 | /// enum BookFormat { |
156 | /// Paperback, | |
157 | /// Hardback, | |
158 | /// Ebook, | |
159 | /// } | |
160 | /// | |
60c5eb7d | 161 | /// #[derive(PartialEq)] |
b7449926 XL |
162 | /// struct Book { |
163 | /// isbn: i32, | |
164 | /// format: BookFormat, | |
165 | /// } | |
166 | /// | |
167 | /// impl PartialEq<BookFormat> for Book { | |
168 | /// fn eq(&self, other: &BookFormat) -> bool { | |
9fa01778 XL |
169 | /// self.format == *other |
170 | /// } | |
171 | /// } | |
172 | /// | |
173 | /// impl PartialEq<Book> for BookFormat { | |
174 | /// fn eq(&self, other: &Book) -> bool { | |
175 | /// *self == other.format | |
b7449926 XL |
176 | /// } |
177 | /// } | |
178 | /// | |
60c5eb7d XL |
179 | /// fn main() { |
180 | /// let b1 = Book { isbn: 1, format: BookFormat::Paperback }; | |
181 | /// let b2 = Book { isbn: 2, format: BookFormat::Paperback }; | |
b7449926 | 182 | /// |
60c5eb7d XL |
183 | /// assert!(b1 == BookFormat::Paperback); |
184 | /// assert!(BookFormat::Paperback == b2); | |
b7449926 | 185 | /// |
60c5eb7d XL |
186 | /// // The following should hold by transitivity but doesn't. |
187 | /// assert!(b1 == b2); // <-- PANICS | |
188 | /// } | |
b7449926 XL |
189 | /// ``` |
190 | /// | |
54a0048b SL |
191 | /// # Examples |
192 | /// | |
193 | /// ``` | |
194 | /// let x: u32 = 0; | |
195 | /// let y: u32 = 1; | |
196 | /// | |
197 | /// assert_eq!(x == y, false); | |
198 | /// assert_eq!(x.eq(&y), false); | |
199 | /// ``` | |
74b04a01 XL |
200 | /// |
201 | /// [`eq`]: PartialEq::eq | |
202 | /// [`ne`]: PartialEq::ne | |
d9579d0f | 203 | #[lang = "eq"] |
85aaf69f | 204 | #[stable(feature = "rust1", since = "1.0.0")] |
83c7162d XL |
205 | #[doc(alias = "==")] |
206 | #[doc(alias = "!=")] | |
5099ac24 FG |
207 | #[cfg_attr( |
208 | bootstrap, | |
209 | rustc_on_unimplemented( | |
210 | message = "can't compare `{Self}` with `{Rhs}`", | |
211 | label = "no implementation for `{Self} == {Rhs}`" | |
212 | ) | |
213 | )] | |
214 | #[cfg_attr( | |
215 | not(bootstrap), | |
216 | rustc_on_unimplemented( | |
217 | message = "can't compare `{Self}` with `{Rhs}`", | |
218 | label = "no implementation for `{Self} == {Rhs}`", | |
219 | append_const_msg, | |
220 | ) | |
8faf50e0 | 221 | )] |
064997fb | 222 | #[const_trait] |
c295e0f8 | 223 | #[rustc_diagnostic_item = "PartialEq"] |
1a4d82fc | 224 | pub trait PartialEq<Rhs: ?Sized = Self> { |
62682a34 SL |
225 | /// This method tests for `self` and `other` values to be equal, and is used |
226 | /// by `==`. | |
3b2f2976 | 227 | #[must_use] |
85aaf69f | 228 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
229 | fn eq(&self, other: &Rhs) -> bool; |
230 | ||
f2b60f7d FG |
231 | /// This method tests for `!=`. The default implementation is almost always |
232 | /// sufficient, and should not be overridden without very good reason. | |
1a4d82fc | 233 | #[inline] |
3b2f2976 | 234 | #[must_use] |
85aaf69f | 235 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
236 | fn ne(&self, other: &Rhs) -> bool { |
237 | !self.eq(other) | |
238 | } | |
1a4d82fc JJ |
239 | } |
240 | ||
416331ca | 241 | /// Derive macro generating an impl of the trait `PartialEq`. |
416331ca | 242 | #[rustc_builtin_macro] |
416331ca | 243 | #[stable(feature = "builtin_macro_prelude", since = "1.38.0")] |
e74abb32 | 244 | #[allow_internal_unstable(core_intrinsics, structural_match)] |
dfeec247 XL |
245 | pub macro PartialEq($item:item) { |
246 | /* compiler built-in */ | |
247 | } | |
416331ca | 248 | |
1a4d82fc JJ |
249 | /// Trait for equality comparisons which are [equivalence relations]( |
250 | /// https://en.wikipedia.org/wiki/Equivalence_relation). | |
251 | /// | |
85aaf69f SL |
252 | /// This means, that in addition to `a == b` and `a != b` being strict inverses, the equality must |
253 | /// be (for all `a`, `b` and `c`): | |
1a4d82fc JJ |
254 | /// |
255 | /// - reflexive: `a == a`; | |
256 | /// - symmetric: `a == b` implies `b == a`; and | |
257 | /// - transitive: `a == b` and `b == c` implies `a == c`. | |
85aaf69f SL |
258 | /// |
259 | /// This property cannot be checked by the compiler, and therefore `Eq` implies | |
74b04a01 | 260 | /// [`PartialEq`], and has no extra methods. |
92a42be0 | 261 | /// |
3157f602 XL |
262 | /// ## Derivable |
263 | /// | |
264 | /// This trait can be used with `#[derive]`. When `derive`d, because `Eq` has | |
265 | /// no extra methods, it is only informing the compiler that this is an | |
266 | /// equivalence relation rather than a partial equivalence relation. Note that | |
9e0c209e | 267 | /// the `derive` strategy requires all fields are `Eq`, which isn't |
3157f602 XL |
268 | /// always desired. |
269 | /// | |
270 | /// ## How can I implement `Eq`? | |
271 | /// | |
272 | /// If you cannot use the `derive` strategy, specify that your type implements | |
273 | /// `Eq`, which has no methods: | |
274 | /// | |
275 | /// ``` | |
276 | /// enum BookFormat { Paperback, Hardback, Ebook } | |
277 | /// struct Book { | |
278 | /// isbn: i32, | |
279 | /// format: BookFormat, | |
280 | /// } | |
281 | /// impl PartialEq for Book { | |
532ac7d7 | 282 | /// fn eq(&self, other: &Self) -> bool { |
3157f602 XL |
283 | /// self.isbn == other.isbn |
284 | /// } | |
285 | /// } | |
286 | /// impl Eq for Book {} | |
287 | /// ``` | |
83c7162d XL |
288 | #[doc(alias = "==")] |
289 | #[doc(alias = "!=")] | |
85aaf69f | 290 | #[stable(feature = "rust1", since = "1.0.0")] |
c295e0f8 | 291 | #[rustc_diagnostic_item = "Eq"] |
1a4d82fc | 292 | pub trait Eq: PartialEq<Self> { |
ea8adc8c XL |
293 | // this method is used solely by #[deriving] to assert |
294 | // that every component of a type implements #[deriving] | |
1a4d82fc JJ |
295 | // itself, the current deriving infrastructure means doing this |
296 | // assertion without using a method on this trait is nearly | |
297 | // impossible. | |
298 | // | |
299 | // This should never be implemented by hand. | |
300 | #[doc(hidden)] | |
17df50a5 | 301 | #[no_coverage] // rust-lang/rust#84605 |
3b2f2976 | 302 | #[inline] |
85aaf69f | 303 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
304 | fn assert_receiver_is_total_eq(&self) {} |
305 | } | |
306 | ||
416331ca | 307 | /// Derive macro generating an impl of the trait `Eq`. |
416331ca | 308 | #[rustc_builtin_macro] |
416331ca | 309 | #[stable(feature = "builtin_macro_prelude", since = "1.38.0")] |
cdc7bbd5 | 310 | #[allow_internal_unstable(core_intrinsics, derive_eq, structural_match, no_coverage)] |
dfeec247 XL |
311 | pub macro Eq($item:item) { |
312 | /* compiler built-in */ | |
313 | } | |
416331ca | 314 | |
9e0c209e SL |
315 | // FIXME: this struct is used solely by #[derive] to |
316 | // assert that every component of a type implements Eq. | |
317 | // | |
318 | // This struct should never appear in user code. | |
319 | #[doc(hidden)] | |
320 | #[allow(missing_debug_implementations)] | |
dfeec247 XL |
321 | #[unstable(feature = "derive_eq", reason = "deriving hack, should not be public", issue = "none")] |
322 | pub struct AssertParamIsEq<T: Eq + ?Sized> { | |
323 | _field: crate::marker::PhantomData<T>, | |
324 | } | |
9e0c209e | 325 | |
85aaf69f SL |
326 | /// An `Ordering` is the result of a comparison between two values. |
327 | /// | |
328 | /// # Examples | |
329 | /// | |
330 | /// ``` | |
331 | /// use std::cmp::Ordering; | |
332 | /// | |
333 | /// let result = 1.cmp(&2); | |
334 | /// assert_eq!(Ordering::Less, result); | |
335 | /// | |
336 | /// let result = 1.cmp(&1); | |
337 | /// assert_eq!(Ordering::Equal, result); | |
338 | /// | |
339 | /// let result = 2.cmp(&1); | |
340 | /// assert_eq!(Ordering::Greater, result); | |
341 | /// ``` | |
f2b60f7d | 342 | #[derive(Clone, Copy, Eq, Debug, Hash)] |
85aaf69f | 343 | #[stable(feature = "rust1", since = "1.0.0")] |
c295e0f8 | 344 | #[repr(i8)] |
1a4d82fc | 345 | pub enum Ordering { |
48663c56 | 346 | /// An ordering where a compared value is less than another. |
85aaf69f SL |
347 | #[stable(feature = "rust1", since = "1.0.0")] |
348 | Less = -1, | |
48663c56 | 349 | /// An ordering where a compared value is equal to another. |
85aaf69f SL |
350 | #[stable(feature = "rust1", since = "1.0.0")] |
351 | Equal = 0, | |
48663c56 | 352 | /// An ordering where a compared value is greater than another. |
85aaf69f SL |
353 | #[stable(feature = "rust1", since = "1.0.0")] |
354 | Greater = 1, | |
1a4d82fc JJ |
355 | } |
356 | ||
357 | impl Ordering { | |
fc512014 XL |
358 | /// Returns `true` if the ordering is the `Equal` variant. |
359 | /// | |
360 | /// # Examples | |
361 | /// | |
362 | /// ``` | |
fc512014 XL |
363 | /// use std::cmp::Ordering; |
364 | /// | |
365 | /// assert_eq!(Ordering::Less.is_eq(), false); | |
366 | /// assert_eq!(Ordering::Equal.is_eq(), true); | |
367 | /// assert_eq!(Ordering::Greater.is_eq(), false); | |
368 | /// ``` | |
369 | #[inline] | |
370 | #[must_use] | |
cdc7bbd5 XL |
371 | #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] |
372 | #[stable(feature = "ordering_helpers", since = "1.53.0")] | |
fc512014 XL |
373 | pub const fn is_eq(self) -> bool { |
374 | matches!(self, Equal) | |
375 | } | |
376 | ||
377 | /// Returns `true` if the ordering is not the `Equal` variant. | |
378 | /// | |
379 | /// # Examples | |
380 | /// | |
381 | /// ``` | |
fc512014 XL |
382 | /// use std::cmp::Ordering; |
383 | /// | |
384 | /// assert_eq!(Ordering::Less.is_ne(), true); | |
385 | /// assert_eq!(Ordering::Equal.is_ne(), false); | |
386 | /// assert_eq!(Ordering::Greater.is_ne(), true); | |
387 | /// ``` | |
388 | #[inline] | |
389 | #[must_use] | |
cdc7bbd5 XL |
390 | #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] |
391 | #[stable(feature = "ordering_helpers", since = "1.53.0")] | |
fc512014 XL |
392 | pub const fn is_ne(self) -> bool { |
393 | !matches!(self, Equal) | |
394 | } | |
395 | ||
396 | /// Returns `true` if the ordering is the `Less` variant. | |
397 | /// | |
398 | /// # Examples | |
399 | /// | |
400 | /// ``` | |
fc512014 XL |
401 | /// use std::cmp::Ordering; |
402 | /// | |
403 | /// assert_eq!(Ordering::Less.is_lt(), true); | |
404 | /// assert_eq!(Ordering::Equal.is_lt(), false); | |
405 | /// assert_eq!(Ordering::Greater.is_lt(), false); | |
406 | /// ``` | |
407 | #[inline] | |
408 | #[must_use] | |
cdc7bbd5 XL |
409 | #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] |
410 | #[stable(feature = "ordering_helpers", since = "1.53.0")] | |
fc512014 XL |
411 | pub const fn is_lt(self) -> bool { |
412 | matches!(self, Less) | |
413 | } | |
414 | ||
415 | /// Returns `true` if the ordering is the `Greater` variant. | |
416 | /// | |
417 | /// # Examples | |
418 | /// | |
419 | /// ``` | |
fc512014 XL |
420 | /// use std::cmp::Ordering; |
421 | /// | |
422 | /// assert_eq!(Ordering::Less.is_gt(), false); | |
423 | /// assert_eq!(Ordering::Equal.is_gt(), false); | |
424 | /// assert_eq!(Ordering::Greater.is_gt(), true); | |
425 | /// ``` | |
426 | #[inline] | |
427 | #[must_use] | |
cdc7bbd5 XL |
428 | #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] |
429 | #[stable(feature = "ordering_helpers", since = "1.53.0")] | |
fc512014 XL |
430 | pub const fn is_gt(self) -> bool { |
431 | matches!(self, Greater) | |
432 | } | |
433 | ||
434 | /// Returns `true` if the ordering is either the `Less` or `Equal` variant. | |
435 | /// | |
436 | /// # Examples | |
437 | /// | |
438 | /// ``` | |
fc512014 XL |
439 | /// use std::cmp::Ordering; |
440 | /// | |
441 | /// assert_eq!(Ordering::Less.is_le(), true); | |
442 | /// assert_eq!(Ordering::Equal.is_le(), true); | |
443 | /// assert_eq!(Ordering::Greater.is_le(), false); | |
444 | /// ``` | |
445 | #[inline] | |
446 | #[must_use] | |
cdc7bbd5 XL |
447 | #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] |
448 | #[stable(feature = "ordering_helpers", since = "1.53.0")] | |
fc512014 XL |
449 | pub const fn is_le(self) -> bool { |
450 | !matches!(self, Greater) | |
451 | } | |
452 | ||
453 | /// Returns `true` if the ordering is either the `Greater` or `Equal` variant. | |
454 | /// | |
455 | /// # Examples | |
456 | /// | |
457 | /// ``` | |
fc512014 XL |
458 | /// use std::cmp::Ordering; |
459 | /// | |
460 | /// assert_eq!(Ordering::Less.is_ge(), false); | |
461 | /// assert_eq!(Ordering::Equal.is_ge(), true); | |
462 | /// assert_eq!(Ordering::Greater.is_ge(), true); | |
463 | /// ``` | |
464 | #[inline] | |
465 | #[must_use] | |
cdc7bbd5 XL |
466 | #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] |
467 | #[stable(feature = "ordering_helpers", since = "1.53.0")] | |
fc512014 XL |
468 | pub const fn is_ge(self) -> bool { |
469 | !matches!(self, Less) | |
470 | } | |
471 | ||
cc61c64b | 472 | /// Reverses the `Ordering`. |
1a4d82fc | 473 | /// |
85aaf69f SL |
474 | /// * `Less` becomes `Greater`. |
475 | /// * `Greater` becomes `Less`. | |
476 | /// * `Equal` becomes `Equal`. | |
1a4d82fc | 477 | /// |
85aaf69f | 478 | /// # Examples |
1a4d82fc | 479 | /// |
85aaf69f | 480 | /// Basic behavior: |
1a4d82fc | 481 | /// |
85aaf69f SL |
482 | /// ``` |
483 | /// use std::cmp::Ordering; | |
484 | /// | |
485 | /// assert_eq!(Ordering::Less.reverse(), Ordering::Greater); | |
486 | /// assert_eq!(Ordering::Equal.reverse(), Ordering::Equal); | |
487 | /// assert_eq!(Ordering::Greater.reverse(), Ordering::Less); | |
488 | /// ``` | |
489 | /// | |
490 | /// This method can be used to reverse a comparison: | |
491 | /// | |
492 | /// ``` | |
416331ca | 493 | /// let data: &mut [_] = &mut [2, 10, 5, 8]; |
1a4d82fc JJ |
494 | /// |
495 | /// // sort the array from largest to smallest. | |
496 | /// data.sort_by(|a, b| a.cmp(b).reverse()); | |
497 | /// | |
85aaf69f | 498 | /// let b: &mut [_] = &mut [10, 8, 5, 2]; |
1a4d82fc JJ |
499 | /// assert!(data == b); |
500 | /// ``` | |
501 | #[inline] | |
74b04a01 | 502 | #[must_use] |
1b1a35ee | 503 | #[rustc_const_stable(feature = "const_ordering", since = "1.48.0")] |
85aaf69f | 504 | #[stable(feature = "rust1", since = "1.0.0")] |
1b1a35ee | 505 | pub const fn reverse(self) -> Ordering { |
7453a54e SL |
506 | match self { |
507 | Less => Greater, | |
508 | Equal => Equal, | |
509 | Greater => Less, | |
1a4d82fc JJ |
510 | } |
511 | } | |
c30ab7b3 SL |
512 | |
513 | /// Chains two orderings. | |
514 | /// | |
515 | /// Returns `self` when it's not `Equal`. Otherwise returns `other`. | |
74b04a01 | 516 | /// |
c30ab7b3 SL |
517 | /// # Examples |
518 | /// | |
519 | /// ``` | |
c30ab7b3 SL |
520 | /// use std::cmp::Ordering; |
521 | /// | |
522 | /// let result = Ordering::Equal.then(Ordering::Less); | |
523 | /// assert_eq!(result, Ordering::Less); | |
524 | /// | |
525 | /// let result = Ordering::Less.then(Ordering::Equal); | |
526 | /// assert_eq!(result, Ordering::Less); | |
527 | /// | |
528 | /// let result = Ordering::Less.then(Ordering::Greater); | |
529 | /// assert_eq!(result, Ordering::Less); | |
530 | /// | |
531 | /// let result = Ordering::Equal.then(Ordering::Equal); | |
532 | /// assert_eq!(result, Ordering::Equal); | |
533 | /// | |
534 | /// let x: (i64, i64, i64) = (1, 2, 7); | |
535 | /// let y: (i64, i64, i64) = (1, 5, 3); | |
536 | /// let result = x.0.cmp(&y.0).then(x.1.cmp(&y.1)).then(x.2.cmp(&y.2)); | |
537 | /// | |
538 | /// assert_eq!(result, Ordering::Less); | |
539 | /// ``` | |
cc61c64b | 540 | #[inline] |
74b04a01 | 541 | #[must_use] |
1b1a35ee | 542 | #[rustc_const_stable(feature = "const_ordering", since = "1.48.0")] |
8bb4bdeb | 543 | #[stable(feature = "ordering_chaining", since = "1.17.0")] |
1b1a35ee | 544 | pub const fn then(self, other: Ordering) -> Ordering { |
c30ab7b3 SL |
545 | match self { |
546 | Equal => other, | |
547 | _ => self, | |
548 | } | |
549 | } | |
550 | ||
551 | /// Chains the ordering with the given function. | |
552 | /// | |
553 | /// Returns `self` when it's not `Equal`. Otherwise calls `f` and returns | |
554 | /// the result. | |
555 | /// | |
556 | /// # Examples | |
557 | /// | |
558 | /// ``` | |
c30ab7b3 SL |
559 | /// use std::cmp::Ordering; |
560 | /// | |
561 | /// let result = Ordering::Equal.then_with(|| Ordering::Less); | |
562 | /// assert_eq!(result, Ordering::Less); | |
563 | /// | |
564 | /// let result = Ordering::Less.then_with(|| Ordering::Equal); | |
565 | /// assert_eq!(result, Ordering::Less); | |
566 | /// | |
567 | /// let result = Ordering::Less.then_with(|| Ordering::Greater); | |
568 | /// assert_eq!(result, Ordering::Less); | |
569 | /// | |
570 | /// let result = Ordering::Equal.then_with(|| Ordering::Equal); | |
571 | /// assert_eq!(result, Ordering::Equal); | |
572 | /// | |
573 | /// let x: (i64, i64, i64) = (1, 2, 7); | |
5869c6ff | 574 | /// let y: (i64, i64, i64) = (1, 5, 3); |
c30ab7b3 SL |
575 | /// let result = x.0.cmp(&y.0).then_with(|| x.1.cmp(&y.1)).then_with(|| x.2.cmp(&y.2)); |
576 | /// | |
577 | /// assert_eq!(result, Ordering::Less); | |
578 | /// ``` | |
cc61c64b | 579 | #[inline] |
74b04a01 | 580 | #[must_use] |
8bb4bdeb | 581 | #[stable(feature = "ordering_chaining", since = "1.17.0")] |
c30ab7b3 SL |
582 | pub fn then_with<F: FnOnce() -> Ordering>(self, f: F) -> Ordering { |
583 | match self { | |
584 | Equal => f(), | |
585 | _ => self, | |
586 | } | |
587 | } | |
1a4d82fc JJ |
588 | } |
589 | ||
cc61c64b XL |
590 | /// A helper struct for reverse ordering. |
591 | /// | |
74b04a01 | 592 | /// This struct is a helper to be used with functions like [`Vec::sort_by_key`] and |
cc61c64b XL |
593 | /// can be used to reverse order a part of a key. |
594 | /// | |
74b04a01 XL |
595 | /// [`Vec::sort_by_key`]: ../../std/vec/struct.Vec.html#method.sort_by_key |
596 | /// | |
597 | /// # Examples | |
cc61c64b XL |
598 | /// |
599 | /// ``` | |
cc61c64b XL |
600 | /// use std::cmp::Reverse; |
601 | /// | |
602 | /// let mut v = vec![1, 2, 3, 4, 5, 6]; | |
603 | /// v.sort_by_key(|&num| (num > 3, Reverse(num))); | |
604 | /// assert_eq!(v, vec![3, 2, 1, 6, 5, 4]); | |
605 | /// ``` | |
17df50a5 | 606 | #[derive(PartialEq, Eq, Debug, Copy, Default, Hash)] |
7cac9316 | 607 | #[stable(feature = "reverse_cmp_key", since = "1.19.0")] |
6a06907d | 608 | #[repr(transparent)] |
7cac9316 | 609 | pub struct Reverse<T>(#[stable(feature = "reverse_cmp_key", since = "1.19.0")] pub T); |
cc61c64b | 610 | |
7cac9316 | 611 | #[stable(feature = "reverse_cmp_key", since = "1.19.0")] |
064997fb FG |
612 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
613 | impl<T: ~const PartialOrd> const PartialOrd for Reverse<T> { | |
cc61c64b XL |
614 | #[inline] |
615 | fn partial_cmp(&self, other: &Reverse<T>) -> Option<Ordering> { | |
616 | other.0.partial_cmp(&self.0) | |
617 | } | |
618 | ||
619 | #[inline] | |
dfeec247 XL |
620 | fn lt(&self, other: &Self) -> bool { |
621 | other.0 < self.0 | |
622 | } | |
cc61c64b | 623 | #[inline] |
dfeec247 XL |
624 | fn le(&self, other: &Self) -> bool { |
625 | other.0 <= self.0 | |
626 | } | |
cc61c64b | 627 | #[inline] |
dfeec247 XL |
628 | fn gt(&self, other: &Self) -> bool { |
629 | other.0 > self.0 | |
630 | } | |
60c5eb7d | 631 | #[inline] |
dfeec247 XL |
632 | fn ge(&self, other: &Self) -> bool { |
633 | other.0 >= self.0 | |
634 | } | |
cc61c64b XL |
635 | } |
636 | ||
7cac9316 | 637 | #[stable(feature = "reverse_cmp_key", since = "1.19.0")] |
cc61c64b XL |
638 | impl<T: Ord> Ord for Reverse<T> { |
639 | #[inline] | |
640 | fn cmp(&self, other: &Reverse<T>) -> Ordering { | |
641 | other.0.cmp(&self.0) | |
642 | } | |
643 | } | |
644 | ||
17df50a5 XL |
645 | #[stable(feature = "reverse_cmp_key", since = "1.19.0")] |
646 | impl<T: Clone> Clone for Reverse<T> { | |
647 | #[inline] | |
648 | fn clone(&self) -> Reverse<T> { | |
649 | Reverse(self.0.clone()) | |
650 | } | |
651 | ||
652 | #[inline] | |
653 | fn clone_from(&mut self, other: &Self) { | |
654 | self.0.clone_from(&other.0) | |
655 | } | |
656 | } | |
657 | ||
85aaf69f | 658 | /// Trait for types that form a [total order](https://en.wikipedia.org/wiki/Total_order). |
1a4d82fc | 659 | /// |
136023e0 XL |
660 | /// Implementations must be consistent with the [`PartialOrd`] implementation, and ensure |
661 | /// `max`, `min`, and `clamp` are consistent with `cmp`: | |
662 | /// | |
663 | /// - `partial_cmp(a, b) == Some(cmp(a, b))`. | |
664 | /// - `max(a, b) == max_by(a, b, cmp)` (ensured by the default implementation). | |
665 | /// - `min(a, b) == min_by(a, b, cmp)` (ensured by the default implementation). | |
666 | /// - For `a.clamp(min, max)`, see the [method docs](#method.clamp) | |
667 | /// (ensured by the default implementation). | |
668 | /// | |
669 | /// It's easy to accidentally make `cmp` and `partial_cmp` disagree by | |
670 | /// deriving some of the traits and manually implementing others. | |
671 | /// | |
672 | /// ## Corollaries | |
673 | /// | |
674 | /// From the above and the requirements of `PartialOrd`, it follows that `<` defines a strict total order. | |
675 | /// This means that for all `a`, `b` and `c`: | |
1a4d82fc | 676 | /// |
136023e0 XL |
677 | /// - exactly one of `a < b`, `a == b` or `a > b` is true; and |
678 | /// - `<` is transitive: `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. | |
c1a9b12d | 679 | /// |
3157f602 XL |
680 | /// ## Derivable |
681 | /// | |
5099ac24 FG |
682 | /// This trait can be used with `#[derive]`. |
683 | /// | |
684 | /// When `derive`d on structs, it will produce a | |
685 | /// [lexicographic](https://en.wikipedia.org/wiki/Lexicographic_order) ordering | |
686 | /// based on the top-to-bottom declaration order of the struct's members. | |
687 | /// | |
688 | /// When `derive`d on enums, variants are ordered by their discriminants. | |
689 | /// By default, the discriminant is smallest for variants at the top, and | |
690 | /// largest for variants at the bottom. Here's an example: | |
94222f64 XL |
691 | /// |
692 | /// ``` | |
5099ac24 FG |
693 | /// #[derive(PartialEq, Eq, PartialOrd, Ord)] |
694 | /// enum E { | |
695 | /// Top, | |
696 | /// Bottom, | |
697 | /// } | |
698 | /// | |
699 | /// assert!(E::Top < E::Bottom); | |
700 | /// ``` | |
701 | /// | |
702 | /// However, manually setting the discriminants can override this default | |
703 | /// behavior: | |
704 | /// | |
705 | /// ``` | |
706 | /// #[derive(PartialEq, Eq, PartialOrd, Ord)] | |
707 | /// enum E { | |
708 | /// Top = 2, | |
709 | /// Bottom = 1, | |
94222f64 XL |
710 | /// } |
711 | /// | |
5099ac24 | 712 | /// assert!(E::Bottom < E::Top); |
94222f64 | 713 | /// ``` |
3157f602 | 714 | /// |
29967ef6 XL |
715 | /// ## Lexicographical comparison |
716 | /// | |
717 | /// Lexicographical comparison is an operation with the following properties: | |
718 | /// - Two sequences are compared element by element. | |
719 | /// - The first mismatching element defines which sequence is lexicographically less or greater than the other. | |
720 | /// - If one sequence is a prefix of another, the shorter sequence is lexicographically less than the other. | |
721 | /// - If two sequence have equivalent elements and are of the same length, then the sequences are lexicographically equal. | |
722 | /// - An empty sequence is lexicographically less than any non-empty sequence. | |
723 | /// - Two empty sequences are lexicographically equal. | |
724 | /// | |
3157f602 XL |
725 | /// ## How can I implement `Ord`? |
726 | /// | |
74b04a01 | 727 | /// `Ord` requires that the type also be [`PartialOrd`] and [`Eq`] (which requires [`PartialEq`]). |
3157f602 | 728 | /// |
74b04a01 XL |
729 | /// Then you must define an implementation for [`cmp`]. You may find it useful to use |
730 | /// [`cmp`] on your type's fields. | |
3157f602 XL |
731 | /// |
732 | /// Here's an example where you want to sort people by height only, disregarding `id` | |
733 | /// and `name`: | |
734 | /// | |
735 | /// ``` | |
736 | /// use std::cmp::Ordering; | |
737 | /// | |
738 | /// #[derive(Eq)] | |
739 | /// struct Person { | |
740 | /// id: u32, | |
741 | /// name: String, | |
742 | /// height: u32, | |
743 | /// } | |
744 | /// | |
745 | /// impl Ord for Person { | |
532ac7d7 | 746 | /// fn cmp(&self, other: &Self) -> Ordering { |
3157f602 XL |
747 | /// self.height.cmp(&other.height) |
748 | /// } | |
749 | /// } | |
750 | /// | |
751 | /// impl PartialOrd for Person { | |
532ac7d7 | 752 | /// fn partial_cmp(&self, other: &Self) -> Option<Ordering> { |
3157f602 XL |
753 | /// Some(self.cmp(other)) |
754 | /// } | |
755 | /// } | |
756 | /// | |
757 | /// impl PartialEq for Person { | |
532ac7d7 | 758 | /// fn eq(&self, other: &Self) -> bool { |
3157f602 XL |
759 | /// self.height == other.height |
760 | /// } | |
761 | /// } | |
762 | /// ``` | |
74b04a01 XL |
763 | /// |
764 | /// [`cmp`]: Ord::cmp | |
83c7162d XL |
765 | #[doc(alias = "<")] |
766 | #[doc(alias = ">")] | |
767 | #[doc(alias = "<=")] | |
768 | #[doc(alias = ">=")] | |
85aaf69f | 769 | #[stable(feature = "rust1", since = "1.0.0")] |
c295e0f8 | 770 | #[rustc_diagnostic_item = "Ord"] |
064997fb | 771 | #[const_trait] |
1a4d82fc | 772 | pub trait Ord: Eq + PartialOrd<Self> { |
74b04a01 | 773 | /// This method returns an [`Ordering`] between `self` and `other`. |
85aaf69f SL |
774 | /// |
775 | /// By convention, `self.cmp(&other)` returns the ordering matching the expression | |
776 | /// `self <operator> other` if true. | |
1a4d82fc | 777 | /// |
85aaf69f | 778 | /// # Examples |
1a4d82fc JJ |
779 | /// |
780 | /// ``` | |
85aaf69f | 781 | /// use std::cmp::Ordering; |
1a4d82fc | 782 | /// |
85aaf69f SL |
783 | /// assert_eq!(5.cmp(&10), Ordering::Less); |
784 | /// assert_eq!(10.cmp(&5), Ordering::Greater); | |
785 | /// assert_eq!(5.cmp(&5), Ordering::Equal); | |
1a4d82fc | 786 | /// ``` |
74b04a01 | 787 | #[must_use] |
85aaf69f | 788 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 789 | fn cmp(&self, other: &Self) -> Ordering; |
041b39d2 XL |
790 | |
791 | /// Compares and returns the maximum of two values. | |
792 | /// | |
793 | /// Returns the second argument if the comparison determines them to be equal. | |
794 | /// | |
795 | /// # Examples | |
796 | /// | |
797 | /// ``` | |
041b39d2 XL |
798 | /// assert_eq!(2, 1.max(2)); |
799 | /// assert_eq!(2, 2.max(2)); | |
800 | /// ``` | |
3b2f2976 | 801 | #[stable(feature = "ord_max_min", since = "1.21.0")] |
b7449926 | 802 | #[inline] |
74b04a01 | 803 | #[must_use] |
041b39d2 | 804 | fn max(self, other: Self) -> Self |
dfeec247 XL |
805 | where |
806 | Self: Sized, | |
064997fb | 807 | Self: ~const Destruct, |
dfeec247 | 808 | { |
064997fb FG |
809 | // HACK(fee1-dead): go back to using `self.max_by(other, Ord::cmp)` |
810 | // when trait methods are allowed to be used when a const closure is | |
811 | // expected. | |
812 | match self.cmp(&other) { | |
813 | Ordering::Less | Ordering::Equal => other, | |
814 | Ordering::Greater => self, | |
815 | } | |
041b39d2 XL |
816 | } |
817 | ||
818 | /// Compares and returns the minimum of two values. | |
819 | /// | |
820 | /// Returns the first argument if the comparison determines them to be equal. | |
821 | /// | |
822 | /// # Examples | |
823 | /// | |
824 | /// ``` | |
041b39d2 XL |
825 | /// assert_eq!(1, 1.min(2)); |
826 | /// assert_eq!(2, 2.min(2)); | |
827 | /// ``` | |
3b2f2976 | 828 | #[stable(feature = "ord_max_min", since = "1.21.0")] |
b7449926 | 829 | #[inline] |
74b04a01 | 830 | #[must_use] |
041b39d2 | 831 | fn min(self, other: Self) -> Self |
dfeec247 XL |
832 | where |
833 | Self: Sized, | |
064997fb | 834 | Self: ~const Destruct, |
dfeec247 | 835 | { |
064997fb FG |
836 | // HACK(fee1-dead): go back to using `self.min_by(other, Ord::cmp)` |
837 | // when trait methods are allowed to be used when a const closure is | |
838 | // expected. | |
839 | match self.cmp(&other) { | |
840 | Ordering::Less | Ordering::Equal => self, | |
841 | Ordering::Greater => other, | |
842 | } | |
041b39d2 | 843 | } |
532ac7d7 XL |
844 | |
845 | /// Restrict a value to a certain interval. | |
846 | /// | |
847 | /// Returns `max` if `self` is greater than `max`, and `min` if `self` is | |
848 | /// less than `min`. Otherwise this returns `self`. | |
849 | /// | |
850 | /// # Panics | |
851 | /// | |
852 | /// Panics if `min > max`. | |
853 | /// | |
854 | /// # Examples | |
855 | /// | |
856 | /// ``` | |
532ac7d7 XL |
857 | /// assert!((-3).clamp(-2, 1) == -2); |
858 | /// assert!(0.clamp(-2, 1) == 0); | |
859 | /// assert!(2.clamp(-2, 1) == 1); | |
860 | /// ``` | |
74b04a01 | 861 | #[must_use] |
fc512014 | 862 | #[stable(feature = "clamp", since = "1.50.0")] |
532ac7d7 | 863 | fn clamp(self, min: Self, max: Self) -> Self |
dfeec247 XL |
864 | where |
865 | Self: Sized, | |
064997fb FG |
866 | Self: ~const Destruct, |
867 | Self: ~const PartialOrd, | |
dfeec247 | 868 | { |
532ac7d7 XL |
869 | assert!(min <= max); |
870 | if self < min { | |
871 | min | |
872 | } else if self > max { | |
873 | max | |
874 | } else { | |
875 | self | |
876 | } | |
877 | } | |
1a4d82fc JJ |
878 | } |
879 | ||
416331ca | 880 | /// Derive macro generating an impl of the trait `Ord`. |
416331ca | 881 | #[rustc_builtin_macro] |
416331ca XL |
882 | #[stable(feature = "builtin_macro_prelude", since = "1.38.0")] |
883 | #[allow_internal_unstable(core_intrinsics)] | |
dfeec247 XL |
884 | pub macro Ord($item:item) { |
885 | /* compiler built-in */ | |
886 | } | |
416331ca | 887 | |
f2b60f7d FG |
888 | #[stable(feature = "rust1", since = "1.0.0")] |
889 | impl StructuralPartialEq for Ordering {} | |
890 | ||
891 | #[stable(feature = "rust1", since = "1.0.0")] | |
892 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] | |
893 | impl const PartialEq for Ordering { | |
894 | #[inline] | |
895 | fn eq(&self, other: &Self) -> bool { | |
896 | (*self as i32).eq(&(*other as i32)) | |
897 | } | |
898 | } | |
899 | ||
85aaf69f | 900 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
901 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
902 | impl const Ord for Ordering { | |
1a4d82fc | 903 | #[inline] |
1a4d82fc | 904 | fn cmp(&self, other: &Ordering) -> Ordering { |
85aaf69f | 905 | (*self as i32).cmp(&(*other as i32)) |
1a4d82fc JJ |
906 | } |
907 | } | |
908 | ||
85aaf69f | 909 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
910 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
911 | impl const PartialOrd for Ordering { | |
1a4d82fc | 912 | #[inline] |
1a4d82fc | 913 | fn partial_cmp(&self, other: &Ordering) -> Option<Ordering> { |
85aaf69f | 914 | (*self as i32).partial_cmp(&(*other as i32)) |
1a4d82fc JJ |
915 | } |
916 | } | |
917 | ||
5099ac24 | 918 | /// Trait for types that form a [partial order](https://en.wikipedia.org/wiki/Partial_order). |
1a4d82fc | 919 | /// |
136023e0 XL |
920 | /// The `lt`, `le`, `gt`, and `ge` methods of this trait can be called using |
921 | /// the `<`, `<=`, `>`, and `>=` operators, respectively. | |
922 | /// | |
5e7ed085 FG |
923 | /// The methods of this trait must be consistent with each other and with those of [`PartialEq`]. |
924 | /// The following conditions must hold: | |
136023e0 | 925 | /// |
5e7ed085 FG |
926 | /// 1. `a == b` if and only if `partial_cmp(a, b) == Some(Equal)`. |
927 | /// 2. `a < b` if and only if `partial_cmp(a, b) == Some(Less)` | |
928 | /// 3. `a > b` if and only if `partial_cmp(a, b) == Some(Greater)` | |
929 | /// 4. `a <= b` if and only if `a < b || a == b` | |
930 | /// 5. `a >= b` if and only if `a > b || a == b` | |
931 | /// 6. `a != b` if and only if `!(a == b)`. | |
932 | /// | |
933 | /// Conditions 2–5 above are ensured by the default implementation. | |
934 | /// Condition 6 is already ensured by [`PartialEq`]. | |
136023e0 XL |
935 | /// |
936 | /// If [`Ord`] is also implemented for `Self` and `Rhs`, it must also be consistent with | |
937 | /// `partial_cmp` (see the documentation of that trait for the exact requirements). It's | |
938 | /// easy to accidentally make them disagree by deriving some of the traits and manually | |
939 | /// implementing others. | |
940 | /// | |
1a4d82fc JJ |
941 | /// The comparison must satisfy, for all `a`, `b` and `c`: |
942 | /// | |
85aaf69f | 943 | /// - transitivity: `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. |
136023e0 | 944 | /// - duality: `a < b` if and only if `b > a`. |
1a4d82fc | 945 | /// |
85aaf69f SL |
946 | /// Note that these requirements mean that the trait itself must be implemented symmetrically and |
947 | /// transitively: if `T: PartialOrd<U>` and `U: PartialOrd<V>` then `U: PartialOrd<T>` and `T: | |
1a4d82fc JJ |
948 | /// PartialOrd<V>`. |
949 | /// | |
136023e0 XL |
950 | /// ## Corollaries |
951 | /// | |
952 | /// The following corollaries follow from the above requirements: | |
953 | /// | |
954 | /// - irreflexivity of `<` and `>`: `!(a < a)`, `!(a > a)` | |
955 | /// - transitivity of `>`: if `a > b` and `b > c` then `a > c` | |
956 | /// - duality of `partial_cmp`: `partial_cmp(a, b) == partial_cmp(b, a).map(Ordering::reverse)` | |
957 | /// | |
3157f602 XL |
958 | /// ## Derivable |
959 | /// | |
5099ac24 FG |
960 | /// This trait can be used with `#[derive]`. |
961 | /// | |
962 | /// When `derive`d on structs, it will produce a | |
963 | /// [lexicographic](https://en.wikipedia.org/wiki/Lexicographic_order) ordering | |
964 | /// based on the top-to-bottom declaration order of the struct's members. | |
965 | /// | |
966 | /// When `derive`d on enums, variants are ordered by their discriminants. | |
967 | /// By default, the discriminant is smallest for variants at the top, and | |
968 | /// largest for variants at the bottom. Here's an example: | |
969 | /// | |
970 | /// ``` | |
971 | /// #[derive(PartialEq, PartialOrd)] | |
972 | /// enum E { | |
973 | /// Top, | |
974 | /// Bottom, | |
975 | /// } | |
976 | /// | |
977 | /// assert!(E::Top < E::Bottom); | |
978 | /// ``` | |
979 | /// | |
980 | /// However, manually setting the discriminants can override this default | |
981 | /// behavior: | |
982 | /// | |
983 | /// ``` | |
984 | /// #[derive(PartialEq, PartialOrd)] | |
985 | /// enum E { | |
986 | /// Top = 2, | |
987 | /// Bottom = 1, | |
988 | /// } | |
989 | /// | |
990 | /// assert!(E::Bottom < E::Top); | |
991 | /// ``` | |
3157f602 | 992 | /// |
32a655c1 | 993 | /// ## How can I implement `PartialOrd`? |
3157f602 | 994 | /// |
74b04a01 | 995 | /// `PartialOrd` only requires implementation of the [`partial_cmp`] method, with the others |
7cac9316 | 996 | /// generated from default implementations. |
1a4d82fc | 997 | /// |
85aaf69f SL |
998 | /// However it remains possible to implement the others separately for types which do not have a |
999 | /// total order. For example, for floating point numbers, `NaN < 0 == false` and `NaN >= 0 == | |
1000 | /// false` (cf. IEEE 754-2008 section 5.11). | |
92a42be0 | 1001 | /// |
74b04a01 | 1002 | /// `PartialOrd` requires your type to be [`PartialEq`]. |
3157f602 | 1003 | /// |
74b04a01 | 1004 | /// If your type is [`Ord`], you can implement [`partial_cmp`] by using [`cmp`]: |
3157f602 XL |
1005 | /// |
1006 | /// ``` | |
1007 | /// use std::cmp::Ordering; | |
1008 | /// | |
1009 | /// #[derive(Eq)] | |
1010 | /// struct Person { | |
1011 | /// id: u32, | |
1012 | /// name: String, | |
1013 | /// height: u32, | |
1014 | /// } | |
1015 | /// | |
1016 | /// impl PartialOrd for Person { | |
1b1a35ee | 1017 | /// fn partial_cmp(&self, other: &Self) -> Option<Ordering> { |
3157f602 XL |
1018 | /// Some(self.cmp(other)) |
1019 | /// } | |
1020 | /// } | |
1021 | /// | |
1022 | /// impl Ord for Person { | |
1b1a35ee | 1023 | /// fn cmp(&self, other: &Self) -> Ordering { |
3157f602 XL |
1024 | /// self.height.cmp(&other.height) |
1025 | /// } | |
1026 | /// } | |
1027 | /// | |
1028 | /// impl PartialEq for Person { | |
1b1a35ee | 1029 | /// fn eq(&self, other: &Self) -> bool { |
3157f602 XL |
1030 | /// self.height == other.height |
1031 | /// } | |
1032 | /// } | |
1033 | /// ``` | |
1034 | /// | |
74b04a01 | 1035 | /// You may also find it useful to use [`partial_cmp`] on your type's fields. Here |
3157f602 XL |
1036 | /// is an example of `Person` types who have a floating-point `height` field that |
1037 | /// is the only field to be used for sorting: | |
1038 | /// | |
1039 | /// ``` | |
1040 | /// use std::cmp::Ordering; | |
1041 | /// | |
1042 | /// struct Person { | |
1043 | /// id: u32, | |
1044 | /// name: String, | |
1045 | /// height: f64, | |
1046 | /// } | |
1047 | /// | |
1048 | /// impl PartialOrd for Person { | |
532ac7d7 | 1049 | /// fn partial_cmp(&self, other: &Self) -> Option<Ordering> { |
3157f602 XL |
1050 | /// self.height.partial_cmp(&other.height) |
1051 | /// } | |
1052 | /// } | |
1053 | /// | |
1054 | /// impl PartialEq for Person { | |
532ac7d7 | 1055 | /// fn eq(&self, other: &Self) -> bool { |
3157f602 XL |
1056 | /// self.height == other.height |
1057 | /// } | |
1058 | /// } | |
1059 | /// ``` | |
54a0048b SL |
1060 | /// |
1061 | /// # Examples | |
1062 | /// | |
1063 | /// ``` | |
5099ac24 FG |
1064 | /// let x: u32 = 0; |
1065 | /// let y: u32 = 1; | |
54a0048b SL |
1066 | /// |
1067 | /// assert_eq!(x < y, true); | |
1068 | /// assert_eq!(x.lt(&y), true); | |
1069 | /// ``` | |
74b04a01 XL |
1070 | /// |
1071 | /// [`partial_cmp`]: PartialOrd::partial_cmp | |
1072 | /// [`cmp`]: Ord::cmp | |
83c7162d | 1073 | #[lang = "partial_ord"] |
85aaf69f | 1074 | #[stable(feature = "rust1", since = "1.0.0")] |
83c7162d XL |
1075 | #[doc(alias = ">")] |
1076 | #[doc(alias = "<")] | |
1077 | #[doc(alias = "<=")] | |
1078 | #[doc(alias = ">=")] | |
5099ac24 FG |
1079 | #[cfg_attr( |
1080 | bootstrap, | |
1081 | rustc_on_unimplemented( | |
1082 | message = "can't compare `{Self}` with `{Rhs}`", | |
1083 | label = "no implementation for `{Self} < {Rhs}` and `{Self} > {Rhs}`", | |
1084 | ) | |
1085 | )] | |
1086 | #[cfg_attr( | |
1087 | not(bootstrap), | |
1088 | rustc_on_unimplemented( | |
1089 | message = "can't compare `{Self}` with `{Rhs}`", | |
1090 | label = "no implementation for `{Self} < {Rhs}` and `{Self} > {Rhs}`", | |
1091 | append_const_msg, | |
1092 | ) | |
8faf50e0 | 1093 | )] |
064997fb | 1094 | #[const_trait] |
c295e0f8 | 1095 | #[rustc_diagnostic_item = "PartialOrd"] |
1a4d82fc | 1096 | pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> { |
85aaf69f SL |
1097 | /// This method returns an ordering between `self` and `other` values if one exists. |
1098 | /// | |
1099 | /// # Examples | |
1100 | /// | |
1101 | /// ``` | |
1102 | /// use std::cmp::Ordering; | |
1103 | /// | |
1104 | /// let result = 1.0.partial_cmp(&2.0); | |
1105 | /// assert_eq!(result, Some(Ordering::Less)); | |
1106 | /// | |
1107 | /// let result = 1.0.partial_cmp(&1.0); | |
1108 | /// assert_eq!(result, Some(Ordering::Equal)); | |
1109 | /// | |
1110 | /// let result = 2.0.partial_cmp(&1.0); | |
1111 | /// assert_eq!(result, Some(Ordering::Greater)); | |
1112 | /// ``` | |
1113 | /// | |
1114 | /// When comparison is impossible: | |
1115 | /// | |
1116 | /// ``` | |
ba9703b0 | 1117 | /// let result = f64::NAN.partial_cmp(&1.0); |
85aaf69f SL |
1118 | /// assert_eq!(result, None); |
1119 | /// ``` | |
3b2f2976 | 1120 | #[must_use] |
85aaf69f | 1121 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1122 | fn partial_cmp(&self, other: &Rhs) -> Option<Ordering>; |
1123 | ||
1124 | /// This method tests less than (for `self` and `other`) and is used by the `<` operator. | |
85aaf69f SL |
1125 | /// |
1126 | /// # Examples | |
1127 | /// | |
1128 | /// ``` | |
85aaf69f SL |
1129 | /// let result = 1.0 < 2.0; |
1130 | /// assert_eq!(result, true); | |
1131 | /// | |
1132 | /// let result = 2.0 < 1.0; | |
1133 | /// assert_eq!(result, false); | |
1134 | /// ``` | |
1a4d82fc | 1135 | #[inline] |
3b2f2976 | 1136 | #[must_use] |
85aaf69f | 1137 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1138 | fn lt(&self, other: &Rhs) -> bool { |
dfeec247 | 1139 | matches!(self.partial_cmp(other), Some(Less)) |
1a4d82fc JJ |
1140 | } |
1141 | ||
85aaf69f SL |
1142 | /// This method tests less than or equal to (for `self` and `other`) and is used by the `<=` |
1143 | /// operator. | |
1144 | /// | |
1145 | /// # Examples | |
1146 | /// | |
1147 | /// ``` | |
1148 | /// let result = 1.0 <= 2.0; | |
1149 | /// assert_eq!(result, true); | |
1150 | /// | |
1151 | /// let result = 2.0 <= 2.0; | |
1152 | /// assert_eq!(result, true); | |
1153 | /// ``` | |
1a4d82fc | 1154 | #[inline] |
3b2f2976 | 1155 | #[must_use] |
85aaf69f | 1156 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1157 | fn le(&self, other: &Rhs) -> bool { |
f2b60f7d | 1158 | matches!(self.partial_cmp(other), Some(Less | Equal)) |
1a4d82fc JJ |
1159 | } |
1160 | ||
85aaf69f SL |
1161 | /// This method tests greater than (for `self` and `other`) and is used by the `>` operator. |
1162 | /// | |
1163 | /// # Examples | |
1164 | /// | |
1165 | /// ``` | |
1166 | /// let result = 1.0 > 2.0; | |
1167 | /// assert_eq!(result, false); | |
1168 | /// | |
1169 | /// let result = 2.0 > 2.0; | |
1170 | /// assert_eq!(result, false); | |
1171 | /// ``` | |
1a4d82fc | 1172 | #[inline] |
3b2f2976 | 1173 | #[must_use] |
85aaf69f | 1174 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1175 | fn gt(&self, other: &Rhs) -> bool { |
dfeec247 | 1176 | matches!(self.partial_cmp(other), Some(Greater)) |
1a4d82fc JJ |
1177 | } |
1178 | ||
85aaf69f SL |
1179 | /// This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` |
1180 | /// operator. | |
1181 | /// | |
1182 | /// # Examples | |
1183 | /// | |
1184 | /// ``` | |
1185 | /// let result = 2.0 >= 1.0; | |
1186 | /// assert_eq!(result, true); | |
1187 | /// | |
1188 | /// let result = 2.0 >= 2.0; | |
1189 | /// assert_eq!(result, true); | |
1190 | /// ``` | |
1a4d82fc | 1191 | #[inline] |
3b2f2976 | 1192 | #[must_use] |
85aaf69f | 1193 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1194 | fn ge(&self, other: &Rhs) -> bool { |
ba9703b0 | 1195 | matches!(self.partial_cmp(other), Some(Greater | Equal)) |
1a4d82fc JJ |
1196 | } |
1197 | } | |
1198 | ||
416331ca | 1199 | /// Derive macro generating an impl of the trait `PartialOrd`. |
416331ca | 1200 | #[rustc_builtin_macro] |
416331ca XL |
1201 | #[stable(feature = "builtin_macro_prelude", since = "1.38.0")] |
1202 | #[allow_internal_unstable(core_intrinsics)] | |
dfeec247 XL |
1203 | pub macro PartialOrd($item:item) { |
1204 | /* compiler built-in */ | |
1205 | } | |
416331ca | 1206 | |
cc61c64b | 1207 | /// Compares and returns the minimum of two values. |
85aaf69f | 1208 | /// |
c34b1796 AL |
1209 | /// Returns the first argument if the comparison determines them to be equal. |
1210 | /// | |
74b04a01 | 1211 | /// Internally uses an alias to [`Ord::min`]. |
041b39d2 | 1212 | /// |
85aaf69f SL |
1213 | /// # Examples |
1214 | /// | |
1215 | /// ``` | |
1216 | /// use std::cmp; | |
1217 | /// | |
1218 | /// assert_eq!(1, cmp::min(1, 2)); | |
1219 | /// assert_eq!(2, cmp::min(2, 2)); | |
1220 | /// ``` | |
1a4d82fc | 1221 | #[inline] |
74b04a01 | 1222 | #[must_use] |
85aaf69f | 1223 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb | 1224 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
136023e0 | 1225 | #[cfg_attr(not(test), rustc_diagnostic_item = "cmp_min")] |
064997fb | 1226 | pub const fn min<T: ~const Ord + ~const Destruct>(v1: T, v2: T) -> T { |
041b39d2 | 1227 | v1.min(v2) |
1a4d82fc JJ |
1228 | } |
1229 | ||
e1599b0c XL |
1230 | /// Returns the minimum of two values with respect to the specified comparison function. |
1231 | /// | |
1232 | /// Returns the first argument if the comparison determines them to be equal. | |
1233 | /// | |
1234 | /// # Examples | |
1235 | /// | |
1236 | /// ``` | |
e1599b0c XL |
1237 | /// use std::cmp; |
1238 | /// | |
1239 | /// assert_eq!(cmp::min_by(-2, 1, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), 1); | |
1240 | /// assert_eq!(cmp::min_by(-2, 2, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), -2); | |
1241 | /// ``` | |
1242 | #[inline] | |
74b04a01 | 1243 | #[must_use] |
cdc7bbd5 | 1244 | #[stable(feature = "cmp_min_max_by", since = "1.53.0")] |
e1599b0c XL |
1245 | pub fn min_by<T, F: FnOnce(&T, &T) -> Ordering>(v1: T, v2: T, compare: F) -> T { |
1246 | match compare(&v1, &v2) { | |
1247 | Ordering::Less | Ordering::Equal => v1, | |
1248 | Ordering::Greater => v2, | |
1249 | } | |
1250 | } | |
1251 | ||
1252 | /// Returns the element that gives the minimum value from the specified function. | |
1253 | /// | |
1254 | /// Returns the first argument if the comparison determines them to be equal. | |
1255 | /// | |
1256 | /// # Examples | |
1257 | /// | |
1258 | /// ``` | |
e1599b0c XL |
1259 | /// use std::cmp; |
1260 | /// | |
1261 | /// assert_eq!(cmp::min_by_key(-2, 1, |x: &i32| x.abs()), 1); | |
1262 | /// assert_eq!(cmp::min_by_key(-2, 2, |x: &i32| x.abs()), -2); | |
1263 | /// ``` | |
1264 | #[inline] | |
74b04a01 | 1265 | #[must_use] |
cdc7bbd5 | 1266 | #[stable(feature = "cmp_min_max_by", since = "1.53.0")] |
e1599b0c XL |
1267 | pub fn min_by_key<T, F: FnMut(&T) -> K, K: Ord>(v1: T, v2: T, mut f: F) -> T { |
1268 | min_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2))) | |
1269 | } | |
1270 | ||
cc61c64b | 1271 | /// Compares and returns the maximum of two values. |
85aaf69f | 1272 | /// |
c34b1796 AL |
1273 | /// Returns the second argument if the comparison determines them to be equal. |
1274 | /// | |
74b04a01 | 1275 | /// Internally uses an alias to [`Ord::max`]. |
041b39d2 | 1276 | /// |
85aaf69f SL |
1277 | /// # Examples |
1278 | /// | |
1279 | /// ``` | |
1280 | /// use std::cmp; | |
1281 | /// | |
1282 | /// assert_eq!(2, cmp::max(1, 2)); | |
1283 | /// assert_eq!(2, cmp::max(2, 2)); | |
1284 | /// ``` | |
1a4d82fc | 1285 | #[inline] |
74b04a01 | 1286 | #[must_use] |
85aaf69f | 1287 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb | 1288 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
136023e0 | 1289 | #[cfg_attr(not(test), rustc_diagnostic_item = "cmp_max")] |
064997fb | 1290 | pub const fn max<T: ~const Ord + ~const Destruct>(v1: T, v2: T) -> T { |
041b39d2 | 1291 | v1.max(v2) |
1a4d82fc JJ |
1292 | } |
1293 | ||
e1599b0c XL |
1294 | /// Returns the maximum of two values with respect to the specified comparison function. |
1295 | /// | |
1296 | /// Returns the second argument if the comparison determines them to be equal. | |
1297 | /// | |
1298 | /// # Examples | |
1299 | /// | |
1300 | /// ``` | |
e1599b0c XL |
1301 | /// use std::cmp; |
1302 | /// | |
1303 | /// assert_eq!(cmp::max_by(-2, 1, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), -2); | |
1304 | /// assert_eq!(cmp::max_by(-2, 2, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), 2); | |
1305 | /// ``` | |
1306 | #[inline] | |
74b04a01 | 1307 | #[must_use] |
cdc7bbd5 | 1308 | #[stable(feature = "cmp_min_max_by", since = "1.53.0")] |
e1599b0c XL |
1309 | pub fn max_by<T, F: FnOnce(&T, &T) -> Ordering>(v1: T, v2: T, compare: F) -> T { |
1310 | match compare(&v1, &v2) { | |
1311 | Ordering::Less | Ordering::Equal => v2, | |
1312 | Ordering::Greater => v1, | |
1313 | } | |
1314 | } | |
1315 | ||
1316 | /// Returns the element that gives the maximum value from the specified function. | |
1317 | /// | |
1318 | /// Returns the second argument if the comparison determines them to be equal. | |
1319 | /// | |
1320 | /// # Examples | |
1321 | /// | |
1322 | /// ``` | |
e1599b0c XL |
1323 | /// use std::cmp; |
1324 | /// | |
1325 | /// assert_eq!(cmp::max_by_key(-2, 1, |x: &i32| x.abs()), -2); | |
1326 | /// assert_eq!(cmp::max_by_key(-2, 2, |x: &i32| x.abs()), 2); | |
1327 | /// ``` | |
1328 | #[inline] | |
74b04a01 | 1329 | #[must_use] |
cdc7bbd5 | 1330 | #[stable(feature = "cmp_min_max_by", since = "1.53.0")] |
e1599b0c XL |
1331 | pub fn max_by_key<T, F: FnMut(&T) -> K, K: Ord>(v1: T, v2: T, mut f: F) -> T { |
1332 | max_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2))) | |
1333 | } | |
1334 | ||
1a4d82fc JJ |
1335 | // Implementation of PartialEq, Eq, PartialOrd and Ord for primitive types |
1336 | mod impls { | |
dfeec247 | 1337 | use crate::cmp::Ordering::{self, Equal, Greater, Less}; |
60c5eb7d | 1338 | use crate::hint::unreachable_unchecked; |
1a4d82fc JJ |
1339 | |
1340 | macro_rules! partial_eq_impl { | |
1341 | ($($t:ty)*) => ($( | |
85aaf69f | 1342 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1343 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1344 | impl const PartialEq for $t { | |
1a4d82fc JJ |
1345 | #[inline] |
1346 | fn eq(&self, other: &$t) -> bool { (*self) == (*other) } | |
1347 | #[inline] | |
1348 | fn ne(&self, other: &$t) -> bool { (*self) != (*other) } | |
1349 | } | |
1350 | )*) | |
1351 | } | |
1352 | ||
85aaf69f | 1353 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1354 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1355 | impl const PartialEq for () { | |
1a4d82fc | 1356 | #[inline] |
dfeec247 XL |
1357 | fn eq(&self, _other: &()) -> bool { |
1358 | true | |
1359 | } | |
1a4d82fc | 1360 | #[inline] |
dfeec247 XL |
1361 | fn ne(&self, _other: &()) -> bool { |
1362 | false | |
1363 | } | |
1a4d82fc JJ |
1364 | } |
1365 | ||
1366 | partial_eq_impl! { | |
8bb4bdeb | 1367 | bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 |
1a4d82fc JJ |
1368 | } |
1369 | ||
1370 | macro_rules! eq_impl { | |
1371 | ($($t:ty)*) => ($( | |
85aaf69f | 1372 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1373 | impl Eq for $t {} |
1374 | )*) | |
1375 | } | |
1376 | ||
8bb4bdeb | 1377 | eq_impl! { () bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } |
1a4d82fc JJ |
1378 | |
1379 | macro_rules! partial_ord_impl { | |
1380 | ($($t:ty)*) => ($( | |
85aaf69f | 1381 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1382 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1383 | impl const PartialOrd for $t { | |
1a4d82fc JJ |
1384 | #[inline] |
1385 | fn partial_cmp(&self, other: &$t) -> Option<Ordering> { | |
923072b8 | 1386 | match (*self <= *other, *self >= *other) { |
1a4d82fc JJ |
1387 | (false, false) => None, |
1388 | (false, true) => Some(Greater), | |
1389 | (true, false) => Some(Less), | |
1390 | (true, true) => Some(Equal), | |
1391 | } | |
1392 | } | |
1393 | #[inline] | |
1394 | fn lt(&self, other: &$t) -> bool { (*self) < (*other) } | |
1395 | #[inline] | |
1396 | fn le(&self, other: &$t) -> bool { (*self) <= (*other) } | |
1397 | #[inline] | |
1398 | fn ge(&self, other: &$t) -> bool { (*self) >= (*other) } | |
1399 | #[inline] | |
1400 | fn gt(&self, other: &$t) -> bool { (*self) > (*other) } | |
1401 | } | |
1402 | )*) | |
1403 | } | |
1404 | ||
85aaf69f | 1405 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1406 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1407 | impl const PartialOrd for () { | |
1a4d82fc JJ |
1408 | #[inline] |
1409 | fn partial_cmp(&self, _: &()) -> Option<Ordering> { | |
1410 | Some(Equal) | |
1411 | } | |
1412 | } | |
1413 | ||
85aaf69f | 1414 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1415 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1416 | impl const PartialOrd for bool { | |
1a4d82fc JJ |
1417 | #[inline] |
1418 | fn partial_cmp(&self, other: &bool) -> Option<Ordering> { | |
fc512014 | 1419 | Some(self.cmp(other)) |
1a4d82fc JJ |
1420 | } |
1421 | } | |
1422 | ||
b039eaaf | 1423 | partial_ord_impl! { f32 f64 } |
1a4d82fc JJ |
1424 | |
1425 | macro_rules! ord_impl { | |
1426 | ($($t:ty)*) => ($( | |
b039eaaf | 1427 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1428 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1429 | impl const PartialOrd for $t { | |
b039eaaf SL |
1430 | #[inline] |
1431 | fn partial_cmp(&self, other: &$t) -> Option<Ordering> { | |
1432 | Some(self.cmp(other)) | |
1433 | } | |
1434 | #[inline] | |
1435 | fn lt(&self, other: &$t) -> bool { (*self) < (*other) } | |
1436 | #[inline] | |
1437 | fn le(&self, other: &$t) -> bool { (*self) <= (*other) } | |
1438 | #[inline] | |
1439 | fn ge(&self, other: &$t) -> bool { (*self) >= (*other) } | |
1440 | #[inline] | |
1441 | fn gt(&self, other: &$t) -> bool { (*self) > (*other) } | |
1442 | } | |
1443 | ||
85aaf69f | 1444 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1445 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1446 | impl const Ord for $t { | |
1a4d82fc JJ |
1447 | #[inline] |
1448 | fn cmp(&self, other: &$t) -> Ordering { | |
e1599b0c XL |
1449 | // The order here is important to generate more optimal assembly. |
1450 | // See <https://github.com/rust-lang/rust/issues/63758> for more info. | |
1451 | if *self < *other { Less } | |
1452 | else if *self == *other { Equal } | |
b039eaaf | 1453 | else { Greater } |
1a4d82fc JJ |
1454 | } |
1455 | } | |
1456 | )*) | |
1457 | } | |
1458 | ||
85aaf69f | 1459 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1460 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1461 | impl const Ord for () { | |
1a4d82fc | 1462 | #[inline] |
dfeec247 XL |
1463 | fn cmp(&self, _other: &()) -> Ordering { |
1464 | Equal | |
1465 | } | |
1a4d82fc JJ |
1466 | } |
1467 | ||
85aaf69f | 1468 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1469 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1470 | impl const Ord for bool { | |
1a4d82fc JJ |
1471 | #[inline] |
1472 | fn cmp(&self, other: &bool) -> Ordering { | |
60c5eb7d XL |
1473 | // Casting to i8's and converting the difference to an Ordering generates |
1474 | // more optimal assembly. | |
1475 | // See <https://github.com/rust-lang/rust/issues/66780> for more info. | |
1476 | match (*self as i8) - (*other as i8) { | |
1477 | -1 => Less, | |
1478 | 0 => Equal, | |
1479 | 1 => Greater, | |
1480 | // SAFETY: bool as i8 returns 0 or 1, so the difference can't be anything else | |
1481 | _ => unsafe { unreachable_unchecked() }, | |
1482 | } | |
1a4d82fc JJ |
1483 | } |
1484 | } | |
1485 | ||
8bb4bdeb | 1486 | ord_impl! { char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } |
1a4d82fc | 1487 | |
ff7c6d11 | 1488 | #[unstable(feature = "never_type", issue = "35121")] |
064997fb FG |
1489 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1490 | impl const PartialEq for ! { | |
9e0c209e SL |
1491 | fn eq(&self, _: &!) -> bool { |
1492 | *self | |
1493 | } | |
1494 | } | |
5bcae85e | 1495 | |
ff7c6d11 | 1496 | #[unstable(feature = "never_type", issue = "35121")] |
9e0c209e | 1497 | impl Eq for ! {} |
5bcae85e | 1498 | |
ff7c6d11 | 1499 | #[unstable(feature = "never_type", issue = "35121")] |
064997fb FG |
1500 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1501 | impl const PartialOrd for ! { | |
9e0c209e SL |
1502 | fn partial_cmp(&self, _: &!) -> Option<Ordering> { |
1503 | *self | |
5bcae85e SL |
1504 | } |
1505 | } | |
1506 | ||
ff7c6d11 | 1507 | #[unstable(feature = "never_type", issue = "35121")] |
064997fb FG |
1508 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1509 | impl const Ord for ! { | |
9e0c209e SL |
1510 | fn cmp(&self, _: &!) -> Ordering { |
1511 | *self | |
1512 | } | |
1513 | } | |
5bcae85e | 1514 | |
1a4d82fc JJ |
1515 | // & pointers |
1516 | ||
85aaf69f | 1517 | #[stable(feature = "rust1", since = "1.0.0")] |
064997fb FG |
1518 | #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] |
1519 | impl<A: ?Sized, B: ?Sized> const PartialEq<&B> for &A | |
dfeec247 | 1520 | where |
064997fb | 1521 | A: ~const PartialEq<B>, |
dfeec247 | 1522 | { |
1a4d82fc | 1523 | #[inline] |
dfeec247 XL |
1524 | fn eq(&self, other: &&B) -> bool { |
1525 | PartialEq::eq(*self, *other) | |
1526 | } | |
1a4d82fc | 1527 | #[inline] |
dfeec247 XL |
1528 | fn ne(&self, other: &&B) -> bool { |
1529 | PartialEq::ne(*self, *other) | |
1530 | } | |
1a4d82fc | 1531 | } |
85aaf69f | 1532 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
1533 | impl<A: ?Sized, B: ?Sized> PartialOrd<&B> for &A |
1534 | where | |
1535 | A: PartialOrd<B>, | |
1536 | { | |
1a4d82fc | 1537 | #[inline] |
532ac7d7 | 1538 | fn partial_cmp(&self, other: &&B) -> Option<Ordering> { |
1a4d82fc JJ |
1539 | PartialOrd::partial_cmp(*self, *other) |
1540 | } | |
1541 | #[inline] | |
dfeec247 XL |
1542 | fn lt(&self, other: &&B) -> bool { |
1543 | PartialOrd::lt(*self, *other) | |
1544 | } | |
1a4d82fc | 1545 | #[inline] |
dfeec247 XL |
1546 | fn le(&self, other: &&B) -> bool { |
1547 | PartialOrd::le(*self, *other) | |
1548 | } | |
1a4d82fc | 1549 | #[inline] |
dfeec247 XL |
1550 | fn gt(&self, other: &&B) -> bool { |
1551 | PartialOrd::gt(*self, *other) | |
1552 | } | |
60c5eb7d | 1553 | #[inline] |
dfeec247 XL |
1554 | fn ge(&self, other: &&B) -> bool { |
1555 | PartialOrd::ge(*self, *other) | |
1556 | } | |
1a4d82fc | 1557 | } |
85aaf69f | 1558 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
1559 | impl<A: ?Sized> Ord for &A |
1560 | where | |
1561 | A: Ord, | |
1562 | { | |
1a4d82fc | 1563 | #[inline] |
dfeec247 XL |
1564 | fn cmp(&self, other: &Self) -> Ordering { |
1565 | Ord::cmp(*self, *other) | |
1566 | } | |
1a4d82fc | 1567 | } |
85aaf69f | 1568 | #[stable(feature = "rust1", since = "1.0.0")] |
0bf4aa26 | 1569 | impl<A: ?Sized> Eq for &A where A: Eq {} |
1a4d82fc JJ |
1570 | |
1571 | // &mut pointers | |
1572 | ||
85aaf69f | 1573 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
1574 | impl<A: ?Sized, B: ?Sized> PartialEq<&mut B> for &mut A |
1575 | where | |
1576 | A: PartialEq<B>, | |
1577 | { | |
1a4d82fc | 1578 | #[inline] |
dfeec247 XL |
1579 | fn eq(&self, other: &&mut B) -> bool { |
1580 | PartialEq::eq(*self, *other) | |
1581 | } | |
1a4d82fc | 1582 | #[inline] |
dfeec247 XL |
1583 | fn ne(&self, other: &&mut B) -> bool { |
1584 | PartialEq::ne(*self, *other) | |
1585 | } | |
1a4d82fc | 1586 | } |
85aaf69f | 1587 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
1588 | impl<A: ?Sized, B: ?Sized> PartialOrd<&mut B> for &mut A |
1589 | where | |
1590 | A: PartialOrd<B>, | |
1591 | { | |
1a4d82fc | 1592 | #[inline] |
532ac7d7 | 1593 | fn partial_cmp(&self, other: &&mut B) -> Option<Ordering> { |
1a4d82fc JJ |
1594 | PartialOrd::partial_cmp(*self, *other) |
1595 | } | |
1596 | #[inline] | |
dfeec247 XL |
1597 | fn lt(&self, other: &&mut B) -> bool { |
1598 | PartialOrd::lt(*self, *other) | |
1599 | } | |
1a4d82fc | 1600 | #[inline] |
dfeec247 XL |
1601 | fn le(&self, other: &&mut B) -> bool { |
1602 | PartialOrd::le(*self, *other) | |
1603 | } | |
1a4d82fc | 1604 | #[inline] |
dfeec247 XL |
1605 | fn gt(&self, other: &&mut B) -> bool { |
1606 | PartialOrd::gt(*self, *other) | |
1607 | } | |
60c5eb7d | 1608 | #[inline] |
dfeec247 XL |
1609 | fn ge(&self, other: &&mut B) -> bool { |
1610 | PartialOrd::ge(*self, *other) | |
1611 | } | |
1a4d82fc | 1612 | } |
85aaf69f | 1613 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
1614 | impl<A: ?Sized> Ord for &mut A |
1615 | where | |
1616 | A: Ord, | |
1617 | { | |
1a4d82fc | 1618 | #[inline] |
dfeec247 XL |
1619 | fn cmp(&self, other: &Self) -> Ordering { |
1620 | Ord::cmp(*self, *other) | |
1621 | } | |
1a4d82fc | 1622 | } |
85aaf69f | 1623 | #[stable(feature = "rust1", since = "1.0.0")] |
0bf4aa26 | 1624 | impl<A: ?Sized> Eq for &mut A where A: Eq {} |
1a4d82fc | 1625 | |
85aaf69f | 1626 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
1627 | impl<A: ?Sized, B: ?Sized> PartialEq<&mut B> for &A |
1628 | where | |
1629 | A: PartialEq<B>, | |
1630 | { | |
1a4d82fc | 1631 | #[inline] |
dfeec247 XL |
1632 | fn eq(&self, other: &&mut B) -> bool { |
1633 | PartialEq::eq(*self, *other) | |
1634 | } | |
1a4d82fc | 1635 | #[inline] |
dfeec247 XL |
1636 | fn ne(&self, other: &&mut B) -> bool { |
1637 | PartialEq::ne(*self, *other) | |
1638 | } | |
1a4d82fc JJ |
1639 | } |
1640 | ||
85aaf69f | 1641 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
1642 | impl<A: ?Sized, B: ?Sized> PartialEq<&B> for &mut A |
1643 | where | |
1644 | A: PartialEq<B>, | |
1645 | { | |
1a4d82fc | 1646 | #[inline] |
dfeec247 XL |
1647 | fn eq(&self, other: &&B) -> bool { |
1648 | PartialEq::eq(*self, *other) | |
1649 | } | |
1a4d82fc | 1650 | #[inline] |
dfeec247 XL |
1651 | fn ne(&self, other: &&B) -> bool { |
1652 | PartialEq::ne(*self, *other) | |
1653 | } | |
1a4d82fc JJ |
1654 | } |
1655 | } |