Skip to content

Commit

Permalink
Rollup merge of rust-lang#40619 - stjepang:unstable-book-sort-unstabl…
Browse files Browse the repository at this point in the history
…e, r=frewsxcv

Add docs for sort_unstable to unstable book

Tracking issue for the feature: rust-lang#40585

r? @steveklabnik
  • Loading branch information
GuillaumeGomez authored Mar 22, 2017
2 parents 8c4f2c6 + 6acbbc6 commit 7455018
Showing 1 changed file with 31 additions and 0 deletions.
31 changes: 31 additions & 0 deletions src/doc/unstable-book/src/sort-unstable.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]);
```

0 comments on commit 7455018

Please sign in to comment.