Landin library reference source

core/vec

Shared: available on every enabled target.

A growable contiguous list with explicit allocation and rollback on failed growth.

new starts without allocating; reserve and push receive the provider. get copies, at lends a writable pointer, and used lends the initialized slice. End views before relocation or release. Clearing or releasing a container never frees resources referenced by its items.

Items

Executable example

This complete program is maintained in the repository runtime tests. View source.

import core/mem
import core/vec

exercise: () -> (ok: bool) ! mem.out_of_memory | mem.empty | mem.out_of_bounds =
    ok = false
    mut backing: [256]u8 = zeroed
    mut state := mem.arena_over_unchecked(addr backing[0], 256)
    mut values := vec.new(item: i32)
    try vec.push(values, state, i32(41))
    return when vec.length(values) <> 1
    slot: ptr mut i32 = try vec.at(values, usize(0))
    slot.val = 42
    last: i32 = try vec.last(values)
    return when last <> 42
    removed := try vec.pop(values)
    return when removed <> 42
    _ = vec.pop(values) else (problem)
        ok = problem == mem.empty and vec.length(values) == 0
        return
    end
end exercise

public main: () -> (code: i32) =
    code = 1
    ok := exercise() else false
    if ok then
        code = 42
    end if
end main

list type

public list: type (item: type) = struct
    values: mem.storage(item)
end list

core/vec/vec.ldn:9

Growable contiguous list with explicit allocator arguments. Its public shape contains opaque typed storage; no allocator is stored in the list.

The list shape is public as in prototype 3, but its values field has the opaque mem.storage(item) type: clients can inspect the container shape without reaching raw-storage counters or bytes.

at function

public at: (item: type, inout value: list(item), index: usize)
           -> (slot: ptr mut item from value) ! mem.out_of_bounds

core/vec/vec.ldn:194

Lend a writable pointer to an indexed item. Reports mem.out_of_bounds for a missing slot; end the pointer's lifetime before growing or releasing the list.

A writable slot for in-place update. While the result lives the list binding may not be passed inout or sink [0800]: bind it, update through it, and let it end before the next push, reserve or release.

capacity function

public capacity: (item: type, value: list(item)) -> (count: usize)

core/vec/vec.ldn:26

Return the number of items that fit without further growth.

clear function

public clear: (item: type, inout value: list(item)) -> none

core/vec/vec.ldn:225

Discard all items and retain capacity. Does not release resources referenced by discarded values.

get function

public get: (item: type, value: list(item), at: usize)
            -> (result: item from value) ! mem.out_of_bounds

core/vec/vec.ldn:179

Copy the indexed item, preserving origins of references it contains. Reports mem.out_of_bounds outside the initialized prefix.

last function

public last: (item: type, value: list(item))
             -> (result: item from value) ! mem.empty

core/vec/vec.ldn:203

Copy the last item without removing it. Reports mem.empty for an empty list.

length function

public length: (item: type, value: list(item)) -> (count: usize)

core/vec/vec.ldn:21

Return the number of initialized items.

new function

public new: (item: type) -> (result: list(item))

core/vec/vec.ldn:15

Create an empty list without allocating. Supply the allocator when growing or releasing it.

pop function

public pop: (item: type, inout value: list(item))
            -> (result: item from value) ! mem.empty

core/vec/vec.ldn:215

Remove and return the last item. Reports mem.empty without mutation when empty; retains capacity.

push function

public push: (item: type, provider: type is mem.allocator,
              inout value: list(item), inout state: provider,
              escaping added: item) -> none ! mem.out_of_memory

core/vec/vec.ldn:160

Append a value, growing capacity when needed. Reports mem.out_of_memory without appending on allocation failure. Successful growth may invalidate views into the previous allocation.

release function

public release: (item: type, provider: type is mem.allocator,
                 inout value: list(item), inout state: provider) -> none

core/vec/vec.ldn:232

Discard items, free backing through the original provider and reset the list. End all views first; nested resources remain the caller's responsibility.

reserve function

public reserve: (item: type, provider: type is mem.allocator,
                 inout value: list(item), inout state: provider, want: usize)
                -> none ! mem.out_of_memory

core/vec/vec.ldn:126

Ensure room for at least want items. May grow backing in place or copy to a replacement. Failure preserves the old length, capacity and values; successful relocation invalidates old views. Use the original provider for existing backing.

used function

public used: (item: type, value: list(item))
             -> (items: []mut item from value)

core/vec/used.ldn:8

Lend a mutable slice covering only initialized items. End uses before any operation that relocates or releases backing.

Only initialized elements are exposed. The descriptor derives from the list; changing capacity or releasing storage requires ending that view.