List Operations

Functions for manipulating lists, including access, transformation, combination, and aggregation.

Element Access

head

Signature: head(list: List[T]) -> Option[T]

Returns the first element of a list, or None if the list is empty.

head_or

Signature: head_or(default: T, list: List[T]) -> T

Returns the first element, or a default value if the list is empty. The data-last argument order makes this function pipe-friendly.

tail

Signature: tail(list: List[T]) -> List[T]

Returns all elements except the first. Returns an empty list if the input has 0 or 1 elements.

last

Signature: last(list: List[T]) -> Option[T]

Returns the last element of a list, or None if the list is empty.

init

Signature: init(list: List[T]) -> List[T]

Returns all elements except the last. Returns an empty list if the input has 0 or 1 elements.

get_at

Signature: get_at(index: Int, list: List[T]) -> Option[T]

Returns the element at the given index (0-based), or None if the index is out of bounds. The data-last argument order makes this function pipe-friendly.

List Construction

append

Signature: append(element: T, list: List[T]) -> List[T]

Returns a new list with the element added to the end. The data-last argument order makes this function pipe-friendly.

concat

Signature: concat(list2: List[T], list1: List[T]) -> List[T]

Concatenates two lists into a single list. The data-last argument order makes this function pipe-friendly: list1 | concat(list2) appends list2 to list1.

reverse

Signature: reverse(list: List[T]) -> List[T]

Returns a new list with elements in reverse order.

take

Signature: take(n: Int, list: List[T]) -> List[T]

Returns the first n elements of the list. If n exceeds the list length, returns the entire list. The data-last argument order makes this function pipe-friendly.

drop

Signature: drop(n: Int, list: List[T]) -> List[T]

Returns the list with the first n elements removed. If n exceeds the list length, returns an empty list. The data-last argument order makes this function pipe-friendly.

range

Signature: range(start: Int, end: Int) -> List[Int]

Creates a list of integers from start (inclusive) to end (exclusive).

Higher-Order Functions

These functions are effect-polymorphic—they propagate any effects from their callback functions. See the Effects Guide for details.

map

Signature: map[A, B, effect E](f: Fn(A) -> B with E, list: List[A]) -> List[B] with ECurried: map(f: Fn(A) -> B) -> Fn(List[A]) -> List[B]

Applies a function to every element of the list, returning a new list of results.

If the callback has effects (IO, Quantum, etc.), those effects propagate to the caller.

When called with just a function, returns a partially applied function for use in pipelines:

[1, 2, 3] | map(fn(x: Int) -> x * 2)  -- [2, 4, 6]

filter

Signature: filter[T, effect E](predicate: Fn(T) -> Bool with E, list: List[T]) -> List[T] with ECurried: filter(predicate: Fn(T) -> Bool) -> Fn(List[T]) -> List[T]

Returns a new list containing only elements for which the predicate returns true.

If the predicate has effects, those effects propagate to the caller.

When called with just a predicate, returns a partially applied function for use in pipelines:

[1, 2, 3, 4] | filter(fn(x: Int) -> x % 2 == 0)  -- [2, 4]

fold

Signature: fold[A, B, effect E](initial: B, f: Fn(B, A) -> B with E, list: List[A]) -> B with E

Reduces a list to a single value by repeatedly applying a function. Also known as "reduce" or "foldl" in other languages.

The function f takes an accumulator and the current element, returning a new accumulator value. If f has effects, those effects propagate to the caller.

all

Signature: all[T, effect E](predicate: Fn(T) -> Bool with E, list: List[T]) -> Bool with E

Returns true if all elements satisfy the predicate. Returns true for an empty list.

-- Check if all numbers are positive
[1, 2, 3, 4] | all(fn(x: Int) -> x > 0)  -- true
[1, -2, 3] | all(fn(x: Int) -> x > 0)    -- false

Useful in refinement type predicates:

type AllPositive = List[Int] as xs | all(fn(x: Int) -> x > 0, xs)

any

Signature: any[T, effect E](predicate: Fn(T) -> Bool with E, list: List[T]) -> Bool with E

Returns true if any element satisfies the predicate. Returns false for an empty list.

-- Check if any number is negative
[1, 2, 3] | any(fn(x: Int) -> x < 0)   -- false
[1, -2, 3] | any(fn(x: Int) -> x < 0)  -- true

Aggregation

sum

Signature: sum(list: List[Int]) -> Int

Returns the sum of all integers in the list.

sumf

Signature: sumf(list: List[Float]) -> Float

Returns the sum of all floats in the list.

mean

Signature: mean(list: List[Any]) -> Float

Returns the arithmetic mean (average) of the numeric values in the list.

counts

Signature: counts(list: List[T]) -> Map[String, Int]

Counts occurrences of each unique element in the list, returning a map from string representation to count.

most_common

Signature: most_common(list: List[T]) -> T

Returns the element that appears most frequently in the list.

Option Operations

cat_options

Signature: cat_options(list: List[Option[T]]) -> List[T]

Filters a list of options, keeping only the Some values and extracting their contents.

Common Patterns

Pipeline Processing

Kettle supports the | pipe operator for chaining operations:

Combining Transformations

Function Summary

Function	Signature	Description
head	List[T] -> Option[T]	First element
head_or	(T, List[T]) -> T	First element or default
tail	List[T] -> List[T]	All but first
last	List[T] -> Option[T]	Last element
init	List[T] -> List[T]	All but last
get_at	(Int, List[T]) -> Option[T]	Element at index
append	(T, List[T]) -> List[T]	Add to end
concat	(List[T], List[T]) -> List[T]	Combine lists
reverse	List[T] -> List[T]	Reverse order
take	(Int, List[T]) -> List[T]	First n elements
drop	(Int, List[T]) -> List[T]	Skip first n
range	(Int, Int) -> List[Int]	Integer range
map	(Fn(A) -> B with E, List[A]) -> List[B] with E	Transform each (effect-polymorphic)
filter	(Fn(T) -> Bool with E, List[T]) -> List[T] with E	Keep matching (effect-polymorphic)
fold	(B, Fn(B, A) -> B with E, List[A]) -> B with E	Reduce to value (effect-polymorphic)
sum	List[Int] -> Int	Sum integers
sumf	List[Float] -> Float	Sum floats
mean	List[Any] -> Float	Average
counts	List[T] -> Map[String, Int]	Count occurrences
most_common	List[T] -> T	Most frequent
cat_options	List[Option[T]] -> List[T]	Filter Somes

See Also

• Types & Conversions - Working with basic types
• Quantum Operations - Quantum computing functions
• I/O & Environment - File and system operations