Skip to content

slice methods

Level: reference · for working programmers

One line: One page per slice method a Vec reader reaches for first — the 22 that the Vec methods page names as not on its list — each with the signature, what it actually does, the trap it is usually involved in, and a program whose printed output is checked by CI.

Vec<T> implements Deref<Target = [T]>, and so does every array, so these methods are called on a Vec or an array as if they were its own — v.sort(), arr.first() — while living on the slice. That is why sort is not a Vec method, and why learning them once covers both types. Arrays and slices is the lesson; this folder is the per-method reference beside it, shaped like the Vec and str ones.

This is not the whole slice API. The pinned toolchain's documentation for [T] lists over two hundred methods, inherent and trait-provided together; the 22 here are the everyday set. Where a page's nearest relative has no page of its own — chunks_exact, split_at_mut, partition_point, sort_by_cached_key, rotate_right, fill_with — it is linked to std with a ↗.

Every page has the same shape: a one-line summary, the signature, the stability line, the prose, then a complete runnable program and its verified output. Nothing on any of these pages is hand-typed output — tools/run_examples.py compiles each example, runs it, and fails the build if what the page shows is not what the program printed. The signature block is a text fence on purpose: a bare pub fn … is not something you can paste, and the house rule is that the first rust block on a page must compile.

The signatures

Taken from the rendered documentation of the pinned toolchain, Rust 1.98.0. Two things to know when reading them.

const fn is common here, and it rarely matters. first, last, reverse, swap and rotate_left are all const — they touch no allocator, so they can run in a const context — and the stability line on each page records when that landed. It changes nothing about calling them at run time.

SliceIndex is one bound doing two jobs. get and get_mut take I: SliceIndex<[T]>, which is how a single method accepts both a usize (returning one element) and a range (returning a sub-slice). The same trait is behind v[i] and v[a..b].

Sorting

All four are stable — equal elements keep their order — except sort_unstable, whose name says so; all four return ().

method what it does
sort Ascending by Ord; may allocate a temporary buffer
sort_unstable The same, in place, without the equal-elements promise
sort_by By a comparison you write — descending, floats, several keys
sort_by_key By a key you extract, recomputed at every comparison

Searching

method what it does
contains Linear scan by ==; takes a &T, which is the Vec<String> trap
binary_search O(log n) on a sorted slice; Err carries the insertion point

iter().position(…) — the index of the first element passing a predicate — is an Iterator ↗ method, reached through iter.

The ends

method what it does
first Option<&T> — None where v[0] would panic
last Option<&T> — the safe spelling of v[v.len() - 1]
first_mut The same, writable
last_mut The same, writable

Safe indexing

method what it does
get An element or a range as an Option; an out-of-range range is None, not clamped
get_mut The same, writable — and why two at once needs get_disjoint_mut

Iterating

method what it does
iter Over &T — what for x in &v calls
iter_mut Over &mut T — what for x in &mut v calls
chunks Non-overlapping groups of n; the last may be short
windows Overlapping runs of n; never short

Rearranging

In place, and each returns ().

method what it does
reverse Flip the order
swap Exchange two indices — the thing mem::swap on two &mut v[i] cannot do
rotate_left Shift left by mid, wrapping; mid > len panics
fill Every element becomes a clone of one value; the length never changes

Joining

method what it does
concat Flatten a slice of slices or strings into one Vec or String
join The same, with a separator between the pieces

See also