From 2a3568f14bafa2bf62c50fd8589b48be6e31991d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 10 Jan 2017 10:23:21 -0500 Subject: [PATCH 1/4] Fix wording around sort guarantees Fixes #38524 --- src/libcollections/slice.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index e704f400d49e3..e4bc05c7ff01f 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -1064,8 +1064,11 @@ impl [T] { /// This is equivalent to `self.sort_by(|a, b| a.cmp(b))`. /// - /// This sort is stable and `O(n log n)` worst-case, but allocates - /// temporary storage half the size of `self`. + /// This sort is stable and `O(n log n)` worst-case. + /// + /// # Current Implementation + /// + /// The current implementation allocates temporary storage half the size of `self`. /// /// # Examples /// From c2b153b133d244015e4d174d893e75a733db12df Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Sat, 14 Jan 2017 01:46:30 +0100 Subject: [PATCH 2/4] Expand the sort docs --- src/libcollections/slice.rs | 44 +++++++++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index e4bc05c7ff01f..211394180e861 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -1064,11 +1064,17 @@ impl [T] { /// This is equivalent to `self.sort_by(|a, b| a.cmp(b))`. /// - /// This sort is stable and `O(n log n)` worst-case. + /// This sort is stable (i.e. does not reorder equal elements) and `O(n log n)` worst-case. /// - /// # Current Implementation + /// # Current implementation /// - /// The current implementation allocates temporary storage half the size of `self`. + /// The current algorithm is an adaptive, iterative merge sort inspired by + /// [timsort](https://en.wikipedia.org/wiki/Timsort). + /// It is designed to be very fast in cases where the slice is nearly sorted, or consists of + /// two or more sorted sequences concatenated one after another. + /// + /// Also, it allocates temporary storage half the size of `self`, but for short slices a + /// non-allocating insertion sort is used instead. /// /// # Examples /// @@ -1086,11 +1092,19 @@ impl [T] { self.sort_by(|a, b| a.cmp(b)) } - /// Sorts the slice, in place, using `f` to extract a key by which to - /// order the sort by. + /// Sorts the slice using `f` to extract a key to compare elements by. + /// + /// This sort is stable (i.e. does not reorder equal elements) and `O(n log n)` worst-case. + /// + /// # Current implementation + /// + /// The current algorithm is an adaptive, iterative merge sort inspired by + /// [timsort](https://en.wikipedia.org/wiki/Timsort). + /// It is designed to be very fast in cases where the slice is nearly sorted, or consists of + /// two or more sorted sequences concatenated one after another. /// - /// This sort is stable and `O(n log n)` worst-case, but allocates - /// temporary storage half the size of `self`. + /// Also, it allocates temporary storage half the size of `self`, but for short slices a + /// non-allocating insertion sort is used instead. /// /// # Examples /// @@ -1108,11 +1122,19 @@ impl [T] { self.sort_by(|a, b| f(a).cmp(&f(b))) } - /// Sorts the slice, in place, using `compare` to compare - /// elements. + /// Sorts the slice using `compare` to compare elements. + /// + /// This sort is stable (i.e. does not reorder equal elements) and `O(n log n)` worst-case. + /// + /// # Current implementation + /// + /// The current algorithm is an adaptive, iterative merge sort inspired by + /// [timsort](https://en.wikipedia.org/wiki/Timsort). + /// It is designed to be very fast in cases where the slice is nearly sorted, or consists of + /// two or more sorted sequences concatenated one after another. /// - /// This sort is stable and `O(n log n)` worst-case, but allocates - /// temporary storage half the size of `self`. + /// Also, it allocates temporary storage half the size of `self`, but for short slices a + /// non-allocating insertion sort is used instead. /// /// # Examples /// From 11ede684ee2e3eee4b3586174b2d5008b58a86cf Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Tue, 17 Jan 2017 01:11:06 +0100 Subject: [PATCH 3/4] Fix: insertion_len -> max_insertion --- src/libcollections/slice.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index 211394180e861..18e4a23fa8d67 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -1560,7 +1560,7 @@ fn merge_sort(v: &mut [T], mut compare: F) // FIXME #12092: These numbers are platform-specific and need more extensive testing/tuning. // - // If `v` has length up to `insertion_len`, simply switch to insertion sort because it is going + // If `v` has length up to `max_insertion`, simply switch to insertion sort because it is going // to perform better than merge sort. For bigger types `T`, the threshold is smaller. // // Short runs are extended using insertion sort to span at least `min_run` elements, in order From e02f923e37402273a4971e2c015842ecc4c5f0d9 Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Fri, 20 Jan 2017 09:11:11 +0100 Subject: [PATCH 4/4] Remove trailing whitespace --- src/libcollections/slice.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index 18e4a23fa8d67..fc49c9f56438c 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -1067,7 +1067,7 @@ impl [T] { /// This sort is stable (i.e. does not reorder equal elements) and `O(n log n)` worst-case. /// /// # Current implementation - /// + /// /// The current algorithm is an adaptive, iterative merge sort inspired by /// [timsort](https://en.wikipedia.org/wiki/Timsort). /// It is designed to be very fast in cases where the slice is nearly sorted, or consists of