← Index

x/type/list

The list/sequence API, homed on the List class.

The list/sequence operations as static methods; core/list.x keeps the %-helpers they are built on.

Element access is (List ref n lst) – the adjudicated name; list-ref/list-tail are Scheme-compat wrappers.

Class List

(List of . args)

Variadic literal: the arguments as a list – (List of …) is (list …), homed on the class for the constructor-verb symmetry.

Parameters:

• args : ANY — Elements, in order

Returns: LIST — List of the arguments

Examples:

(List of 1 2 3) => (1 2 3)

(List from-seq x)

Build a list from any iterable – the from-X conversion verb (Gen from-seq is its lazy twin; the boot layer normalizes through its private %as-list plumbing). Lists and nil pass through unchanged; anything else goes through (Iter new), which raises type on a value it cannot iterate.

Parameters:

• x : ANY — A list, nil, or iterable (e.g. vector)

Returns: LIST — The input as a proper list

Examples:

(List from-seq (Vector of 1 2 3)) => (1 2 3)

(List iter lst)

An iterator over the list’s elements.

Parameters:

• lst : LIST — List to iterate

Returns: ITER — Iterator

Examples:

(Iter ->list (List iter (list 1 2))) => (1 2)

(List fold f init lst)

Fold a function over a list from the left.

Block form: (List fold (acc x) body … init lst) – or (acc i x) with the 0-based index ahead of the element.

Parameters:

• f : CALLABLE — Binary function: (accumulator, element) -> new accumulator
• init : ANY — Initial accumulator value
• lst : LIST — List or iterable to fold over

Returns: ANY — Final accumulated value

Examples:

