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

`List`

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

Usage

List = require "mods.List"

ls = List({ "a" }):append("b")
print(ls:contains("b")) --> true
print(ls:index("b"))    --> 2

Note

List(t) wraps t with the List metatable in place. It does not copy or filter table values. List(t):copy() or List.copy(t) both copy only 1..#t and wrap t as a List.

Functions

Predicates:

Function	Description
`all(pred)`	Return true if all values match the predicate.
`any(pred)`	Return true if any value matches the predicate.
`equals(ls)`	Compare two lists using shallow element equality.
`lt(ls)`	Compare two lists lexicographically.
`le(ls)`	Compare two lists lexicographically.

Mutation:

Function	Description
`append()`	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.
`concat(sep?, i?, j?)`	Concatenate list values using Lua's native `table.concat` behavior.
`join(sep?, quoted?)`	Join list values into a string.
`tostring()`	Render the list to a string via the regular method form.
`keypath()`	Render list items as a table-access key path.
`map(fn)`	Return a new list by mapping each value.
`mul(n)`	Return a new list repeated `n` times (list multiplication behavior).
`reduce(fn, init?)`	Reduce the list to a single value using an accumulator.
`reverse()`	Return a new list with items reversed.
`toset()`	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.

Metamethods:

Function	Description
`__eq(ls)`	Compare two lists using shallow element equality (`==`).
`__lt(ls)`	Compare two lists lexicographically (`<`).
`__le(ls)`	Compare two lists lexicographically (`<=`).
`__mul(n)`	Repeat a list `n` times (`*`).
`__add(ls)`	Extend the left-hand list in place with right-hand values, then return the same left-hand list reference (`+`).
`__sub(ls)`	Return values from the left list that are not present in the right list (`-`).
`__tostring()`	Render the list to a string like `{ "a", "b", 1 }`.

Predicates

Boolean checks for list-wide conditions.

`all(pred)`

Return true if all values match the predicate.

Parameters:

pred (fun(v:any):boolean): Predicate function.

Return:

ok (boolean): Whether the condition is met.

Example:

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

Note

Empty lists return true.

`any(pred)`

Return true if any value matches the predicate.

Parameters:

pred (fun(v:any):boolean): Predicate function.

Return:

ok (boolean): Whether the condition is met.

Example:

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

`equals(ls)`

Compare two lists using shallow element equality.

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ok (boolean): Whether the condition is met.

Example:

a = List({ "x", "y" })
b = List({ "x", "y" })
ok = a:equals(b) --> true

Note

equals is also available through the == operator when both operands are List.

a = List({ "a", 1 })
b = List({ "a", 1 })
ok = (a == b) --> true

Unlike ==, this method also works when ls is a plain array table.

a = List({ "a", 1 })
b = { "a", 1 }
ok = a:equals(b) --> true

