nupp.mem.span

nupp.mem.span gives a C array a rooted, one-based, bounds-checked view. A shared Span<T> reads contiguous elements; a writable span adds exclusive access and an affine lifetime, so the pointer cannot outlive or overlap its owner.

local span = nupp.mem.span

const text = "hello"
const bytes = span.fromString(text)
assert(#bytes == 5)

Use spans at checked boundaries. Direct indexing through a pointer or variable-length C array remains an unsafe operation.

Span<T> is a sealed contract over a private implementation that keeps an element count beside a rooted pointer, so public code can neither forge one nor reach the raw pointer it holds. Indexing and slicing check that count first.

Creating a shared span#

fromCarray(source, count) borrows a C array and records its logical element count. fromString(source) creates the byte-specialized ByteSpan. Both keep their source rooted for the lifetime of the view.

local span = nupp.mem.span

local struct Point
    x: float
    y: float
end

const storage = carray(Point, 4)
const points = span.fromCarray(storage, 4)
assert(#points == 4)
assert(points[1].x == 0)

Indexes start at one. view[index] raises when the index is outside 1 through #view. slice(first, last) includes both endpoints and borrows the parent; omitting last extends through the end. An empty slice uses first, first - 1.

The operator surface replaces the former element methods and public count field. Each former member is a migration error, not a deprecated alternative:

fromFixedCarray(source, count) returns FixedSpan<T, N> when the array and literal count carry the same static N. It satisfies Span<T>, while preserving the exact count for checks and generated code.

Writable spans#

writeCarray returns the affine alias Writable<T>. Its underlying WriteSpan<T> contract is what a function accepting exclusive access names:

local span = nupp.mem.span
local indexed = nupp.mem.indexed

local struct Point
    x: float
    y: float
end

local function clear(exclusive points: span.WriteSpan<Point>): nil
    const view = points
    const indexes = indexed.range(1, #view, view)
    for index = indexes.first, indexes.last do
        view[index] = new Point(0, 0)
    end
end

local storage = carray(Point, 4)
const points = span.writeCarray(storage, 4)
clear(points)
drop points

Whole-element and direct field assignments write through the checked indexed place. shared() downgrades the writer to a shared view for the returned view's lifetime.

A writable span is affine because it represents exclusive access rather than owned memory. Dropping it, explicitly or at scope exit, ends that access; it does not free or copy the source array. writeFixedCarray and FixedWritable<T, N> preserve a static count in the same way as their shared counterparts.

Asking one array for a shared span while a writer over it is live reports NUPP2607, and so does the reverse.

Slices and partitions#

WriteSpan.slice(first, last) creates one affine child writer. The parent remains blocked until the child is dropped, preventing a write through the parent from overlapping the slice.

splitAt(mid) partitions a writer into audited, non-overlapping left and right regions. mid is the number of elements in the left region, so zero gives an empty left side and count gives an empty right side. Both children retain the parent as their root.

Use a slice for one subrange and splitAt when two disjoint writable regions must be live together. Unknown indexes and bounds otherwise conservatively overlap.

Shared range for several spans#

indexed.range(first, last, ...) checks one inclusive range against every trusted Span or SoA view and answers a record whose first and last are ordinary integers:

local span = nupp.mem.span
local indexed = nupp.mem.indexed

local struct Value
    n: integer
end

local function dot(
    borrows left: span.Span<Value>,
    borrows right: span.Span<Value>
): integer
    const first = left
    const second = right
    const indexes = indexed.range(1, #first, first, second)
    local total: integer = 0
    for index = indexes.first, indexes.last do
        total = total + first[index].n * second[index].n
    end
    return total
end

const storage = carray(Value, 4)
const values = span.fromCarray(storage, 4)
print(dot(values, values))

At least one span is required. Empty ranges use the same first, first - 1 convention as slices. The typed borrowed vararg passes each original span directly and allocates no container or interface wrapper.

When the bounds and spans are const-bound in the same function, the successful range check proves matching indexed reads and writes non-raising inside the dominated numeric loop. This proof is part of checking at every optimization level: it is what permits those calls inside noraise code.

See OPT-6 for how that proof is spent at -O1, as direct FFI element access and virtual slices that allocate no wrapper.

Passing a span to C#

ref() returns the rooted pointer and logical count for a handwritten native wrapper. Shared spans return a const T[?]; writable spans require exclusive access and return T[?]. The returned pointer borrows the span, so it cannot escape independently.

A declarative C binding can use countedBy(count) instead. Its checked call surface accepts spans, verifies shared counts, and projects the physical pointer and count arguments automatically.

type span.ByteSpan = span.Span<uint8>

type span.ByteWriteSpan = span.WriteSpan<uint8>

sealed interface span.FixedSpan<T, const N: integer> is span.Span<T>
    metamethod __len: function(self: FixedSpan<T, N>): N
end

__len: function(self: FixedSpan<T, N>): N

type span.FixedWritable<T, const N: integer> = affine(span.FixedWriteSpan<T, N>, span.destroyWriteSpan)

sealed interface span.FixedWriteSpan<T, const N: integer> is span.WriteSpan<T>
    metamethod __len: function(self: FixedWriteSpan<T, N>): N
    shared: function(borrows self: FixedWriteSpan<T, N>): span.FixedSpan<T, N> borrows (self)
end

__len: function(self: FixedWriteSpan<T, N>): N

shared: function(borrows self: FixedWriteSpan<T, N>): span.FixedSpan<T, N> borrows (self)

sealed interface span.Span<T>
    metamethod __len: function(self: Span<T>): integer
    metamethod __index: function(self: Span<T>, index: integer): T
    slice: function(self: Span<T>, first: integer, last: integer?): Span<T> borrows (self)
    ref: function(self: Span<T>): (const T[?] borrows (self), integer)
end

__len: function(self: Span<T>): integer

__index: function(self: Span<T>, index: integer): T

slice: function(self: Span<T>, first: integer, last: integer?): Span<T> borrows (self)

const values = span.fromCarray(storage, 4)
const middle = values:slice(2, 3)
assert(#middle == 2)

ref: function(self: Span<T>): (const T[?] borrows (self), integer)

type span.Writable<T> = affine(span.WriteSpan<T>, span.destroyWriteSpan)

sealed interface span.WriteSpan<T> is span.WriteToken
    metamethod __len: function(self: WriteSpan<T>): integer
    metamethod __index: function(borrows self: WriteSpan<T>, index: integer): T
    metamethod __newindex: function(exclusive self: WriteSpan<T>, index: integer, value: T): nil
    drop: nosuspend function(takes self: WriteSpan<T>): nil
    ref: function(exclusive self: WriteSpan<T>): (T[?] borrows (self), integer)
    shared: function(borrows self: WriteSpan<T>): span.Span<T> borrows (self)
    slice: function(
        exclusive self: WriteSpan<T>,
        first: integer,
        last: integer?
    ): affine(span.WriteSpan<T>, span.destroyWriteSpan) borrows (self)
    @partition(left, right)
    splitAt: function(exclusive self: WriteSpan<T>, mid: integer): span.WriteSplit<T> borrows (self)
end

__len: function(self: WriteSpan<T>): integer

__index: function(borrows self: WriteSpan<T>, index: integer): T

__newindex: function(exclusive self: WriteSpan<T>, index: integer, value: T): nil

drop: nosuspend function(takes self: WriteSpan<T>): nil

ref: function(exclusive self: WriteSpan<T>): (T[?] borrows (self), integer)

shared: function(borrows self: WriteSpan<T>): span.Span<T> borrows (self)

slice: function(
    exclusive self: WriteSpan<T>,
    first: integer,
    last: integer?
): affine(span.WriteSpan<T>, span.destroyWriteSpan) borrows (self)

splitAt: function(exclusive self: WriteSpan<T>, mid: integer): span.WriteSplit<T> borrows (self)

do
    local writable = values:write()
    local split = writable:splitAt(2)
    split.left[1] = 11 as int32
    split.right[1] = 22 as int32
end

record span.WriteSplit<T>
    readonly left: span.WriteSpan<T> borrows (anchor)
    readonly right: span.WriteSpan<T> borrows (anchor)
end

left: span.WriteSpan<T> borrows (anchor)

right: span.WriteSpan<T> borrows (anchor)

sealed interface span.WriteToken
    drop: nosuspend function(takes self: WriteToken): nil
end

drop: nosuspend function(takes self: WriteToken): nil

function span.destroyWriteSpan<T is span.WriteToken>(takes writable: T): nil

function span.fromCarray<T>(borrows source: T[?], count: integer): span.Span<T>

local struct Value
    n: int32
end

const storage = carray(Value, 4)
const values = span.fromCarray(storage, 4)
assert(#values == 4)

function span.fromFixedCarray<T, const N: integer>(borrows source: T[N], count: N): span.FixedSpan<T, N>

function span.fromString(borrows source: string): span.ByteSpan

const text = "hello"
const bytes = span.fromString(text)
assert(#bytes == 5 and bytes[1] == 104)

function span.writeCarray<T>(exclusive source: T[?], count: integer): span.Writable<T>

local struct Value
    n: int32
end

const storage = carray(Value, 4)
do
    local writable = span.writeCarray(storage, 4)
    writable[1] = new Value(42)
    drop writable
end
const values = span.fromCarray(storage, 4)
assert(values[1].n == 42)

function span.writeFixedCarray<T, const N: integer>(exclusive source: T[N], count: N): span.FixedWritable<T, N>