From 7e57f0a6a8fd4e5df7890613918f4a2c3b5a1fb7 Mon Sep 17 00:00:00 2001
From: "Havvy (Ryan Scheel)" <ryan.havvy@gmail.com>
Date: Sun, 2 Sep 2018 22:26:38 -0700
Subject: [PATCH 1/4] Doc total order requirement of sort(_unstable)_by
I took the definition of what a total order is from the Ord trait
docs. I specifically put "elements of the slice" because if you
have a slice of f64s, but know none are NaN, then sorting by
partial ord is total in this case. I'm not sure if I should give
such an example in the docs or not.
---
src/liballoc/slice.rs | 7 +++++++
src/libcore/slice/mod.rs | 7 +++++++
2 files changed, 14 insertions(+)
diff --git a/src/liballoc/slice.rs b/src/liballoc/slice.rs
index 33d28bef2d707..2ded376b395a7 100644
--- a/src/liballoc/slice.rs
+++ b/src/liballoc/slice.rs
@@ -211,6 +211,13 @@ impl<T> [T] {
///
/// This sort is stable (i.e. does not reorder equal elements) and `O(n log n)` worst-case.
///
+ /// The comparator function must define a total ordering for the elements in the slice. If
+ /// the ordering is not total, the order of the elements is unspecified. An order is a
+ /// total order if it is (for all a, b and c):
+ ///
+ /// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
+ /// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
+ ///
/// When applicable, unstable sorting is preferred because it is generally faster than stable
/// sorting and it doesn't allocate auxiliary memory.
/// See [`sort_unstable_by`](#method.sort_unstable_by).
diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs
index a50426ba886bb..c22ea0a01f8e0 100644
--- a/src/libcore/slice/mod.rs
+++ b/src/libcore/slice/mod.rs
@@ -1339,6 +1339,13 @@ impl<T> [T] {
/// This sort is unstable (i.e. may reorder equal elements), in-place (i.e. does not allocate),
/// and `O(n log n)` worst-case.
///
+ /// The comparator function must define a total ordering for the elements in the slice. If
+ /// the ordering is not total, the order of the elements is unspecified. An order is a
+ /// total order if it is (for all a, b and c):
+ ///
+ /// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
+ /// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
+ ///
/// # Current implementation
///
/// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters,
From e36bbc82f2fc49945b4ef42ddeca8c1443c3bac4 Mon Sep 17 00:00:00 2001
From: "Havvy (Ryan Scheel)" <ryan.havvy@gmail.com>
Date: Mon, 3 Sep 2018 23:11:15 -0700
Subject: [PATCH 2/4] Example of total ord of elements for sort_by
---
src/liballoc/slice.rs | 6 ++++++
src/libcore/slice/mod.rs | 6 ++++++
2 files changed, 12 insertions(+)
diff --git a/src/liballoc/slice.rs b/src/liballoc/slice.rs
index 2ded376b395a7..ad47eb4b70bb8 100644
--- a/src/liballoc/slice.rs
+++ b/src/liballoc/slice.rs
@@ -242,6 +242,12 @@ impl<T> [T] {
/// // reverse sorting
/// v.sort_by(|a, b| b.cmp(a));
/// assert!(v == [5, 4, 3, 2, 1]);
+ ///
+ /// // While f64 doesn't implement Ord because NaN != NaN, we can use
+ /// // partial_cmp here because we know none of the elements are NaN.
+ /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+ /// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
+ /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[inline]
diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs
index c22ea0a01f8e0..a6e0389e66f1d 100644
--- a/src/libcore/slice/mod.rs
+++ b/src/libcore/slice/mod.rs
@@ -1367,6 +1367,12 @@ impl<T> [T] {
/// // reverse sorting
/// v.sort_unstable_by(|a, b| b.cmp(a));
/// assert!(v == [5, 4, 3, 2, 1]);
+ ///
+ /// // While f64 doesn't implement Ord because NaN != NaN, we can use
+ /// // partial_cmp here because we know none of the elements are NaN.
+ /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+ /// floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
+ /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
/// ```
///
/// [pdqsort]: https://github.com/orlp/pdqsort
From b911dba40b441a65d8566e2013256612a15d27a4 Mon Sep 17 00:00:00 2001
From: "Havvy (Ryan Scheel)" <ryan.havvy@gmail.com>
Date: Sun, 9 Sep 2018 22:07:17 -0700
Subject: [PATCH 3/4] Slice total example: Move closer to total defn
---
src/liballoc/slice.rs | 15 +++++++++------
src/libcore/slice/mod.rs | 15 +++++++++------
2 files changed, 18 insertions(+), 12 deletions(-)
diff --git a/src/liballoc/slice.rs b/src/liballoc/slice.rs
index ad47eb4b70bb8..0802dc3e50073 100644
--- a/src/liballoc/slice.rs
+++ b/src/liballoc/slice.rs
@@ -218,6 +218,15 @@ impl<T> [T] {
/// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
/// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
///
+ /// For example, while `f64` doesn't implement `Ord` because `NaN != NaN`, we can use
+ /// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.
+ ///
+ /// ```
+ /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+ /// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
+ /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
+ /// ```
+ ///
/// When applicable, unstable sorting is preferred because it is generally faster than stable
/// sorting and it doesn't allocate auxiliary memory.
/// See [`sort_unstable_by`](#method.sort_unstable_by).
@@ -242,12 +251,6 @@ impl<T> [T] {
/// // reverse sorting
/// v.sort_by(|a, b| b.cmp(a));
/// assert!(v == [5, 4, 3, 2, 1]);
- ///
- /// // While f64 doesn't implement Ord because NaN != NaN, we can use
- /// // partial_cmp here because we know none of the elements are NaN.
- /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
- /// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
- /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[inline]
diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs
index a6e0389e66f1d..f6695d876f8d6 100644
--- a/src/libcore/slice/mod.rs
+++ b/src/libcore/slice/mod.rs
@@ -1346,6 +1346,15 @@ impl<T> [T] {
/// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
/// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
///
+ /// For example, while `f64` doesn't implement `Ord` because `NaN != NaN`, we can use
+ /// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.
+ ///
+ /// ```
+ /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+ /// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
+ /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
+ /// ```
+ ///
/// # Current implementation
///
/// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters,
@@ -1367,12 +1376,6 @@ impl<T> [T] {
/// // reverse sorting
/// v.sort_unstable_by(|a, b| b.cmp(a));
/// assert!(v == [5, 4, 3, 2, 1]);
- ///
- /// // While f64 doesn't implement Ord because NaN != NaN, we can use
- /// // partial_cmp here because we know none of the elements are NaN.
- /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
- /// floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
- /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
/// ```
///
/// [pdqsort]: https://github.com/orlp/pdqsort
From 99bed21101ef098393c9e6c8eb64f21892dbc8be Mon Sep 17 00:00:00 2001
From: "Havvy (Ryan Scheel)" <ryan.havvy@gmail.com>
Date: Mon, 10 Sep 2018 15:38:37 -0700
Subject: [PATCH 4/4] Linkify types in docs
---
src/liballoc/slice.rs | 2 +-
src/libcore/slice/mod.rs | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/src/liballoc/slice.rs b/src/liballoc/slice.rs
index 0802dc3e50073..5f992795531ec 100644
--- a/src/liballoc/slice.rs
+++ b/src/liballoc/slice.rs
@@ -218,7 +218,7 @@ impl<T> [T] {
/// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
/// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
///
- /// For example, while `f64` doesn't implement `Ord` because `NaN != NaN`, we can use
+ /// For example, while [`f64`] doesn't implement [`Ord`] because `NaN != NaN`, we can use
/// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.
///
/// ```
diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs
index f6695d876f8d6..a9d76376c07b6 100644
--- a/src/libcore/slice/mod.rs
+++ b/src/libcore/slice/mod.rs
@@ -1346,7 +1346,7 @@ impl<T> [T] {
/// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
/// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
///
- /// For example, while `f64` doesn't implement `Ord` because `NaN != NaN`, we can use
+ /// For example, while [`f64`] doesn't implement [`Ord`] because `NaN != NaN`, we can use
/// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.
///
/// ```