equals checks only array positions (1..#list), so extra non-array keys are ignored:

t = {}
a = List({ "a", t })
b = { "a", t, a = 1 }
ok = a:equals(b) --> true

`lt(ls)`

Compare two lists lexicographically.

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ok (boolean): Whether the condition is met.

Example:

ok = List({ 1, 2 }):lt({ 1, 3 })    --> true
ok = List({ 1, 2 }):lt({ 1, 2, 0 }) --> true

Note

lt is also available through the < operator.

`le(ls)`

Compare two lists lexicographically.

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ok (boolean): Whether the condition is met.

Example:

ok = List({ 1, 2 }):le({ 1, 2 })  --> true
ok = List({ 1, 2 }):le({ 1, 1 })  --> false

Note

le is also available through the <= operator.

Mutation

In-place operations that modify the current list.

`append()`

Append a value to the end of the list.

Return:

self (T): Current list instance.

Example:

ls = List({ "a" }):append("b") --> { "a", "b" }

`clear()`

Remove all elements from the list.

Return:

self (T): Current list instance.

Example:

ls = List({ "a", "b" }):clear() --> { }

`extend(ls)`

Extend the list with another list.

Parameters:

ls (any[]): List values.

Return:

self (T): Current list instance.

Example:

ls = List({ "a" }):extend({ "b", "c" }) --> { "a", "b", "c" }

Note

extend is also available through the + operator.

`extract(pred)`

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

Parameters:

pred (fun(v:any):boolean): Predicate function.

Return:

ls (mods.List): Extracted values.

Example:

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

`insert(pos, v)`

Insert a value at the given position.

Parameters:

pos (integer): Insert position.
v (any): Value to insert.

Return:

self (T): Current list instance.

Example:

ls = List({ "a", "c" }):insert(2, "b") --> { "a", "b", "c" }

`insert(v)`

Append a value to the end of the list.

Parameters:

v (any): Value to append.

Return:

self (T): Current list instance.

Example:

ls = List({ "a", "b" }):insert("c") --> { "a", "b", "c" }

`pop()`

Remove and return the last element.

Return:

value (any): Removed value.

Example:

ls = List({ "a", "b" })
v = ls:pop() --> v == "b"; ls is { "a" }

`pop(pos)`

Remove and return the element at the given position.

Parameters:

pos (integer): Numeric value.

Return:

value (any): Removed value.

Example:

ls = List({ "a", "b", "c" })
v = ls:pop(2) --> v == "b"; ls is { "a", "c" }

`prepend(v)`

Insert a value at the start of the list.

Parameters:

v (any): Value to validate.

Return:

self (T): Current list instance.

Example:

ls = List({ "b", "c" })
ls:prepend("a") --> { "a", "b", "c" }

`remove(v)`

Remove the first matching value.

Parameters:

v (any): Value to validate.

Return:

self (T): Current list instance.

Example:

ls = List({ "a", "b", "b" })
ls:remove("b") --> { "a", "b" }

`sort(comp?)`

Sort the list in place.

Parameters:

comp? (fun(a,b):boolean): Optional comparison function (defaults to nil).

Return:

self (T): Current list instance.

Example:

ls = List({ 3, 1, 2 })
ls:sort() --> { 1, 2, 3 }

Copying

Operations that return copied list data.

`copy()`

Return a shallow copy of the list.

Return:

ls (mods.List): New list.

Example:

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

Query

Read-only queries for membership, counts, and indices.

`contains(v)`

Return true if the list contains the value.

Parameters:

v (any): Value to validate.

Return:

ok (boolean): Whether the condition is met.

Example:

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

`count(v)`

Count how many times a value appears.

Parameters:

v (any): Value to validate.

Return:

res (integer): Result count.

Example:

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

`index(v)`

Return the index of the first matching value.

Parameters:

v (any): Value to validate.

Return:

index (integer?): Result index, or nil when not found.

Example:

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

`index_if(pred)`

Return the index of the first value matching the predicate.

Parameters:

pred (fun(v:any):boolean): Predicate function.

Return:

index (integer?): Result index, or nil when no value matches.

Example:

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

`len()`

Return the number of elements in the list.

Return:

count (integer): Element count.

Example:

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

Note

Uses Lua's # operator.

Access

Direct element access helpers.

`first()`

Return the first element or nil if empty.

Return:

value (any): First value, or nil if empty.

Example:

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

`last()`

Return the last element or nil if empty.

Return:

value (any): Last value, or nil if empty.

Example:

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

Transform

Non-mutating transformations and derived-list operations.

`difference(ls)`

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

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ls (T): New list.

Example:

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

Note

difference is also available through the - operator.

`drop(n)`

Return a new list without the first n elements.

Parameters:

n (integer): Numeric value.

Return:

ls (mods.List): New list.

Example:

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

`filter(pred)`

Return a new list with values matching the predicate.

Parameters:

pred (fun(v:any):boolean): Predicate function.

Return:

ls (mods.List): New list.

Example:

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

`flatten()`

Flatten one level of nested lists.

Return:

ls (mods.List): New list.

Example:

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

`foreach(fn)`

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

Parameters:

fn (fun(v:any)): Callback function.

Return:

none (nil)

Example:

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

`group_by(fn)`

Group list values by a computed key.

Parameters:

fn (fun(v:any):any): Callback function.

Return:

groups (table): Groups keyed by the callback result.

Example:

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

`intersection(ls)`

Return values that are also present in the given list.

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ls (mods.List): New list.

Example:

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

Note

Order is preserved from the original list.

`invert()`

Invert values to indices in a new table.

Return:

idxByValue (table): Table mapping each value to its last index.

Example:

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

`concat(sep?, i?, j?)`

Concatenate list values using Lua's native table.concat behavior.

Parameters:

sep? (string): Optional separator value (defaults to "").
i? (integer): Optional start index (defaults to 1).
j? (integer): Optional end index (defaults to #self).

Return:

s (string): Concatenated string.

Example:

s = List({ "a", "b", "c" }):concat(",") --> "a,b,c"

Note

This method forwards to table.concat directly and keeps its strict element rules.

`join(sep?, quoted?)`

Join list values into a string.

Parameters:

sep? (string): Optional separator value (defaults to "").
quoted? (boolean): Optional boolean flag (defaults to false).

Return:

s (string): Joined string.

Example:

s = List({ "a", "b", "c" }):join(",")        --> "a,b,c"
s = List({ "a", "b", "c" }):join(", ", true) --> '"a", "b", "c"'

Note

Values are converted with tostring before joining. Set quoted = true to quote string values.

`tostring()`

Render the list to a string via the regular method form.

Return:

s (string): Rendered list string.

Example:

s = List({ "a", "b", 1 }):tostring() --> '{ "a", "b", 1 }'

Note

tostring(list) calls list:tostring().

`keypath()`

Render list items as a table-access key path.

Return:

s (string): Key-path string.

Example:

p = List({ "ctx", "users", 1, "name" }):keypath() --> "ctx.users[1].name"

`map(fn)`

Return a new list by mapping each value.

Parameters:

fn (fun(v):any): Callback function.

Return:

ls (mods.List): New list.

Example:

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

`mul(n)`

Return a new list repeated n times (list multiplication behavior).

Parameters:

n (integer): Numeric value.

Return:

ls (mods.List): New list.

Example:

ls = List({ "a", "b" }):mul(3) --> { "a", "b", "a", "b", "a", "b" }

Note

mul is also available through the * operator.

`reduce(fn, init?)`

Reduce the list to a single value using an accumulator.

Parameters:

fn (fun(acc:any,): v:any):any Reducer function.
init? (any): Optional initial accumulator; for non-empty lists, nil or omitted uses the first item.

Return:

res (any): Reduced value.

Example:

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

Note

For empty lists, returns init unchanged (or nil when omitted).

`reverse()`

Return a new list with items reversed.

Return:

ls (mods.List): New list.

Example:

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

`toset()`

Convert the list to a set.

Return:

set (mods.Set): New set.

Example:

s = List({ "a", "b", "a" }):toset() --> { a = true, b = true }

Note

Order is preserved from the original list.

`slice(i?, j?)`

Return a new list containing items from i to j (inclusive).

Parameters:

i? (integer): Optional start index (defaults to 1).
j? (integer): Optional end index (defaults to #self).

Return:

ls (mods.List): New list.

Example:

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

Note

Supports negative indices (-1 is last element).

`take(n)`

Return the first n elements as a new list.

Parameters:

n (integer): Numeric value.

Return:

ls (mods.List): New list.

Example:

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

`uniq()`

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

Return:

ls (mods.List): New list.

Example:

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

`zip(ls)`

Zip two lists into a list of 2-element tables.

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ls (mods.List): New list.

Example:

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

Note

Length is the minimum of both lists.

Metamethods

`__eq(ls)`

Compare two lists using shallow element equality (==).

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ok (boolean): Whether the condition is met.

Example:

a = List({ "a", { 1 } })
b = List({ "a", { 1 } })
ok = a == b --> false (different nested table references)

t = { 1 }
a = List({ "a", t })
b = List({ "a", t })
ok = a == b --> true (same nested table reference)

Note

== returns false for List vs plain-table comparisons. Use :equals(ls) for List vs plain-table comparisons.

t = { "a", 1 }
a = List(t)
b = { "a", 1 }
ok = (a == b)     --> false
ok = a:equals(b) --> true

Like :equals(ls), == compares only array positions (1..#list), so extra non-array keys are ignored when both operands are List.
```
a = List({ "a", t })
b = List({ "a", t, extra = 1 })
ok = (a == b) --> true
```

`__lt(ls)`

Compare two lists lexicographically (<).

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ok (boolean): Whether the condition is met.

Example:

ok = List({ 1, 2 }) < List({ 1, 3 }) --> true

Note

< is equivalent to :lt(ls).

`__le(ls)`

Compare two lists lexicographically (<=).

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ok (boolean): Whether the condition is met.

Example:

ok = List({ 1, 2 }) <= List({ 1, 2 }) --> true

Note

<= is equivalent to :le(ls).

`__mul(n)`

Repeat a list n times (*).

Parameters:

n (integer|mods.List): Right operand.

Return:

ls (mods.List): New list.

Example:

l1 = List({ "a", "b" }) * 3 --> { "a", "b", "a", "b", "a", "b" }
l2 = 3 * List({ "a", "b" }) --> { "a", "b", "a", "b", "a", "b" }

Note

* is equivalent to :mul(n).

`__add(ls)`

Extend the left-hand list in place with right-hand values, then return the same left-hand list reference (+).

Parameters:

ls (mods.List|any[]): Other list value.

Return:

self (mods.List|any[]): Current list instance.

Example:

a = List({ "a", "b" })
b = { "c", "d" }
c = a + b --> c and a are the same reference: { "a", "b", "c", "d" }

Note

+ operator is equivalent to :extend(ls).

`__sub(ls)`

Return values from the left list that are not present in the right list (-).

Parameters:

ls (mods.List|any[]): Other list value.

Return:

ls (mods.List): New list.

Example:

a = List({ "a", "b", "c" })
b = { "b" }
d = a - b --> { "a", "c" }

Note

- operator is equivalent to :difference(ls).

`__tostring()`

Render the list to a string like { "a", "b", 1 }.

Return:

s (string): Rendered list string.

Example:

s = tostring(List({ "a", "b", 1 })) --> '{ "a", "b", 1 }'

Note

tostring(ls) is equivalent to :tostring().

Uh oh!

FilesExpand file tree

list.md

Latest commit

History

list.md

File metadata and controls

List

Usage

Functions

Predicates

all(pred)

any(pred)

equals(ls)

lt(ls)

le(ls)

Mutation

append()

clear()

extend(ls)

extract(pred)

insert(pos, v)

insert(v)

pop()

pop(pos)

prepend(v)

remove(v)

sort(comp?)

Copying

copy()

Query

contains(v)

count(v)

index(v)

index_if(pred)

len()

Access

first()

last()

Transform

difference(ls)

drop(n)

filter(pred)

flatten()

foreach(fn)

group_by(fn)

intersection(ls)

invert()

concat(sep?, i?, j?)

join(sep?, quoted?)

tostring()

keypath()

map(fn)

mul(n)

reduce(fn, init?)

reverse()

toset()

slice(i?, j?)

take(n)

uniq()

zip(ls)

Metamethods

__eq(ls)

__lt(ls)

__le(ls)

__mul(n)

__add(ls)

__sub(ls)

__tostring()

`List`

`all(pred)`

`any(pred)`

`equals(ls)`

`lt(ls)`

`le(ls)`

`append()`

`clear()`

`extend(ls)`

`extract(pred)`

`insert(pos, v)`

`insert(v)`

`pop()`

`pop(pos)`

`prepend(v)`

`remove(v)`

`sort(comp?)`

`copy()`

`contains(v)`

`count(v)`

`index(v)`

`index_if(pred)`

`len()`

`first()`

`last()`

`difference(ls)`

`drop(n)`

`filter(pred)`

`flatten()`

`foreach(fn)`

`group_by(fn)`

`intersection(ls)`

`invert()`

`concat(sep?, i?, j?)`

`join(sep?, quoted?)`

`tostring()`

`keypath()`

`map(fn)`

`mul(n)`

`reduce(fn, init?)`

`reverse()`

`toset()`

`slice(i?, j?)`

`take(n)`

`uniq()`

`zip(ls)`

`__eq(ls)`

`__lt(ls)`

`__le(ls)`

`__mul(n)`

`__add(ls)`

`__sub(ls)`

`__tostring()`