← Index

x/type/list

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

The list/sequence operations as static methods; core/list.x keeps the low-level layer (fold/map/filter globals + %-helpers) it is 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

(List iter lst)

An iterator over the list’s elements.

Parameters:

• lst : LIST — List to iterate

Returns: ITER — Iterator

(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

(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

(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

(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 : INT — Zero-based index (negative counts from the end)
• lst : LIST — List

(List last lst)

Return the last element of a list.

Parameters:

• lst : LIST — Non-empty list

(List init lst)

Return all elements except the last.

Parameters:

• lst : LIST — Non-empty list

(List append . args)

Concatenate zero or more lists.

(List prepend x lst)

Add an element to the front of a list.

Parameters:

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

(List reverse lst)

Reverse a list.

Parameters:

• lst : LIST — List or iterable

(List flatten lst)

Recursively flatten nested lists into a single list.

Parameters:

• lst : LIST — Nested list

(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

(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

(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

(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

(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

(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

(List empty? lst)

Return #t if the list is empty.

Parameters:

• lst : LIST — List

(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

(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: INT — Sum

(List product lst)

Multiply all elements of a list.

Parameters:

• lst : LIST — List of numbers

Returns: INT — Product

(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

(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

(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

(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

(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: INT — Count of matching elements

(List take n lst)

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

Parameters:

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

(List chunk n lst)

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

Parameters:

• n : INT — 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 : INT — Number of elements to skip
• lst : LIST — List

(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

(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

(List split-at n lst)

Split a list at position n.

Parameters:

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

Returns: LIST — Pair of (taken dropped)

(List slice start end lst)

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

Parameters:

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

(List sub start n lst)

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

Parameters:

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

(List range start end)

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

Parameters:

• start : INT — Start value (inclusive)
• end : INT — 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 : INT — Number of repetitions
• x : ANY — Value to repeat

Returns: LIST — List of repeated values

(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 : INT — Number of iterations
• f : CALLABLE — Function: index -> value

Returns: LIST — List of results

(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

(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 : INT — Number of iterations
• x : ANY — Initial value

Returns: LIST — List of iterated values

(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

(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

(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

(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

(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

(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

(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

(List intersperse sep lst)

Insert a separator between each element.

Parameters:

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

(List transpose lsts)

Transpose rows and columns of a list of lists.

Parameters:

• lsts : LIST — List of lists

Returns: LIST — Transposed list of lists

(List update n val lst)

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

Parameters:

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

(List insert n val lst)

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

Parameters:

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

(List remove start n lst)

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

Parameters:

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

(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 : INT — Index to adjust
• f : CALLABLE — Transformation function
• lst : LIST — List

(List list? x)

Test if a value is a proper list.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if proper list

(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

(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