Collections

What it is and why it exists

A collection organizes values of the same type when their count may not be known until runtime. An array includes its length in its type, and a tuple can hold unlike types; a standard collection is an owning container built for growth, removal, key lookup, or queuing. It manages its elements and drops them when the container goes out of scope.

A collection type describes more than storage. It also describes semantics that callers can rely on. Vec<T> preserves sequence order and supports integer indexing, HashSet<T> represents unique membership, and HashMap<K, V> maps keys to values. If key order or range queries are part of the contract, use BTreeSet<T> or BTreeMap<K, V>; a queue usually calls for VecDeque<T>.

String also owns a growable buffer, but it maintains a UTF-8 invariant and isn’t in the std::collections module. Text indexing and slicing deserve separate treatment; see the related rust/strings topic. BinaryHeap<T> retrieves elements by priority. This page includes it in the selection table but doesn’t teach heap operations.

You’ll meet collections while parsing input, looking up records by ID, removing duplicates, scheduling work, and assembling responses. State the required semantics first, then choose the type. Picking HashMap merely because it looks general-purpose often hides an ordering requirement until output is produced.

How it works

Vec<T> owns a contiguous element buffer and tracks its length separately from its capacity. Length is the number of initialized elements. Capacity is how many elements the current allocation can hold before it must be replaced. push increases the length; when there isn’t room, the vector may allocate a larger buffer and move its elements.

Maps and sets are organized around key equality. HashMap and HashSet use a hash table . Their keys implement Eq and Hash, and equal keys must produce equal hashes. BTreeMap and BTreeSet arrange ordered keys in a B-tree , so their keys implement Ord.

Hash collections don’t provide stable iteration order. The same input need not produce the same order in another run, in another collection instance, or after a mutation. B-tree collections iterate in the key’s Ord order, which fits range queries and reproducible key sequences.

A collection owns the values inserted into it. Inserting a String into Vec<String> moves that string unless you insert a clone; calling iter() borrows elements, while into_iter() consumes the container and yields owned elements. The precise item type also depends on whether the receiver is T, &T, or &mut T.

When an iterator builds a collection, collect() needs to know the target type. Sometimes the left side of the assignment supplies it; sometimes you write collect::<HashSet<_>>(). That type decides whether duplicates survive, how key-value pairs are organized, and whether result order is preserved.

HashMap::entry represents “present” and “absent” through one Entry API call. or_insert, or_default, and and_modify operate on that state and return or modify the value inside the map. Counting and grouping therefore don’t need a contains_key call followed by a second lookup.

Examples

A data pipeline with Vec

The first example discards invalid readings, then converts Celsius values to tenths of a degree Fahrenheit. into_iter() consumes the source vector, and the Vec<i32> annotation sets the target type for collect().

The filter closure receives a reference to each candidate, hence the dereference of value in its condition. map then takes each accepted i32. The result keeps the relative order of valid readings from the input.

get(1) returns Option<&i32> instead of panicking on an invalid index. Because this element implements Copy, copied() turns the result into Option<i32>; for a non-Copy type such as String, keep the borrow or clone deliberately.

Counting with HashMap::entry

The event names are borrowed &str keys because every one comes from a static program string. Each entry call describes the key once and returns a mutable reference to its counter.

use std::collections::HashMap;

fn main() {
    let events = ["view", "click", "view", "view", "click"];
    let mut counts: HashMap<&str, usize> = HashMap::new();

    for event in events {
        *counts.entry(event).or_insert(0) += 1;
    }

    // HashMap does not promise order; sort explicitly before output.
    let mut summary: Vec<_> = counts.into_iter().collect();
    summary.sort_by_key(|(event, _)| *event);

    for (event, count) in summary {
        println!("{event}: {count}");
    }
}

click: 2
view: 3

or_insert(0) inserts 0 when the key is absent, then returns &mut usize in either state. After the reference is dereferenced, += 1 updates the value in the map rather than a temporary copy.

Sorting happens at the output boundary instead of pretending that HashMap has an order. If key order is a program-wide requirement, the BTreeMap in the next example usually states that contract more directly.

Querying a BTreeMap range

BTreeMap iterators follow key order, and range accepts Rust range bounds. The example reads jobs numbered 20 through 30, then shows the old value returned by insert when a value is replaced.

use std::collections::BTreeMap;

fn main() {
    let mut jobs = BTreeMap::from([
        (30, "running"),
        (10, "done"),
        (20, "queued"),
        (40, "blocked"),
    ]);

    for (id, state) in jobs.range(20..=30) {
        println!("job {id}: {state}");
    }

    let previous = jobs.insert(20, "running");
    println!("replaced: {previous:?}");
}

job 20: queued
job 30: running
replaced: Some("queued")

The output order comes from the key’s Ord implementation, not insertion order. Both 20 and 30 appear because the range includes its start and end.

insert moves the new value and returns Option<V>. The caller can distinguish an initial insert from a replacement; ignoring the result says that the business logic doesn’t need the displaced value.

Expressing a queue with VecDeque

A queue receives tasks at the back and takes them from the front. VecDeque exposes both directions directly, so you don’t have to remove the first element of a Vec repeatedly.

use std::collections::VecDeque;

fn main() {
    let mut queue = VecDeque::from(["parse", "index", "publish"]);

    if let Some(task) = queue.pop_front() {
        println!("running: {task}");
    }

    queue.push_back("notify");

    while let Some(task) = queue.pop_front() {
        println!("next: {task}");
    }

    println!("empty: {}", queue.is_empty());
}

running: parse
next: index
next: publish
next: notify
empty: true

pop_front() returns Option<T> and moves the element out of the queue. while let finishes naturally once the queue is empty, without a separate length check before each pop.

The queue’s logical order doesn’t mean its storage is always one contiguous slice. When an API requires contiguous elements, use make_contiguous() instead of depending on internal layout.

Pitfalls

Fix: Use get or get_mut, then return a domain error or skip the record in the None branch. Use direct indexing only when a program invariant has proved the index valid and violating that invariant should stop the current execution.

Fix: Use a B-tree collection if order pervades the business logic; if only the boundary needs stable output, collect and sort by an explicit key. When testing the map itself, compare its key-value relationships instead of its incidental debug string.

Fix: Use iter() for read-only traversal and into_iter() only when consuming the container; string-keyed maps can usually be queried with &str. Clone when a new container truly needs to own independent data, and make that ownership boundary visible in the type signature.

Fix: Use entry(key) and update through its Occupied or Vacant state. Simple counters can use or_insert, grouping containers often use or_default, and existing values can be handled with and_modify.

Fix: Use or_insert_with(build_value) for lazy construction, or or_default() when the desired value is Default::default(). During review, distinguish an already computed argument from a closure that runs only for a missing key.

Further reading

• Rust standard library: collections
• Rust standard library: Vec
• Rust standard library: Entry
• Rust standard library: BTreeMap
• Rust standard library: VecDeque