Lcl · Core · Packages · Libraries

List

namespace List

Basic list container for Lcl.

Implemented as a resizable array.

proc List::new value

Constructs a list from arguments.

Alias for other constructors.

Examples:

>> List::new "a" "b" "c"
("a" "b" "c")
>> let foo [List::new "a" "b" "c"]
>> == $foo ("a" "b" "c")
1

proc List::push lst values

Return a list with the pushed value appended to it.

Examples:

>> List::push ("a" "b" "c") "d"
("a" "b" "c" "d")

proc List::push! name value

Append value in place to the list held by the var named name, and return the list. name is a bare name, not a value: this is a special form, like set!.

Equivalent to set! name [List::push $name value] but O(1) amortised: a value-returning push must copy whenever the source binding still owns the list, so accumulating in a loop that way is O(n^2). Anything that aliased the old list keeps seeing the old list; the var alone sees the new element.

Examples:

>> var acc ()
>> List::push! acc 1
(1)
>> List::push! acc 2
(1 2)
>> $acc
(1 2)

proc List::pop! name

Remove the last element of the list held by the var named name in place, and return that element. Errors on an empty list. The mutating counterpart of pop: note that pop returns the shortened list, pop! returns the element.

Examples:

>> var stack ("a" "b" "c")
>> List::pop! stack
"c"
>> $stack
("a" "b")

proc List::pop lst

Pop a value off a list. Does not mutate the original list

Examples:

>> let foo ("a" "b" "c")
>>List::pop $foo
("a" "b")
>> == $foo ("a" "b" "c")
1

proc List::slice lst start end

Returns a half-open slice [start, end) from a list.

Examples:

>> List::slice ("a" "b" "c" "d" "e") 1 4
("b" "c" "d")
>> List::slice ("a" "b" "c" "d" "e") 0 3
("a" "b" "c")

proc List::concat lst *rest

Concatenates one or more lists, in order. Returns a new list.

Spreading with @ inside a list literal does the same thing and also lets you interleave literal elements: (@$a @$b "extra").

Examples:

>> List::concat ("a" "b") ("c" "d")
("a" "b" "c" "d")
>> List::concat ("a") ("b") ("c")
("a" "b" "c")
>> let a ("a" "b")
>> let b ("c")
>> List::new @$a @$b "d"
("a" "b" "c" "d")

proc List::reverse lst

Reverses a list. Returns a new list.

Examples:

>> List::reverse ("a" "b" "c")
("c" "b" "a")

proc List::index lst offset

Returns an item from a list at the index. Offset is 0-indexed. Does not mutate the list.

Examples:

>> List::index ("a" "b" "c") 0
"a"
>> List::index ("a" "b" "c") 2
"c"

proc List::range start end step

Returns a list of sequential numbers from [start, end).

Supports an optional step.

Examples:

>> List::range 1 5
(1 2 3 4)
>> List::range 5 0 -1
(5 4 3 2 1)
>> List::range 0 10 3
(0 3 6 9)

proc List::map lst fn

Applies a function over a list, taking each element of the list as an argument. Returns a new list.

Examples

List::map (1 2 3) [lambda {x} {* x 2}] (2 4 6)

proc List::filter lst pred

Applies a predicate function over a list. The results are taken as truthy and a new list is returned where the elements have passed the function.

Examples:

>> List::filter (1 2 3 4 5 6) [lambda {x} {== [% $x 2] 0}]
(2 4 6)

proc List::reduce lst init fn

Applies a function of a list with some accumulator and initializer.

Examples:

>> List::reduce (1 2 3 4 5) 0 [lambda {acc x} {+ $acc $x}]
15

proc List::sort lst

Sorts a list. Sorts words lexicalgraphically and numbers numerically.

Returns a new list.

Examples:

>> List::sort (banana apple cherry)
("apple" "banana" "cherry")
>> List::sort [List::range 5 1 -1]
(2 3 4 5)

proc List::sort_by lst fn

Sorts by a function that determines order. Returns a new list.

Examples:

>> let rows ((bob 30) (amy 25) (cal 28))
>> List::sort_by $rows [lambda {row} {get $row 1}]
(("amy" 25) ("cal" 28) ("bob" 30))

proc List::sort_with lst fn

Sorts by a two-valued function that determines order. Returns a new list.

Examples:

>> List::sort_with (1 10 2 20 3) [lambda {a b} {- $a $b}]
(1 2 3 10 20)

proc List::find lst fn

Find the first element of a list given some search function.

Returns a copy.

Examples:

>> List::find (1 5 10 15 20) [lambda {x} {> $x 8}]
10

proc List::any? lst pred

Returns truthy based on whether any of the elements of a list satisfy some function.

Examples:

>> List::any? (1 2 3 4 5) [lambda {x} {> $x 4}]
1
>> List::any? (1 2 3 4) [lambda {x} {> $x 100}]
0

proc List::all? lst fn

Returns truthy based on whether or not all of the elements satisfy some function.

Examples:

>> List::all? (1 2 3) [lambda {x} {> $x 0}]
1
>> List::all? (1 2 3) [lambda {x} {< $x 0}]
0

proc List::unique lst

Returns the unique elements of the list, removing duplicates. Returns a new list.

Examples:

>> List::unique (1 2 3 1 3 4)
(1 2 3 4)

proc List::flatten lst (depth -1)

Flattens nested sub-lists, recursing to any depth. Empty sub-lists disappear; non-list elements are kept in order.

The optional depth bounds how many levels are flattened: 0 returns the list unchanged, N unwraps at most N levels, and a negative value (or omitting it) flattens fully.

Examples:

>> List::flatten ((a b) (c (d e (f g))))
("a" "b" "c" "d" "e" "f" "g")

>> List::flatten ((a b) (c (d e (f g)))) 1
("a" "b" "c" ("d" "e" ("f" "g")))