List

A Python-style list class providing common operations to create, modify, and query sequences of values.

Quick Reference

Predicates:

Function	Description
all(pred)	Return true if all values match the predicate.
any(pred)	Return true if any value matches the predicate.

Mutation:

Function	Description
append(v)	Append a value to the end of the list.
clear()	Remove all elements from the list.
extend(ls)	Extend the list with another list.
extract(pred)	Extract values matching the predicate and remove them from the list.
insert(pos, v)	Insert a value at the given position.
insert(v)	Append a value to the end of the list.
pop()	Remove and return the last element.
pop(pos)	Remove and return the element at the given position.
prepend(v)	Insert a value at the start of the list.
remove(v)	Remove the first matching value.
sort(comp)	Sort the list in place.

Copying:

Function	Description
copy()	Return a shallow copy of the list.

Query:

Function	Description
contains(v)	Return true if the list contains the value.
count(v)	Count how many times a value appears.
index(v)	Return the index of the first matching value.
index_if(pred)	Return the index of the first value matching the predicate.
len()	Return the number of elements in the list.

Access:

Function	Description
first()	Return the first element or nil if empty.
last()	Return the last element or nil if empty.

Transform:

Function	Description
difference(ls)	Return a new list with values not in the given list.
drop(n)	Return a new list without the first n elements.
filter(pred)	Return a new list with values matching the predicate.
flatten()	Flatten one level of nested lists.
foreach(fn)	Apply a function to each element (for side effects).
group_by(fn)	Group list values by a computed key.
intersection(ls)	Return values that are also present in the given list.
invert()	Invert values to indices in a new table.
join(sep)	Join list values into a string.
map(fn)	Return a new list by mapping each value.
reduce(fn, init)	Reduce the list to a single value using an accumulator.
reverse()	Return a new list with items reversed.
setify()	Convert the list to a set.
slice(i, j)	Return a new list containing items from i to j (inclusive).
take(n)	Return the first n elements as a new list.
uniq()	Return a new list with duplicates removed (first occurrence kept).
zip(ls)	Zip two lists into a list of 2-element tables.

Functions

Predicates

all(pred)

Return true if all values match the predicate. Empty lists return true.

local is_even = function(v) return v % 2 == 0 end
local ok = List({ 2, 4 }):all(is_even)
-- result: true

any(pred)

Return true if any value matches the predicate.

local has_len_2 = function(v) return #v == 2 end
local ok = List({ "a", "bb" }):any(has_len_2)
-- result: true

Mutation

append(v)

Append a value to the end of the list.

local l = List({ "a" }):append("b")
-- result: { "a", "b" }

clear()

Remove all elements from the list.

local l = List({ "a", "b" }):clear()
-- result: { }

extend(ls)

Extend the list with another list.

local l = List({ "a" })
l:extend({ "b", "c" })
-- result: { "a", "b", "c" }

extract(pred)

Extract values matching the predicate and remove them from the list.

local l = List({ "a", "bb", "c" })
local is_len_1 = function(v) return #v == 1 end
local ex = l:extract(is_len_1)
-- result: ex = { "a", "c" }, l = { "bb" }

insert(pos, v)

Insert a value at the given position.

local l = List({ "a", "c" }):insert(2, "b")
-- result: { "a", "b", "c" }

insert(v)

Append a value to the end of the list.

local l = List({ "a", "b" }):insert("b")
-- result: { "a", "b", "c" }

pop()

Remove and return the last element.

local l = List({ "a", "b" })
local v = l:pop()
-- result: v == "b"; l is { "a" }

pop(pos)

Remove and return the element at the given position.

local l = List({ "a", "b", "c" })
local v = l:pop(2)
-- result: v == "b"; l is { "a", "c" }

prepend(v)

Insert a value at the start of the list.

local l = List({ "b", "c" })
l:prepend("a")
-- result: { "a", "b", "c" }

remove(v)

Remove the first matching value.

local l = List({ "a", "b", "b" })
l:remove("b")
-- result: { "a", "b" }

sort(comp)

Sort the list in place.

