From 6acbbc66f7ff4dcf5db92c9c73c84c2b18d63b05 Mon Sep 17 00:00:00 2001 From: Stjepan Glavina Date: Fri, 17 Mar 2017 23:21:21 +0100 Subject: [PATCH] Add docs for sort_unstable to unstable book --- src/doc/unstable-book/src/sort-unstable.md | 31 ++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/src/doc/unstable-book/src/sort-unstable.md b/src/doc/unstable-book/src/sort-unstable.md index aec39de2c9a73..9effcfc774c77 100644 --- a/src/doc/unstable-book/src/sort-unstable.md +++ b/src/doc/unstable-book/src/sort-unstable.md @@ -6,4 +6,35 @@ The tracking issue for this feature is: [#40585] ------------------------ +The default `sort` method on slices is stable. In other words, it guarantees +that the original order of equal elements is preserved after sorting. The +method has several undesirable characteristics: +1. It allocates a sizable chunk of memory. +2. If you don't need stability, it is not as performant as it could be. + +An alternative is the new `sort_unstable` feature, which includes these +methods for sorting slices: + +1. `sort_unstable` +2. `sort_unstable_by` +3. `sort_unstable_by_key` + +Unstable sorting is generally faster and makes no allocations. The majority +of real-world sorting needs doesn't require stability, so these methods can +very often come in handy. + +Another important difference is that `sort` lives in `libstd` and +`sort_unstable` lives in `libcore`. The reason is that the former makes +allocations and the latter doesn't. + +A simple example: + +```rust +#![feature(sort_unstable)] + +let mut v = [-5, 4, 1, -3, 2]; + +v.sort_unstable(); +assert!(v == [-5, -3, 1, 2, 4]); +```