OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Rollup merge of #42260 - stjepang:document-cmp-traits-agreement, r=alexcrichton

Browse Source 
Docs: impls of PartialEq/PartialOrd/Ord must agree

Fixes #41270.

This PR brings two improvements to the docs:

1. Docs for `PartialEq`, `PartialOrd`, and `Ord` clarify that their implementations must agree.
2. Fixes a subtle bug in the Dijkstra example for `BinaryHeap`, where the impls are inconsistent.
Thanks @Rufflewind for spotting the bug!

r? @alexcrichton
cc @frankmcsherry
This commit is contained in:
Mark Simulacrum 2017-05-27 20:54:04 -06:00 committed by GitHub
commit 423b410fce
2 changed files with 18 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
src/libcollections/binary_heap.rs
View File

@ -43,8 +43,11 @@
//! // instead of a max-heap.
//! impl Ord for State {
//! fn cmp(&self, other: &State) -> Ordering {
//! // Notice that the we flip the ordering here
//! // Notice that the we flip the ordering on costs.
//! // In case of a tie we compare positions - this step is necessary
//! // to make implementations of `PartialEq` and `Ord` consistent.
//! other.cost.cmp(&self.cost)
//! .then_with(|| self.position.cmp(&other.position))
//! }
//! }
//!

16
src/libcore/cmp.rs
View File

@ -67,6 +67,10 @@ use self::Ordering::*;
/// the rule that `eq` is a strict inverse of `ne`; that is, `!(a == b)` if and
/// only if `a != b`.
///
/// Implementations of `PartialEq`, `PartialOrd`, and `Ord` *must* agree with
/// each other. It's easy to accidentally make them disagree by deriving some
/// of the traits and manually implementing others.
///
/// An example implementation for a domain in which two books are considered
/// the same book if their ISBN matches, even if the formats differ:
///
@ -386,6 +390,10 @@ impl<T: Ord> Ord for Reverse<T> {
/// Then you must define an implementation for `cmp()`. You may find it useful to use
/// `cmp()` on your type's fields.
///
/// Implementations of `PartialEq`, `PartialOrd`, and `Ord` *must* agree with each other. It's
/// easy to accidentally make them disagree by deriving some of the traits and manually
/// implementing others.
///
/// Here's an example where you want to sort people by height only, disregarding `id`
/// and `name`:
///
@ -474,8 +482,8 @@ impl PartialOrd for Ordering {
///
/// ## How can I implement `PartialOrd`?
///
/// PartialOrd only requires implementation of the `partial_cmp` method, with the others generated
/// from default implementations.
/// `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 ==
@ -483,6 +491,10 @@ impl PartialOrd for Ordering {
///
/// `PartialOrd` requires your type to be `PartialEq`.
///
/// Implementations of `PartialEq`, `PartialOrd`, and `Ord` *must* agree with each other. It's
/// easy to accidentally make them disagree by deriving some of the traits and manually
/// implementing others.
///
/// If your type is `Ord`, you can implement `partial_cmp()` by using `cmp()`:
///
/// ```