Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rollup of 6 pull requests #40735

Closed
wants to merge 13 commits into from
Closed
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Add docs for sort_unstable to unstable book
  • Loading branch information
Stjepan Glavina committed Mar 21, 2017
commit 6acbbc66f7ff4dcf5db92c9c73c84c2b18d63b05
31 changes: 31 additions & 0 deletions src/doc/unstable-book/src/sort-unstable.md
Original file line number Diff line number Diff line change
@@ -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]);
```