Skip to content

Reference arrays slices

StefanVonRanda edited this page Jul 18, 2026 · 1 revision

Mirrored from docs/reference/arrays-slices.md in the repo — that is the canonical source; edits to this wiki page are overwritten when the wiki is re-synced.


Arrays and slices

Thesis context: Arrays are the primary test of cross-arena deep copy for contiguous sequences. Every push copies the element into the array's arena; every return copies the whole array into the caller's arena. Slices (xs[a:b]) test that a non-storable view can exist without a borrow checker — passed as a zero-copy arg, deep-copied on store.

An array [T] is a growable, ordered sequence of values of one element type. Like every Tycho value it has value semantics: assigning an array deep-copies it, so the copy and the original never share storage. The element type T can be int, float, string, a struct, or another array — nested as deep as you like.

xs := [10, 20, 30]      # literal
ys := []int             # empty (element type required)
push(xs, 40)            # append in place
last := pop(xs)         # remove and return the last element (aborts if empty)
len(xs)                 # length -> int
xs[0]                   # index read (bounds-checked)
xs[0] = 99              # index write (bounds-checked)
zs := xs                # value semantics: zs is an independent deep copy

An out-of-bounds index aborts with a message rather than reading stray memory. This check is load-bearing, not belt-and-suspenders: because every value lives in one large arena block, an out-of-bounds read usually lands on other live data in the same block instead of an unmapped page, so the OS would never fault on it — the corruption would just be silent. The runtime bounds check is what turns that into a clean abort, which is why it is always on, in both compilers. Assignment is a deep copy: copying a [string], [Point], or [[int]] duplicates the element bytes, nested structs, and inner buffers too, so mutating the copy never touches the original.

ps := [Point(1, 2), Point(3, 4)]   # array of structs
push(ps, Point(5, 6))
total := ps[1].x + ps[1].y         # index, then read a field

grid := [][int]                    # array of arrays
push(grid, [1, 2, 3])
cell := grid[0][2]                 # 3

Elements are places

A composite-array element is a mutable place — you can write through it in place rather than rebuilding the whole element. This is a projection: the transpiler hands you the element's slot in the backing buffer, bounds-checked, with no pointer ever exposed in Tycho.

ps[0].x = 10                       # a field of an element
push(ps[0].tags, "extra")          # grow an element's array field in place
grid[1][2] = 60                    # a nested-array element
bump(&ps[1].x)                     # an element field as a `inout` argument

Value semantics still holds: after qs := ps, mutating ps[0].x leaves qs untouched — each owns its buffer. The element's owning array must be a mutable variable or field; you cannot project through a read-only borrowed parameter.

Crossing function boundaries

An array parameter is a read-only borrow — passed without a copy, but you may only read it. Mutating a borrowed array (a push or an index-set) is a compile error; copy it first (b := a) if you want a mutable local, or take the parameter inout. A returned array is promoted into the caller's arena, so it never dangles.

fn make_squares(n: int) -> [int]:   # returned: promoted into the caller's arena
    r := []int
    for i in range(n):
        push(r, i * i)
    return r

fn sum(a: [int]) -> int:            # parameter: a read-only borrow
    total := 0
    for i in range(len(a)):
        total = total + a[i]
    return total

Fixed-size arrays ([N]T)

[N]T is an array whose length N is fixed at compile time — an int literal ([3]float) or an int const (const W = 16 then [W]int). Unlike the dynamic [T] (a heap buffer that grows with push), a [N]T is stored inline — no heap, no length header — and copied by value (a plain memcpy for scalar elements, deep for heap elements):

v: [3]int = [10, 20, 30]     # inline, exactly 3 elements
w := v                        # a full value copy
v[0] = 99                     # w[0] is still 10 — no sharing
len(v)                        # 3, a compile-time constant (no runtime field)

fn dot(a: [3]float, b: [3]float) -> float:      # passed and returned by value
    return a[0]*b[0] + a[1]*b[1] + a[2]*b[2]
  • The length is part of the type: [3]int and [4]int are different types, and a literal must have exactly N elements ([3]int = [1, 2] is a compile error). A bare [1, 2, 3] is a dynamic [int] unless the destination type is fixed, in which case it coerces (count and element types checked).
  • Indexing is bounds-checked against the static N; == compares element-wise; a [N]T can be a struct field (stored inline), a by-value parameter, and a return value.
  • Growth operations (push, pop, slices) do not apply — the size is fixed. Use a dynamic [T] when the length varies.

Generic over size ([$N]T)

A function can be generic over the length of a fixed array. A parameter written [$N]T introduces a size parameter $N that the call infers from the argument, and inside the body N is an ordinary int constant equal to that length:

fn sum(xs: [$N]int) -> int:      # N is inferred from the argument
    total := 0
    for i in range(N):           # N is a compile-time int in the body
        total = total + xs[i]
    return total

a: [3]int = [10, 20, 30]
b: [4]int = [1, 2, 3, 4]
print(str(sum(a)))               # 60   (one instance, N = 3)
print(str(sum(b)))               # 10   (a second instance, N = 4)

Each distinct length used is monomorphized into its own instance (just like a $T type parameter), so sum(a) and sum(b) compile to two specialized functions. Size and element parameters compose: [$N]$T infers both the length and the element type. A $N repeated across parameters must bind to one length — fn dot(a: [$N]int, b: [$N]int) requires its two arguments to be the same size, checked at the call.

  • The argument must be a fixed array — a [3]int, not a dynamic [int] (a dynamic array has no compile-time length to infer N from). A bare [1, 2, 3] literal is dynamic unless its destination type is fixed.
  • $N is inferred from an argument, so a return-only [$N]T (no parameter mentions N) is a compile error — there is nothing to infer it from.
  • A [$N]T is a template type: it is meaningful only as a function parameter, never in a stored position (a struct field, an enum payload, a newtype).

Slices (xs[a:b])

xs[a:b] is a sub-range of an array — xs[a:] runs to the end, xs[:b] from the start, xs[:] is the whole thing — with every bound checked (0 ≤ a ≤ b ≤ len). A slice is an ordinary array value, so its cost depends entirely on what you do with it:

xs := [10, 20, 30, 40, 50]
print(str(sum(xs[1:4])))      # passed to a read-only param: a ZERO-COPY view -> 90
mid := xs[1:4]                # stored: a deep copy, owning its own buffer

Passing a slice to a function that only reads its parameter costs nothing — the descriptor { data + a, b - a } points into xs's buffer, the same borrow an ordinary array argument already is. But the moment you store a slice, return it, or push it somewhere, it deep-copies into an owning array, so value semantics still holds: mutating xs afterward never touches the stored copy. That keeps the view non-storable — it can never outlive or alias the buffer it came from — without any borrow checker. Slices work on every array type and compose (xs[1:5][1:3]). One rule to remember: you cannot pass a slice of xs and a inout of xs to the same call, since the inout could reallocate the viewed buffer. A string slice s[a:b] works too — with the same s[a:] / s[:b] / s[:] forms — but unlike an array view it always copies into a fresh substring (there is no zero-copy string view); substr(s, a, b) is the equivalent function form.


Design background: why value-semantic aggregates stay sound — copied deeply, projected in place, never aliased — with no borrow checker or whole-program alias analysis, is in the aggregates design note.

Clone this wiki locally