collectionsLuwuexperimental

collections provides the data structures you'd otherwise build out of tables: bundles of two to four values, an ordered map that remembers insertion order, growable arrays, double-ended queues, and options and results for values that can be missing or can fail. They're builtin classes implemented in C++ that the type checker fully understands.

option and result are tables that hold their variant classes. The types have the same names and come from the library the way a required module's types do:

Copyconst .{ vec } = collections
type .{ vec } = collections

const scores: vec<number> = vec({ 10, 20 })
scores:push(30)
print(#scores)

3

The library is a prototype, and its API can still change.

Two values kept together, like a function's two results stored in one place. The fields are const: build a new pair to change them.

• == compares two pairs field by field with ==.
• tostring writes the call that builds an equal pair: pair("x", 1).
• A for loop gives each position and its value in order, nil included.
• Destructuring reads the fields by position: const .(a, b) = p.

Copyconst .{ pair } = collections

const point = pair("x", 4)
const .(axis, offset) = point
print(`{axis} = {offset}`)
print(point == pair("x", 4))
print(tostring(point))

x = 4
true
pair("x", 4)

Three values kept together. It works like pair with a third field.

Four values kept together. It works like pair with a third and fourth field.

A map whose entries stay in insertion order. A table's pairs visits keys in no particular order, and an orderedmap visits them in order for a menu, a leaderboard or the columns of a table. Finding the position of a key or the entry at a position takes constant time.

• set changes the value of a key the map has and adds a new key at the end. A key can't be nil or NaN. Setting a value to nil keeps the key: use remove to take it out.
• remove returns the removed value, or nil when the map didn't have the key.
• insert adds a new key at position and moves the entries from there on back by one. For a key the map has, it moves that entry there and sets its value.
• move moves a key to a position. movebefore and moveafter move a key right before or after other. swap trades the positions of two keys. Each raises an error when the map doesn't have a key it's given.
• sort puts the entries in a stable order by their keys. comesbefore returns true when its first key goes before its second.
• index returns the position of a key. at returns the key and value at a position, or two nils when there's no entry there.
• # gives the number of entries, and a for loop gives each key and value in order. Removing the key the loop is on raises an error at the next step.

A position is a whole number from 1 to the number of entries (one more for insert). Any other position passed to insert or a move raises an error.

Copyconst .{ orderedmap } = collections

const stock = orderedmap()
stock:set("pears", 4)
stock:set("apples", 12)
stock:insert(1, "kiwis", 7)
stock:moveafter("kiwis", "apples")

for fruit, count in stock do
    print(`{fruit}: {count}`)
end
print(stock:index("kiwis"))

pears: 4
apples: 12
kiwis: 7
3

A growable array that holds one type of value. The first value it gets fixes the type: a vec of numbers raises an error when you push a string, and a vec of objects takes objects of the same class only. nil never goes in. The optional array passed to the constructor fills the vec in order.

• push adds a value at the end and pop takes the last one off, or returns nil when the vec is empty.
• at returns the value at a position, or nil when there's none there. set replaces the value at a position the vec has.
• insert adds a value at a position from 1 to one past the end and moves the values after it back. remove takes out the value at a position and returns it.
• clear empties the vec. The element type stays fixed.
• # gives the length, a for loop gives each position and value, and tostring writes the call that builds an equal vec: vec({1, 2}).

set, insert and remove raise an error for a position out of range.

Copyconst .{ vec } = collections

const names = vec({ "Ada", "Grace" })
names:push("Linus")
names:insert(1, "Alan")
print(names:remove(3))
print(tostring(names))

const ok = pcall(function()
    names:push(42)
    return true
end)
print(ok)

Grace
vec({"Alan", "Ada", "Linus"})
false

A double-ended queue: adding and taking values at either end takes constant time. Taking the first value of an array with table.remove(t, 1) moves every other value down. A vecdeque takes it without moving the rest. Like vec, it holds one type of value fixed by the first one it gets.

• pushfront and pushback add a value at the front or the back. popfront and popback take one off, or return nil when the queue is empty.
• front and back return the value at either end without removing it.
• at and set read and replace values by position from the front, starting at 1.
• clear, #, for loops and tostring work as they do for vec.

Copyconst .{ vecdeque } = collections

const jobs = vecdeque({ "build", "test" })
jobs:pushback("deploy")
jobs:pushfront("fetch")
while #jobs > 0 do
    print(jobs:popfront())
end

fetch
build
test
deploy

A value that may be missing. A full option is a some object that holds the value, and an empty option is none itself. option.none is the same none and allocates nothing.

• option.some(value) raises an error when value is nil or none.
• get returns the value, and none:get() returns none.
• expect returns the value. none:expect(message) raises an error with message, or with "expected a value, but got none" when you leave it out.
• == compares the values of two some objects, and tostring writes option.some(5).

none has get and expect only while the library is loaded. Indexing none with any other key is an error.

Copyconst .{ option } = collections
type .{ option } = collections

const function find_user(id: number): option<string>
    return if id == 1 then option.some("Ada") else option.none
end

print(find_user(1):get())
print(find_user(2):get() == none)
print(tostring(find_user(1)))

Ada
true
option.some("Ada")

The outcome of something that can fail: an ok object with a value or an err object with an error. A function that returns a result makes its caller handle the failure instead of catching an error it raised.

• ok returns the value of an ok and none for an err. err does the opposite.
• expect returns the value of an ok. On an err it raises the error, with message and a colon in front when you pass one.
• An err's module, line and traceback say where its error was raised. A try expression fills them in, and tostring adds them after the error.
• == compares two objects of the same variant by their value or error.

A try expression runs an expression and gives a result: ok with its value, or err with the error it raised.

Copyconst .{ result } = collections
type .{ result } = collections

const function parse_port(text: string): result<number, string>
    const port = tonumber(text)
    if port and port >= 1 and port <= 65535 then
        return result.ok(port)
    end
    return result.err(`'{text}' is not a port`)
end

print(parse_port("8080"):ok())
print(parse_port("http"):err())
print(tostring(try tonumber("12")))

8080
'http' is not a port
result.ok(12)