(List fold + 0 '(1 2 3)) => 6

(List reduce f lst)

Fold without an initial value; uses the first element.

Block form: (List reduce (a b) body … lst).

Parameters:

• f : CALLABLE — Binary function
• lst : LIST — Non-empty list or iterable

Examples:

(List reduce + (list 1 2 3)) => 6

(List scan f init lst)

Like fold, but returns a list of all intermediate values.

Block form: (List scan (acc x) body … init lst) – or (acc i x) with the 0-based index ahead of the element.

Parameters:

• f : CALLABLE — Binary function
• init : ANY — Initial accumulator value
• lst : LIST — List or iterable

Examples:

(List scan + 0 (list 1 2 3)) => (0 1 3 6)

(List fold-right f init lst)

Fold from the right: elements combine last-to-first, callback (f acc element) like fold.

Block form: (List fold-right (acc x) body … init lst) – or (acc i x) with the 0-based index ahead of the element.

Parameters:

• f : CALLABLE — Binary function: (accumulator, element) -> new accumulator
• init : ANY — Initial accumulator value
• lst : LIST — List or iterable

Returns: ANY — Final accumulated value

Examples:

(List fold-right (fn (_ acc x) (pair x acc)) () (list 1 2 3)) => (1 2 3)

(List length lst)

Return the number of elements.

Parameters:

• lst : LIST — List or iterable

Examples:

(List length (list 1 2 3)) => 3

(List ref n lst)

Return the element at index n (zero-based; negative counts from the end; coerced to INT); errors when n is unconvertible or out of range.

Parameters:

• n : INTEGER — Zero-based index (negative counts from the end)
• lst : LIST — List

Examples:

(List ref 1 (list 10 20 30)) => 20
(List ref -1 (list 10 20 30)) => 30

(List last lst)

Return the last element of a list.

Parameters:

• lst : LIST — Non-empty list

Examples:

(List last (list 1 2 3)) => 3

(List init lst)

Return all elements except the last.

Parameters:

• lst : LIST — Non-empty list

Examples:

(List init (list 1 2 3)) => (1 2)

(List append . args)

Concatenate zero or more lists.

Examples:

(List append (list 1 2) (list 3)) => (1 2 3)

(List prepend x lst)

Add an element to the front of a list.

Parameters:

• x : ANY — Element to prepend
• lst : LIST — List

Examples:

(List prepend 0 (list 1 2)) => (0 1 2)

(List reverse lst)

Reverse a list.

Parameters:

• lst : LIST — List or iterable

Examples:

(List reverse (list 1 2 3)) => (3 2 1)

(List flatten lst)

Recursively flatten nested lists into a single list.

Parameters:

• lst : LIST — Nested list

Examples:

(List flatten (list 1 (list 2 (list 3)))) => (1 2 3)

(List map f . lsts)

Apply a function to each element. Supports multiple lists.

Block form: (List map (x) body … lsts) – or (i x) for the 0-based index, then the element.

Parameters:

• f : CALLABLE — Function to apply
• lsts : LIST — One or more lists

Returns: LIST — New list

Examples:

(List map (fn (_ x) (* x 2)) (list 1 2 3)) => (2 4 6)
(List map + (list 1 2) (list 10 20)) => (11 22)

(List filter pred lst)

Return elements that satisfy a predicate.

Block form: (List filter (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List or iterable

Returns: LIST — Filtered list

Examples:

(List filter (fn (_ x) (< x 3)) (list 1 2 3 4)) => (1 2)

(List for-each f . lsts)

Apply a function to each element for side effects.

Block form: (List for-each (x) body … lsts) – or (i x) for the 0-based index, then the element.

Parameters:

• f : CALLABLE — Function to apply
• lsts : LIST — One or more lists

(List flat-map f lst)

Map then flatten one level.

Block form: (List flat-map (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• f : CALLABLE — Function returning a list
• lst : LIST — List or iterable

Examples:

(List flat-map (fn (_ x) (list x x)) (list 1 2)) => (1 1 2 2)

(List any? pred lst)

Return #t if any element satisfies the predicate.

Block form: (List any? (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List or iterable

Examples:

(List any? (fn (_ x) (< 2 x)) (list 1 2 3)) => #t

(List all? pred lst)

Return #t if all elements satisfy the predicate.

Block form: (List all? (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List or iterable

Examples:

(List all? (fn (_ x) (< 0 x)) (list 1 2 3)) => #t

(List none? pred lst)

Return #t if no element satisfies the predicate.

Block form: (List none? (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List or iterable

Examples:

(List none? (fn (_ x) (< 3 x)) (list 1 2 3)) => #t

(List empty? lst)

Return #t if the list is empty.

Parameters:

• lst : LIST — List

Examples:

(List empty? ()) => #t

(List reject pred lst)

Return elements that do NOT satisfy a predicate.

Block form: (List reject (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List

Returns: LIST — Filtered list

Examples:

(List reject (fn (_ x) (< x 3)) (list 1 2 3 4)) => (3 4)

(List min lst)

The smallest element (by <); errors on an empty list.

Parameters:

• lst : LIST — Non-empty list

Returns: ANY — Smallest element

Examples:

(List min (list 3 1 2)) => 1

(List max lst)

The largest element (by <); errors on an empty list.

Parameters:

• lst : LIST — Non-empty list

Returns: ANY — Largest element

Examples:

(List max (list 3 1 2)) => 3

(List sum lst)

Sum all elements of a list.

Parameters:

• lst : LIST — List of numbers

Returns: INTEGER — Sum

Examples:

(List sum (list 1 2 3)) => 6

(List product lst)

Multiply all elements of a list.

Parameters:

• lst : LIST — List of numbers

Returns: INTEGER — Product

Examples:

(List product (list 1 2 3 4)) => 24

(List find pred lst)

Return the first element satisfying a predicate, or nil.

Block form: (List find (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List or iterable

Examples:

(List find (fn (_ x) (< 1 x)) (list 1 2 3)) => 2

(List find-index pred lst)

Return the index of the first element satisfying a predicate.

Block form: (List find-index (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List or iterable

Returns: ANY — Zero-based index, or nil if not found

Examples:

(List find-index (fn (_ x) (< 1 x)) (list 1 2 3)) => 1

(List index-of x lst)

Return the index of the first occurrence of a value.

Parameters:

• x : ANY — Value to find
• lst : LIST — List

Returns: ANY — Zero-based index, or nil if not found

Examples:

(List index-of 20 (list 10 20 30)) => 1

(List includes? x lst)

Test if a list contains a value.

Parameters:

• x : ANY — Value to search for
• lst : LIST — List or iterable

Returns: BOOL — t if found

Examples:

(List includes? 2 (list 1 2 3)) => #t

(List count-if pred lst)

Count elements satisfying a predicate.

Block form: (List count-if (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List or iterable

Returns: INTEGER — Count of matching elements

Examples:

(List count-if (fn (_ x) (< 1 x)) (list 1 2 3)) => 2

(List take n lst)

Take the first n elements of a list (n coerced to INT).

Parameters:

• n : INTEGER — Number of elements
• lst : LIST — List

Examples:

(List take 2 (list 1 2 3)) => (1 2)

(List chunk n lst)

Split a list into successive n-element sublists; the last may be shorter.

Parameters:

• n : INTEGER — Chunk size (must be > 0)
• lst : LIST — List

Returns: LIST — List of chunks

Examples:

(List chunk 2 (list 1 2 3 4 5)) => ((1 2) (3 4) (5))

(List drop n lst)

Drop the first n elements of a list (n coerced to INT).

Parameters:

• n : INTEGER — Number of elements to skip
• lst : LIST — List

Examples:

(List drop 2 (list 1 2 3)) => (3)

(List take-while pred lst)

Take elements from the front while predicate holds.

Block form: (List take-while (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List

Examples:

(List take-while (fn (_ x) (< x 3)) (list 1 2 3 1)) => (1 2)

(List drop-while pred lst)

Drop elements from the front while predicate holds.

Block form: (List drop-while (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List

Examples:

(List drop-while (fn (_ x) (< x 3)) (list 1 2 3 1)) => (3 1)

(List split-at n lst)

Split a list at position n.

Parameters:

• n : INTEGER — Split position
• lst : LIST — List

Returns: LIST — Pair of (taken dropped)

Examples:

(List split-at 2 (list 1 2 3)) => ((1 2) (3))

(List slice start end lst)

Extract a slice from start to end – the slice convention: (start, end-exclusive).

Parameters:

• start : INTEGER — Start index (inclusive)
• end : INTEGER — End index (exclusive)
• lst : LIST — List

Examples:

(List slice 1 3 (list 10 20 30 40)) => (20 30)

(List sub start n lst)

Extract n elements from start – the sub convention: (start, length); the counted twin of slice.

Parameters:

• start : INTEGER — Start index (inclusive)
• n : INTEGER — Number of elements
• lst : LIST — List

Examples:

(List sub 1 2 (list 10 20 30 40)) => (20 30)

(List range start end)

Generate a list of integers from start to end (both coerced to INT).

Parameters:

• start : INTEGER — Start value (inclusive)
• end : INTEGER — End value (exclusive)

Returns: LIST — List of integers

Examples:

(List range 0 5) => (0 1 2 3 4)

(List repeat n x)

Create a list of n copies of a value (n coerced to INT); count first, matching (Str8 repeat n s).

Parameters:

• n : INTEGER — Number of repetitions
• x : ANY — Value to repeat

Returns: LIST — List of repeated values

Examples:

(List repeat 3 0) => (0 0 0)

(List times n f)

Apply a function to each index 0..n-1, collecting results (n coerced to INT). Count first, per the constructor-count rule (was (f n) before the V6 adjudication).

Block form: (List times n (x) body …) – or (i x) for the 0-based index, then the element.

Parameters:

• n : INTEGER — Number of iterations
• f : CALLABLE — Function: index -> value

Returns: LIST — List of results

Examples:

(List times 3 (fn (_ i) (* i i))) => (0 1 4)

(List unfold pred f g seed)

Build a list by repeatedly applying step and value functions to a seed.

Parameters:

• pred : CALLABLE — Stop predicate: seed -> boolean
• f : CALLABLE — Value function: seed -> element
• g : CALLABLE — Step function: seed -> next-seed
• seed : ANY — Initial seed value

Returns: LIST — Generated list

Examples:

(List unfold (fn (_ n) (< 3 n)) (fn (_ n) (* n n)) (fn (_ n) (+ n 1)) 1) => (1 4 9)

(List iterate f n x)

Generate n values by repeatedly applying f (n coerced to INT).

Block form: (List iterate (x) body … n x) – or (i x) for the 0-based index, then the element.

Parameters:

• f : CALLABLE — Step function
• n : INTEGER — Number of iterations
• x : ANY — Initial value

Returns: LIST — List of iterated values

Examples:

(List iterate (fn (_ x) (* x 2)) 4 1) => (1 2 4 8)

(List zip a b)

Pair up corresponding elements from two lists as assocs – the result is an alist, so it feeds Dict from-alist and the Assoc API directly.

Parameters:

• a : LIST — First elements (keys)
• b : LIST — Second elements (values)

Returns: LIST — Alist of (a . b) assocs

Examples:

(List zip (list 1 2) (list 7 8)) => ((1 . 7) (2 . 8))

(List zip-with f a b)

Combine corresponding elements from two lists using a function.

Block form: (List zip-with (a b) body … a b).

Parameters:

• f : CALLABLE — Combining function
• a : LIST — First list
• b : LIST — Second list

Returns: LIST — Combined list

Examples:

(List zip-with + (list 1 2) (list 10 20)) => (11 22)

(List unzip alist)

Invert zip: an alist of (a . b) assocs becomes a list of two lists.

Parameters:

• alist : LIST — Alist of (a . b) assocs

Returns: LIST — (firsts seconds)

Examples:

(List unzip (List zip (list 1 2) (list "a" "b"))) => ((1 2) ("a" "b"))

(List interleave a b)

Alternate elements from two lists, stopping at the shorter.

Parameters:

• a : LIST — First list
• b : LIST — Second list

Returns: LIST — (a1 b1 a2 b2 …)

Examples:

(List interleave (list 1 3) (list 2 4)) => (1 2 3 4)

(List partition pred lst)

Split a list into elements that match and don’t match a predicate.

Block form: (List partition (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• pred : CALLABLE — Predicate function
• lst : LIST — List

Examples:

(List partition (fn (_ x) (< x 3)) (list 1 2 3 4)) => ((1 2) (3 4))

(List group-by f lst)

Group list elements by a key function.

Block form: (List group-by (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• f : CALLABLE — Key function: element -> group key
• lst : LIST — List

Returns: LIST — Alist of (key . elements), keys in first-seen order

Examples:

(List group-by (fn (_ x) (< x 3)) (list 1 2 3 4)) => ((#t 1 2) (#f 3 4))

(List sort cmp lst)

Stable merge sort using a comparison function: equal-key elements keep their input order.

Block form: (List sort (a b) body … lst).

Parameters:

• cmp : CALLABLE — Comparison: (a b) -> #t if a comes strictly first
• lst : LIST — List or iterable

Examples:

(List sort < (list 3 1 2)) => (1 2 3)

(List sort-by f lst)

Sort by a key function (ascending).

Block form: (List sort-by (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• f : CALLABLE — Key function: element -> comparable value
• lst : LIST — List

Examples:

(List sort-by rest (list (pair 1 20) (pair 2 10))) => ((2 . 10) (1 . 20))

(List distinct lst)

Remove ALL duplicates (equal?), keeping each element’s first occurrence – unlike uniq, no sorting needed.

O(n^2) via equal?, so it works for every element type; hashable elements (symbols/strings/ints/chars) can dedupe O(n) through x/type/set instead.

Parameters:

• lst : LIST — List

Returns: LIST — lst without later duplicates

Examples:

(List distinct (list 1 2 1 3 2)) => (1 2 3)

(List uniq lst)

Remove consecutive duplicates from a sorted list.

Parameters:

• lst : LIST — Sorted list

Examples:

(List uniq (list 1 1 2 2 3)) => (1 2 3)

(List uniq-by f lst)

Remove consecutive duplicates by key function.

Block form: (List uniq-by (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• f : CALLABLE — Key function
• lst : LIST — Sorted list

Examples:

(List uniq-by first (list (list 1 10) (list 1 11) (list 2 12))) => ((1 10) (2 12))

(List intersperse sep lst)

Insert a separator between each element.

Parameters:

• sep : ANY — Separator element
• lst : LIST — List

Examples:

(List intersperse 0 (list 1 2 3)) => (1 0 2 0 3)

(List transpose lsts)

Transpose rows and columns of a list of lists.

Parameters:

• lsts : LIST — List of lists

Returns: LIST — Transposed list of lists

Examples:

(List transpose (list (list 1 2) (list 3 4))) => ((1 3) (2 4))

(List update n val lst)

Replace the element at index n (coerced to INT).

Parameters:

• n : INTEGER — Index to update
• val : ANY — New value
• lst : LIST — List

Examples:

(List update 1 20 (list 1 2 3)) => (1 20 3)

(List insert n val lst)

Insert a value at index n (coerced to INT; clamped: n<=0 prepends, n>=length appends).

Parameters:

• n : INTEGER — Insertion index
• val : ANY — Value to insert
• lst : LIST — List

Examples:

(List insert 1 20 (list 1 3)) => (1 20 3)

(List remove start n lst)

Remove n elements starting at index (both coerced to INT).

Parameters:

• start : INTEGER — Start index
• n : INTEGER — Number of elements to remove
• lst : LIST — List

Examples:

(List remove 1 2 (list 1 2 3 4)) => (1 4)

(List adjust n f lst)

Apply a function to the element at index n (coerced to INT).

Block form: (List adjust n (x) body … lst) – or (i x) for the 0-based index, then the element.

Parameters:

• n : INTEGER — Index to adjust
• f : CALLABLE — Transformation function
• lst : LIST — List

Examples:

(List adjust 1 (fn (_ x) (* x 10)) (list 1 2 3)) => (1 20 3)

(List list? x)

Test if a value is a proper list.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if proper list

Examples:

(List list? (list 1 2)) => #t
(List list? (pair 1 2)) => #f

(List second x)

Return the second element of a list.

Parameters:

• x : LIST — A list with at least two elements

Returns: ANY — The second element

Examples:

(List second (list 1 2 3)) => 2

(List third x)

Return the third element of a list.

Parameters:

• x : LIST — A list with at least three elements

Returns: ANY — The third element

Examples:

(List third (list 1 2 3)) => 3