From 7e57f0a6a8fd4e5df7890613918f4a2c3b5a1fb7 Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" 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] { /// /// 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] { /// 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)" 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] { /// // 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] { /// // 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)" 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] { /// * 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] { /// // 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] { /// * 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] { /// // 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)" 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] { /// * 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] { /// * 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`. /// /// ```