18.4Vec: capacity and growth

Last updated June 13, 2026

A Vec grows when you push, but it doesn't reallocate on every single push, that would be wasteful. Understanding the difference between a vector's length and its capacity explains how growth actually works, why it's efficient, and how to make it even more efficient when you know roughly how many elements you'll need. This is a short, practical lesson about the machinery under push.

Length versus capacity

A Vec tracks two numbers. Length (len()) is how many elements it currently holds. Capacity (capacity()) is how many it could hold before needing to allocate a bigger heap buffer. Capacity is always at least the length, and usually larger:

fn main() {
    let mut v = Vec::new();
    println!("len {}, cap {}", v.len(), v.capacity());
    for i in 1..=5 {
        v.push(i);
        println!("pushed {i}: len {}, cap {}", v.len(), v.capacity());
    }
}

len 0, cap 0
pushed 1: len 1, cap 4
pushed 2: len 2, cap 4
pushed 3: len 3, cap 4
pushed 4: len 4, cap 4
pushed 5: len 5, cap 8

(The exact capacity numbers are an implementation detail and could differ between Rust versions, but the pattern is what matters.) Watch what happens: the empty vector has capacity 0. The first push allocates a buffer with room for 4. Pushes 2 through 4 fit in that room, so the capacity stays 4 and no allocation happens. The fifth push exceeds capacity 4, so the vector allocates a bigger buffer (here doubling to 8), copies the existing elements over, and adds the new one. Length grew by one each time; capacity jumped only when the buffer filled.

Why growth is amortized-cheap

This doubling strategy is why push is fast on average even though it occasionally does expensive work. Most pushes just write into already-allocated space (cheap). Once in a while, a push fills the buffer and triggers a reallocation: a new, larger buffer is allocated and all existing elements are copied to it (lesson 8.2's heap allocation, plus a copy). Because the capacity doubles each time, these expensive reallocations get rarer as the vector grows, so the cost spread across all pushes stays low. (This connects to the iteration rule from lesson 18.3: a reallocation moves the elements to a new address, which is exactly why holding a reference into the vector while pushing would dangle, and why the borrow checker forbids it.)

with_capacity: pre-allocating

When you know roughly how many elements you'll add, you can skip the repeated reallocations by allocating enough room up front with Vec::with_capacity(n):

fn main() {
    let mut v = Vec::with_capacity(100);
    println!("len {}, cap {}", v.len(), v.capacity());   // len 0, cap 100
    for i in 0..100 {
        v.push(i);                                       // no reallocation
    }
    println!("len {}, cap {}", v.len(), v.capacity());   // len 100, cap 100
}

len 0, cap 100
len 100, cap 100

Vec::with_capacity(100) creates an empty vector (length 0) with room for 100 elements already allocated. Now those 100 pushes all fit in the pre-allocated buffer, so not one of them reallocates. For a loop that adds a known number of items, this is a small, free performance win: one allocation instead of several, and no copying as it grows. It's the same idea as reserving a table for the number of guests you expect, rather than adding chairs one at a time.

Quiz time

Question #1

What's the difference between a vector's length and its capacity?

Question #2

What happens when you push onto a vector whose length equals its capacity?

Question #3

You're about to build a vector of exactly 10,000 elements in a loop. How can you avoid repeated reallocations, and why does it help?

Vec holds any type. The next lesson zooms in on the most-used specialized vector of all: String, examined as the collection of UTF-8 bytes it really is, which finally explains why s[0] doesn't compile and why string slicing can panic.