Box and Vec

The Box and Vec types chapter defines container representations and type rules. This chapter defines their operations, reference semantics, and allocation lifecycles. The capability table defines Copy, Clone, and equality support.

Builtin signatures

In these signatures, T stands for the container’s concrete type argument. &self takes a shared reference to the container; &mut self takes a mutable reference. new is an associated function with no receiver. The other entries are methods and follow the ordinary method-call rules. None of the operations in this table requires a builtin trait capability of T; arguments follow the ordinary call and coercion rules.

ContainerSignatureBehavior
Box<T>fn new(value: T) -> Box<T>Moves or copies value into new owned storage.
Vec<T>fn new() -> Vec<T>Creates an empty vector.
Vec<T>fn len(&self) -> usizeReturns the number of initialized elements.
Vec<T>fn is_empty(&self) -> boolReturns whether the length is zero.
Vec<T>fn push(&mut self, value: T) -> ()Appends one element by copy or move.
Vec<T>fn remove(&mut self, index: usize) -> TMoves out and returns the indexed element, shifting later elements left.

In valid programs, constructors have explicit concrete type arguments:

let boxed = Box::<i32>::new(7);
let mut values = Vec::<i32>::new();

All container constructors–including nested ones–must provide explicit concrete type arguments. Omitting this argument, as in Box::new(7) or Vec::new(), is undefined behavior under the test guarantees. Lifetime arguments inside T follow the lifetime rules; type-position _ is unsupported.

Box access and moves

For b: Box<T>, the builtin dereference expression *b is a T place. It is mutable through a mutable owner or mutable reference and read-only through shared access. Normal field, index, method, and borrow operations apply after supported Box and reference dereferences.

Dereferencing an owned Box does not insert a shared borrow. An immutable owner prevents replacing its contents, but an &mut U stored in those contents can still provide mutable access to U. Access through &Box<T> crosses a shared reference and cannot provide this mutable access.

Reading Copy contents copies them. Reading non-Copy contents from an owned Box moves them; moving through a borrowed Box is excluded by the ownership guarantee. An allocation whose contents were moved may remain allocated until program end.

Vec operations

For v: Vec<T> and index: usize, the builtin index expression v[index] is a T place.

Indexing and removal require index < len; out-of-bounds execution is excluded with no required check or panic. remove preserves order and supports non-Copy, non-Clone elements. Reading a Copy indexed element copies it; directly moving a non-Copy indexed element is undefined behavior (excluded by test guarantees), so elements must be extracted using remove. Assignment to a mutable indexed place is supported.

let mut v = Vec::<i32>::new();
v.push(10);
v.push(20);
let first = v[0];               // copying an i32 element
let removed = v.remove(0);      // removing element at index 0

Vec itself is not dereferenceable and never coerces to an element or slice reference.

Indexing and mutable access

Vec indexing implicitly borrows the vector. Shared reads and &mut T to &T coercions require only shared access. Assignment, compound assignment, mutable borrowing or reborrowing, and an &mut self receiver require mutable access to the vector at that indexing step.

The requirement persists through fields, further indexing, Box dereferences, and mutable references stored in the element. An &mut T inside a vector does not make an immutable vector mutable:

fn shared_access(values: Vec<&mut i32>) {
    let r: &i32 = values[0]; // valid: &mut i32 coerces to &i32
}

fn immutable_vector(values: Vec<&mut i32>) {
    *values[0] = 2; // compile error: add mut to the values parameter
}

fn mutable_vector(mut values: Vec<&mut i32>) {
    *values[0] = 2; // valid: the vector can be borrowed mutably
}

fn mutable_reference(values: &mut Vec<&mut i32>) {
    *values[0] = 2; // valid: the reference supplies mutable access
}

Mutable reborrows and method receivers require the same mutable access even without an explicit assignment to the element. Both functions below require mut values:

fn mutable_reborrow(values: Vec<&mut i32>) {
    let r: &mut i32 = values[0]; // compile error
}

fn nested_method(values: Vec<Vec<i32>>) {
    values[0].push(2); // compile error: push needs a mutable receiver
}

Fixed-array indexing and owned Box dereferencing do not insert a container borrow. A mutable reference stored there can therefore remain usable through an immutable owner. The position of the mutable reference matters:

fn array_reference(values: [&mut i32; 1]) {
    *values[0] = 2; // valid, unlike immutable_vector above
}

fn boxed_reference(value: Box<&mut i32>) {
    **value = 2; // valid: dereferencing the stored mutable reference
}

fn boxed_vector(values: Box<Vec<&mut i32>>) {
    *values[0] = 2; // compile error: the vector has an immutable owner
}

fn boxed_vector_reference(values: Box<&mut Vec<&mut i32>>) {
    *values[0] = 2; // valid: mutable access is obtained before Vec indexing
}

Clone and equality

When T is Clone, the containers support these builtin Clone methods:

TypeMethod signatureResult
Box<T>fn clone(&self) -> Box<T>Clones the stored T into independently owned storage.
Vec<T>fn clone(&self) -> Vec<T>Clones elements in order into an independent vector of equal length.

Owned nested containers clone recursively; shared references are copied without cloning their targets. The Clone capability is specified in Builtin traits. Dot calls remain subject to the competing-method exclusion if multiple methods match the same candidate receiver type. A fully qualified call such as Box::<i32>::clone(&boxed) selects the container operation directly without method lookup.

Box equality compares stored values. Vec equality compares length and corresponding elements, ignoring allocation address, capacity, and padding. These operations compose with struct derives and finite values of recursive types.

Storage and references

A Vec stores exactly its initialized sequence; spare capacity is not initialized data. Capacity and growth are unobservable implementation choices. Reallocation preserves values and order but invalidates references into the old buffer. remove invalidates references to removed or shifted elements.

Tests obey Rust’s borrowing rules, including supported two-phase receiver borrowing such as v.push(v.len()). They never use an element reference across a conflicting mutable container operation, regardless of spare capacity. No borrow checker is required.

Zero-sized heap objects are undefined behavior under the zero-sized-data guarantee. An empty Vec<T> for nonzero-sized T is valid and need not have a dereferenceable buffer. All allocations in valid tests fit within the target’s 32-bit usize address space, and test cases do not depend on allocation failure.

Heap cleanup

Student-generated code does not need to free heap allocations. Heap leaks are allowed: storage from Box and Vec may remain allocated after scope exit, overwrite, move-out, return, jumps, or Vec buffer replacement. No per-value destruction, deallocation call, or final heap-cleanup code is required.

This does not change source ownership or reference validity. Moves still transfer ownership, clones still create independent owned contents, and a reference invalidated by reallocation or removal remains invalid even if the old bytes are still present.

An implementation may reclaim or reuse storage earlier when it preserves program behavior and valid references. Tests fit the cumulative heap budget defined by the backend resource guarantees.