lloyAlloy on GitHub
Array
Docs

Array

Updated
Array<T>
local xs = [ 1, 2, 3 ]
local doubled = xs:map(function(x) return x * 2 end)
local grid = [ [1, 2], [3, 4] ]

The array type of the std: a Luau array with the std's methods on its metatable. An array literal carries it, T[] and Array<T> name the same type, and a plain table becomes one with Array.from(t), in place. [[ is Luau's long string, so a nested array starts [ [. A read T[] is ReadArray<T>, the readers alone, and a write T[] is WriteArray<T>, push alone.

Luau rejects an alias that names itself with other arguments, so map returns the same shape under a second name, and the third map in one chain is any. Annotate the accumulator of reduce when its body uses it: xs:reduce(function(acc: number, x) return acc + x end, 0). $set[ ] and $map[ ] build a Set and a HashMap the way [ ] builds an array.

Statics

Array.new

Array.new<T>(t: { T }?): T[]

An empty array with the Array metatable, or with t the array Array.from(t) gives. [ ] is the literal for one.

local xs: number[] = new Array()
xs:push(1)

Array.with_capacity

Array.with_capacity<T>(n: number): T[]

An empty array with room for n items already allocated. Use it before a loop that pushes a known count.

local xs: number[] = Array.with_capacity(3)
xs:push(1, 2, 3)

Array.from

Array.from<T>(t: { T }): T[]

The table t as an array: it gains the metatable and stays the same table, so no copy happens.

local raw = { 1, 2, 3 }
local xs = Array.from(raw)
print(xs:len())

Methods

Array:len

Array:len(): number

The number of items, the # of the table.

local xs = [ 1, 2, 3 ]
print(xs:len())

Array:is_empty

Array:is_empty(): boolean

Whether the array holds no items.

local xs: number[] = [ ]
print(xs:is_empty())

Array:push

Array:push(...: T): Array<T>

Appends the values in the order given. It writes into the array and returns it, so calls chain.

local xs = [ 1 ]
xs:push(2, 3):push(4)
print(xs:len())

Array:pop

Array:pop(): T?

Removes the last item and returns it, or nil when the array is empty.

local xs = [ 1, 2 ]
print(xs:pop())

Array:remove

Array:remove(index: number): T?

Removes the item at index and returns it. The items after it move down one, so the order stays and the cost grows with the length. swap_remove costs the same at any length.

local xs = [ 1, 2, 3 ]
print(xs:remove(1))
print(xs:join(", "))

Array:swap_remove

Array:swap_remove(index: number): T?

Removes the item at index and returns it. The last item moves into its place, so the call costs the same at any length and the order changes. An index outside the array removes nothing and returns nil.

local xs = [ 1, 2, 3 ]
print(xs:swap_remove(1))
print(xs:join(", "))

Array:first

Array:first(): T?

The first item, or nil when the array is empty.

local xs = [ 1, 2 ]
print(xs:first())

Array:last

Array:last(): T?

The last item, or nil when the array is empty.

local xs = [ 1, 2 ]
print(xs:last())

Array:map

Array:map<U>(f: (T, number) -> U): U[]

A new array of f(item, index) for each item. The result names a second alias of the same shape, so the third map in one chain types as any.

local xs = [ 1, 2, 3 ]
local doubled = xs:map(function(x) return x * 2 end)
print(doubled:join(", "))

Array:filter

Array:filter(f: (T, number) -> boolean): T[]

A new array of the items where f(item, index) holds.

local xs = [ 1, 2, 3, 4 ]
local even = xs:filter(function(x) return x % 2 == 0 end)
print(even:len())

Array:find

Array:find(f: (T, number) -> boolean): T?

The first item where f(item, index) holds, or nil.

local xs = [ 1, 2, 3 ]
print(xs:find(function(x) return x > 1 end))

Array:find_index

Array:find_index(f: (T, number) -> boolean): number?

The index of the first item where f(item, index) holds, or nil.

local xs = [ 1, 2, 3 ]
print(xs:find_index(function(x) return x > 1 end))

Array:contains

Array:contains(value: T): boolean

Whether an item equals value. value in xs is the same test.

local xs = [ 1, 2, 3 ]
print(xs:contains(2))

Array:index_of

Array:index_of(value: T): number?

The index of the first item that equals value, or nil.

local xs = [ "a", "b" ]
print(xs:index_of("b"))

Array:for_each

Array:for_each(f: (T, number) -> ())

Calls f(item, index) for each item, in order, and returns nothing.

local xs = [ 1, 2 ]
xs:for_each(function(x, i) print(i, x) end)

Array:reduce

Array:reduce<U>(f: (U, T, number) -> U, init: U): U

Folds the array: acc = f(acc, item, index) from init, and the last acc is the result. Annotate the accumulator when its body needs the type.

local xs = [ 1, 2, 3 ]
local sum = xs:reduce(function(acc: number, x) return acc + x end, 0)
print(sum)

Array:slice

Array:slice(from: number, to: number?): T[]

A new array of the items from index from to index to, both inclusive. to defaults to the last index.

local xs = [ 1, 2, 3, 4 ]
print(xs:slice(2, 3):join(", "))

Array:concat

Array:concat(other: T[]): T[]

A new array of this one's items followed by other's. Neither input changes.

local xs = [ 1, 2 ]
print(xs:concat([ 3 ]):len())

Array:reverse

Array:reverse(): T[]

A new array with the items in the other order. This one is left as it was.

local xs = [ 1, 2, 3 ]
print(xs:reverse():first())

Array:sort_by

Array:sort_by(less: (T, T) -> boolean): T[]

Sorts in place with less(a, b) and returns the same array, so a chain reads on. The sort is not stable.

local xs = [ 3, 1, 2 ]
xs:sort_by(function(a, b) return a < b end)
print(xs:join(", "))

Array:join

Array:join(sep: string?): string

Every item through tostring, joined by sep. Without sep the parts run together.

local xs = [ 1, 2, 3 ]
print(xs:join(", "))

Array:to_table

Array:to_table(): { T }

The array's own table, not a copy: a write through it changes the array. An array is its own table, so the result is the same value under the plain table type.

local xs: number[] = [ 1, 2 ]
local t: { number } = xs:to_table()
print(#t)