local l = List({ 3, 1, 2 })
l:sort()
-- result: { 1, 2, 3 }

Copying

copy()

Return a shallow copy of the list.

local c = List({ "a", "b" }):copy()
-- result: { "a", "b" }

Query

contains(v)

Return true if the list contains the value.

local ok = List({ "a", "b" }):contains("b")
-- result: true

count(v)

Count how many times a value appears.

local n = List({ "a", "b", "b" }):count("b")
-- result: 2

index(v)

Return the index of the first matching value.

local i = List({ "a", "b", "c", "b" }):index("b")
-- result: 2

index_if(pred)

Return the index of the first value matching the predicate.

local gt_1 = function(x) return x > 1 end
local i = List({ 1, 2, 3 }):index_if(gt_1)
-- result: 2

len()

Return the number of elements in the list.

local n = List({ "a", "b", "c" }):len()
-- result: 3

Access

first()

Return the first element or nil if empty.

local v = List({ "a", "b" }):first()
-- result: "a"

last()

Return the last element or nil if empty.

local v = List({ "a", "b" }):last()
-- result: "b"

Transform

difference(ls)

Return a new list with values not in the given list.

local d = List({ "a", "b", "c" }):difference({ "b" })
-- result: { "a", "c" }

drop(n)

Return a new list without the first n elements.

local t = List({ "a", "b", "c" }):drop(1)
-- result: { "b", "c" }

filter(pred)

Return a new list with values matching the predicate.

local is_len_1 = function(v) return #v == 1 end
local f = List({ "a", "bb", "c" }):filter(is_len_1)
-- result: { "a", "c" }

flatten()

Flatten one level of nested lists.

local f = List({ { "a", "b" }, { "c" } }):flatten()
-- result: { "a", "b", "c" }

foreach(fn)

Apply a function to each element (for side effects). Returns nil.

List({ "a", "b" }):foreach(print)

group_by(fn)

Group list values by a computed key.

local words = { "aa", "b", "ccc", "dd" }
local g = List(words):group_by(string.len)
-- result: { {"b"}, { "aa", "dd" }, { "ccc" } }

intersection(ls)

Return values that are also present in the given list. Order is preserved from the original list.

local i = List({ "a", "b", "a", "c" }):intersection({ "a", "c" })
-- result: { "a", "a", "c" }

invert()

Invert values to indices in a new table.

local t = List({ "a", "b", "c" }):invert()
-- result: { a = 1, b = 2, c = 3 }

join(sep)

Join list values into a string.

local s = List({ "a", "b", "c" }):join(",")
-- result: "a,b,c"

map(fn)

Return a new list by mapping each value.

local to_upper = function(v) return v:upper() end
local m = List({ "a", "b" }):map(to_upper)
-- result: { "A", "B" }

reduce(fn, init)

Reduce the list to a single value using an accumulator. If init is nil, the first element is used as the initial value. Empty lists return init (or nil if init is nil).

local add = function(acc, v) return acc + v end
local sum = List({ 1, 2, 3 }):reduce(add, 0)
-- result: 6

sum = List({ 1, 2, 3 }):reduce(add, 10)
-- result: 16

reverse()

Return a new list with items reversed.

local r = List({ "a", "b", "c" }):reverse()
-- result: { "c", "b", "a" }

setify()

Convert the list to a set.

local s = List({ "a", "b", "a" }):setify()
-- result: { a = true, b = true }

slice(i, j)

Return a new list containing items from i to j (inclusive). Supports negative indices (-1 is last element).

local t = List({ "a", "b", "c", "d" }):slice(2, 3)
-- result: { "b", "c" }

take(n)

Return the first n elements as a new list.

local t = List({ "a", "b", "c" }):take(2)
-- result: { "a", "b" }

uniq()

Return a new list with duplicates removed (first occurrence kept).

local u = List({ "a", "b", "a", "c" }):uniq()
-- result: { "a", "b", "c" }

zip(ls)

Zip two lists into a list of 2-element tables. Length is the minimum of both lists.

local z = List({ "a", "b" }):zip({ 1, 2 })
-- result: { {"a",1}, {"b",2} }