> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # Rust Vec A `Vec` (vector) is a `Sized`, contiguous, and dynamically growable array type that manages a heap-allocated buffer. It provides $O(1)$ indexing, amortized $O(1)$ push operations, and guarantees that its elements are stored sequentially in memory, making it highly cache-friendly. ## Memory Layout Under the hood, a `Vec` is represented as a struct containing exactly three machine words: 1. **Pointer:** A non-null pointer (internally represented as `Unique`, which wraps `NonNull`) to the start of the allocated heap buffer. This strict non-null guarantee enables Rust's null-pointer optimization, allowing types like `Option>` to have the exact same memory footprint as `Vec`. 2. **Capacity:** A `usize` representing the total number of elements the buffer can currently hold without triggering a reallocation. 3. **Length:** A `usize` representing the number of initialized elements currently in the vector. The invariant `len <= capacity` is always maintained. ## Initialization Syntax Vectors can be initialized empty, pre-allocated, or populated via macros. ```rust theme={"dark"} // 1. Empty vector. Does not allocate heap memory until the first element is pushed. let mut v1: Vec = Vec::new(); // 2. Pre-allocated vector. Allocates heap space for at least 10 elements. // The underlying allocator may round up the allocation size, so capacity can be >= 10. // Prevents reallocation overhead if the maximum size is known upfront. let mut v2: Vec = Vec::with_capacity(10); // 3. Macro initialization with a list of elements. let v3 = vec![1, 2, 3]; // 4. Macro initialization with a repeated value (requires T to implement Clone). let v4 = vec![0; 5]; // Equivalent to [0, 0, 0, 0, 0] ``` ## Growth and Reallocation Mechanics When an element is added to a `Vec` and `len == capacity`, the vector must grow. The standard library handles this by: 1. Allocating a new, larger heap buffer (historically doubling the capacity). 2. Moving the existing elements from the old buffer to the new buffer. 3. Deallocating the old buffer. Because reallocation is an $O(n)$ operation, pushing to a vector is an *amortized* $O(1)$ operation. Using `Vec::with_capacity` bypasses this overhead by satisfying the capacity requirement at instantiation. ## Ownership and Memory Management `Vec` owns its elements. When a vector goes out of scope, its `Drop` implementation is triggered. This sequentially calls the `Drop` trait on all initialized elements (from index `0` to `len - 1`) and subsequently frees the underlying heap buffer. ```rust theme={"dark"} { let v = vec![String::from("A"), String::from("B")]; // v owns the heap-allocated Strings. } // v is dropped. The Strings are dropped, then the Vec's buffer is deallocated. ``` ## Slicing and Deref Coercion `Vec` implements both `Deref` and `DerefMut`. This means a vector automatically coerces to an immutable slice (`&[T]`) via `Deref`, or a mutable slice (`&mut [T]`) via `DerefMut`, when passed by reference. Slices provide a view into the vector's contiguous memory without taking ownership. ```rust theme={"dark"} let mut v = vec![10, 20, 30, 40, 50]; // Deref coercion allows calling slice methods directly on the Vec let contains_thirty = v.contains(&30); // Borrowing a specific range as an immutable slice (&[i32]) via Index let slice: &[i32] = &v[1..4]; // [20, 30, 40] // Borrowing as a mutable slice (&mut [i32]) via DerefMut coercion let mut_slice: &mut [i32] = &mut v; mut_slice[0] = 99; ``` ## Access Patterns Accessing elements requires navigating Rust's borrowing rules and bounds checking. ```rust theme={"dark"} let v = vec![10, 20, 30]; // 1. Direct indexing: v[1] is a place expression evaluating to the element (type T). // Taking a reference (&v[1]) yields &T. Panics if index >= len. let val_ref: &i32 = &v[1]; // 2. Safe access: Returns Option<&T>. Returns None if index >= len. let safe_val: Option<&i32> = v.get(5); // 3. Mutable access: Returns Option<&mut T>. let mut v_mut = vec![10, 20, 30]; if let Some(val) = v_mut.get_mut(0) { *val += 1; // v_mut is now [11, 20, 30] } ``` ## Iteration Mechanics Vectors support three primary modes of iteration, directly mapping to Rust's ownership semantics: ```rust theme={"dark"} let mut v = vec![1, 2, 3]; // 1. Immutable Borrow: Yields &T. Vector remains accessible. for val in &v { /* ... */ } // 2. Mutable Borrow: Yields &mut T. Vector remains accessible. for val in &mut v { /* ... */ } // 3. Consuming (IntoIter): Yields T. Vector is moved and destroyed. for val in v { /* ... */ } // v is no longer accessible here. ```

Tired of Poor Rust Skills? Fix That With Deep Grasping! Learn More