Rollup merge of #40619 - stjepang:unstable-book-sort-unstable, r=frewsxcv

Add docs for sort_unstable to unstable book

Tracking issue for the feature: #40585

r? @steveklabnik

1 files changed, 31 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/sort-unstable.md b/src/doc/unstable-book/src/sort-unstable.md
index aec39de2c9a..9effcfc774c 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]);
+```