← Back to the index

Module std/list.vv

The list module provides utilities for working with lists (arrays). Lists are ordered, mutable collections of elements of any type.

Example:

import list from "std/list.vv"

let l = [1, 2, 3]
list.push(l, 4)
let doubled = list.map(l, fun (i, x) return x * 2 end)

Table of Contents

Exports

fun push(l, v) extern "native"

Adds a value to the end of a list. Returns the modified list.

Example:

let l = [1, 2]
list.push(l, 3) // [1, 2, 3]

fun pop(l) extern "native"

Removes and returns the last element from a list.

Example:

let l = [1, 2, 3]
let v = list.pop(l) // 3
// l is now [1, 2]

fun shift(l) extern "native"

Removes and returns the first element from a list.

Example:

let l = [1, 2, 3]
let v = list.shift(l) // 1
// l is now [2, 3]

fun unshift(l, v) extern "native"

Adds a value to the beginning of a list. Returns the modified list.

Example:

let l = [2, 3]
list.unshift(l, 1) // [1, 2, 3]

fun replace(xs, from_pattern, to_pattern) extern "native"

Replaces occurrences of a sub-list pattern within a list with another pattern. Returns a new list.

Example:

let l = [1, 2, 3, 2, 3, 4]
let r = list.replace(l, [2, 3], [5, 6]) // [1, 5, 6, 5, 6, 4]

fun each(xs, f)

Iterates over each element in a list and applies a function to it. The applied function receives the index and the element as arguments.

Example:

let l = ["a", "b"]
list.each(l, fun (i, x) console.print(x) end)

fun map(xs, f)

Returns a new list with the results of applying a function to every element. The applied function receives the index and the element as arguments.

Example:

let l = [1, 2, 3]
list.map(l, fun (i, x) return x * 2 end) // [2, 4, 6]

fun filter(xs, f)

Returns a new list containing only elements that satisfy the provided testing function. The testing function receives the index and the element as arguments.

Example:

let l = [1, 2, 3, 4]
list.filter(l, fun (i, x) return x % 2 == 0 end) // [2, 4]

fun reverse(xs)

Returns a new list with the elements of the original list in reverse order.

Example:

let l = [1, 2, 3]
list.reverse(l) // [3, 2, 1]

fun fold_left(xs, init, f)

Applies a function against an accumulator and each element (from left to right) to reduce it to a single value. The applied function receives the accumulator, the index, and the element as arguments.

Example:

let l = [1, 2, 3]
list.fold_left(l, 0, fun (acc, i, x) return acc + x end) // 6

fun fold_right(xs, init, f)

Applies a function against an accumulator and each element (from right to left) to reduce it to a single value. The applied function receives the accumulator, the index, and the element as arguments.

Example:

let l = ["a", "b", "c"]
list.fold_right(l, "", fun (acc, i, x) return acc + x end) // "cba"

Returns the first element of a list.

Example:

let l = [1, 2, 3]
list.head(l) // 1

fun tail(xs)

Returns a new list containing all elements except the first one.

Example:

let l = [1, 2, 3]
list.tail(l) // [2, 3]

fun flat(xs)

Flattens a list of lists into a single continuous list. Note: Only flattens exactly one level deep.

Example:

let l = [[1, 2], [3, 4]]
list.flat(l) // [1, 2, 3, 4]

fun flat_map(xs, f)

Maps a function over a list and optionally flattens the result by one level.

Example:

let l = [1, 2]
list.flat_map(l, fun (i, x) return [x, x * 2] end) // [1, 2, 2, 4]

fun join(xs, sep)

Joins all elements of a list, placing the provided separator between each element.

Example:

let l = [1, 2, 3]
list.join(l, 0) // [1, 0, 2, 0, 3]

fun init(n, f)

Creates a list of size n, initializing each element using the function f(index).

Example:

list.init(3, fun (i) return i * 2 end) // [0, 2, 4]

fun max(xs, f)

Returns the element that produces the maximum value when f(element) is applied.

Example:

let l = [1, 5, 2]
list.max(l, fun (x) return x end) // 5

fun min(xs, f)

Returns the element that produces the minimum value when f(element) is applied.

Example:

let l = [1, 5, 2]
list.min(l, fun (x) return x end) // 1

fun partition(xs, f)

Splits a list into two lists: one containing elements that satisfy the condition f(index, element), and another for elements that don't.

Example:

let l = [1, 2, 3, 4]
list.partition(l, fun (i, x) return x % 2 == 0 end) // [[2, 4], [1, 3]]

fun zip(xs, ys)

Pairs elements of two lists based on their index. The longer list is truncated to the shorter list's length.

Example:

let a = [1, 2]
let b = ["a", "b"]
list.zip(a, b) // [[1, "a"], [2, "b"]]

fun every(xs, f)

Checks if all elements in the list satisfy the applied condition f(index, element).

Example:

let l = [2, 4, 6]
list.every(l, fun (i, x) return x % 2 == 0 end) // true

fun some(xs, f)

Checks if at least one element in the list satisfies the applied condition f(index, element).

Example:

let l = [1, 2, 3]
list.some(l, fun (i, x) return x % 2 == 0 end) // true

fun find(xs, f)

Returns the first element in the list that satisfies the condition f(index, element).

Example:

let l = [1, 2, 3]
list.find(l, fun (i, x) return x % 2 == 0 end) // 2

fun find_index(xs, f)

Returns the index of the first element in the list that satisfies the condition f(index, element). Returns -1 if no such element is found.

Example:

let l = [1, 2, 3]
list.find_index(l, fun (i, x) return x % 2 == 0 end) // 1

fun find_pattern(xs, ys)

Searches for a sub-list pattern within the list and returns the start index. Returns -1 if not found.

Example:

let l = [1, 2, 3, 4]
list.find_pattern(l, [2, 3]) // 1

fun take_while(xs, f)

Takes elements from the beginning of the list as long as they satisfy the condition f(index, element). Stops at the first element that fails the condition.

Example:

let l = [1, 2, 3, 4]
list.take_while(l, fun (i, x) return x < 3 end) // [1, 2]

fun drop_while(xs, f)

Drops elements from the beginning of the list as long as they satisfy the condition f(index, element). Returns the remaining elements starting from the first element that fails the condition.

Example:

let l = [1, 2, 3, 4]
list.drop_while(l, fun (i, x) return x < 3 end) // [3, 4]