Vec[T] — Nova-native growable array

Vec[T] is a generic growable array implemented entirely in Nova on top of raw pointer allocation (RawMem.alloc). It is available as std.collections.vec_owned.Vec.

When to use Vec[T]

Use []T (the built-in slice) by default. Switch to Vec[T] when:

• The element type T is a value-struct — Option[U], named tuple, or value record — whose in-memory representation is wider than 8 bytes (the int64-slot used by []T’s internal erasure model).
• You need typed storage where every element is laid out at its real C type without boxing.

For primitives and heap-record types, []T and Vec[T] behave identically in practice; prefer []T for terseness.

Quick start

import std.collections.vec_owned.{Vec}

fn main() -> () {
    // Build a vector from a literal element list (D259: `of`, not `from([…])`)
    mut v = Vec[int].of(10, 20, 30)
    assert(v.len() == 3)

    // Push and pop
    v.push(40)
    assert(v.pop() == Some(40))

    // Index access
    assert(v.get(0) == Some(10))
    assert(v.get(99) == None)

    // Iteration
    for x in v {
        println(x)    // 10, 20, 30
    }

    // Value-struct elements work correctly
    mut opts = Vec[Option[int]].new()
    opts.push(Some(1))
    opts.push(None)
    opts.push(Some(3))
    assert(opts.get(1) == Some(None))
}

Construction

of vs .clone() — when to use which (Plan 153.1 / D259)

Vec[T].from(coll) is RETRACTED (2026-07-20, Plan 200 П16) — it was exactly coll.clone() (a deep, per-element copy via Clone, D230), so the dedicated static constructor was redundant. Use .clone() directly.

Two distinct roles — don’t mix them up:

• Building from a literal element list → Vec[T].of(a, b, c) (variadic). Like Rust vec![a, b, c]. Takes the elements directly: one allocation.
• Converting an existing collection → existing.clone(). Like Rust iter.clone() — a deep, independent copy of something you already hold.

ro a = Vec[int].of(1, 2, 3)        // ✅ literal list → of (1 allocation)
ro b = Vec[int].new()              // ✅ empty
ro c = other_vec.clone()           // ✅ convert (deep-copy) an existing collection

Why a literal never goes through a conversion path. Under D239 an array literal [1, 2, 3] is already a Vec[int] — one allocation at the literal itself. Wrapping it in a second constructor call (the old from([1, 2, 3]) anti-pattern) would copy it into a second buffer for two allocations total, versus Vec[int].of(1, 2, 3)’s one. Reserve .clone() for converting a collection you already have.

When the element type is already fixed by context, you don’t even need a constructor — the bare literal [a, b, c] is the Vec[T] (D239). of is only for inline type annotation (return position, generic context); .clone() is only for converting a collection you already hold.

Method reference

Size and capacity

Adding and removing elements

Access

Bulk operations

Slices & views (Plan 153.4 / D262)

Zero-copy []T-views of the same type sharing the parent buffer (cap == len); no Slice type. A reallocating mutation on a view detaches it (Go-model, GC-safe); an owning copy is clone()/to_vec(). The lazy slice-view iterators chunks/chunks_exact/rchunks/windows live in the explicitly-imported lazy module (import std.collections.vec_lazy) — they yield []T views one at a time with no outer Vec allocation (Rust slice::chunks/windows). See vec-internals.md → Slices & views.

Lazy slice-view iterators (import std.collections.vec_lazy; each -> BoxIter[[]T], requires n > 0):

Conversion

Protocols

Examples

Grow and iterate

mut v = Vec[int].new()
for i in 0..10 { v.push(i) }
assert(v.len() == 10)
for x in v { print("${x} ") }    // 0 1 2 3 ... 9

Insert and remove

mut v = Vec[int].of(1, 2, 4, 5)
v.insert(2, 3)                     // [1, 2, 3, 4, 5]
assert(v.remove(0) == 1)           // [2, 3, 4, 5]
assert(v.swap_remove(0) == 2)      // [5, 3, 4] (order disrupted)

Filter with retain

mut v = Vec[int].of(1, 2, 3, 4, 5, 6)
v.retain(|x| x % 2 == 0)
assert(v.as_slice() == [2, 4, 6])

Slices & views (zero-copy)

ro v = Vec[int].of(1, 2, 3, 4, 5)

// split_at: two views of the same buffer (contract 0 <= i <= len)
ro (l, r) = v.split_at(2)
assert(l.len() == 2 && r.len() == 3 && l[0] == 1 && r[0] == 3)

// first_n / last_n clamp ("take up to N")
assert(v.first_n(3).len() == 3)
assert(v.first_n(99).len() == 5)        // clamped to len
assert(v.last_n(2).equal(Vec[int].of(4, 5)))

// mut @as_slice writes through to the parent (until detach)
mut w = Vec[int].of(1, 2, 3)
mut s = w.as_slice()
s[0] = 99
assert(w[0] == 99)

// detach-on-resize: pushing onto a cap==len view reallocs; parent untouched
mut head = w.first_n(2)
head.push(7)                            // detaches into a fresh buffer
assert(w.equal(Vec[int].of(99, 2, 3)))  // parent unchanged

Value-struct elements

// Option[int] is a value-struct. []Option[int] would erase it.
// Vec[Option[int]] stores each NovaOpt_nova_int struct inline.
mut v = Vec[Option[int]].new()
v.push(Some(42))
v.push(None)
assert(v.get(0) == Some(Some(42)))
assert(v.get(1) == Some(None))

Capacity management

mut v = Vec[int].with_capacity(100)
assert(v.cap() >= 100)
for i in 0..50 { v.push(i) }
v.shrink_to_fit()
assert(v.cap() == 50)

Clone and equality

ro a = Vec[int].of(1, 2, 3)
mut b = a.clone()
b.push(4)
assert(a.len() == 3)          // original unchanged
assert(b.len() == 4)
assert(a.equals(Vec[int].of(1, 2, 3)))

Unsafe get_mut

get_mut returns a raw mutable pointer for in-place update without copying:

mut v = Vec[int].of(10, 20, 30)
if Some(p) = v.get_mut(1) {
    unsafe { *p = 99 }
}
assert(v.get(1) == Some(99))

Note: the pointer is invalidated by any subsequent push, insert, reserve, or other realloc-capable call.

Comparison with []T

Performance notes

• push: amortised O(1). Initial capacity 8; doubles on each realloc.
• get / get_mut: O(1) pointer arithmetic.
• insert / remove: O(n) element shift — prefer swap_remove when order does not matter.
• as_slice: O(n) copy — avoid in hot paths; iterate directly with for x in v.
• Buffer allocation uses RawMem.alloc (Boehm GC-tracked, zeroed, 8-byte aligned). GC scans the buffer conservatively, so element pointers inside the buffer keep their targets alive.

Spec references

• D231 — RawMem allocator API.
• D232 — Vec[T] formal spec.
• D216 §6 — pointer arithmetic codegen.
• Q-vec-vs-slice — decision guide.