list

CUE v0.18.0

Package list contains functions for manipulating and examining lists.

Schemas

Ascending

Ascending: {
	Comparer
	T:    number | string
	x:    T
	y:    T
	less: x < y
}

Ascending defines a Comparer to sort comparable values in increasing order.

Example: list.Sort(a, list.Ascending)

Comparer

Comparer: {
	T:    _
	x:    T
	y:    T
	less: bool // true if x < y
}

A Comparer specifies whether one value is strictly less than another value.

Descending

Descending: {
	Comparer
	T:    number | string
	x:    T
	y:    T
	less: x > y
}

Descending defines a Comparer to sort comparable values in decreasing order.

Example: list.Sort(a, list.Descending)

Functions

Avg

Avg: func(xs: [...number]) -> number

Avg returns the average value of a non empty list xs.

Concat

Concat: func(a: [...]) -> [...]

Concat takes a list of lists and concatenates them.

Concat([a, b, c]) is equivalent to

	[for x in a {x}, for x in b {x}, for x in c {x}]

Contains

Contains: func(a: [...], v: _) -> bool

Contains reports whether v is contained in a. The value must be a comparable and concrete value. For non-concrete values, you can use [MatchN] with >0.

Drop

Drop: func(x: [...], n: int) -> [...]

Drop reports the suffix of list x after the first n elements, or [] if n > len(x).

For instance:

	Drop([1, 2, 3, 4], 2)

results in

	[3, 4]

FlattenN

FlattenN: func(xs: _, depth: int) -> [...]

FlattenN reports a flattened sequence of the list xs by expanding any elements depth levels deep. If depth is negative all elements are expanded.

For instance:

	FlattenN([1, [[2, 3], []], [4]], 1)

results in

	[1, [2, 3], [], 4]

IsSorted

IsSorted: func(list: [...], cmp: Comparer) -> bool

IsSorted tests whether a list is sorted.

See Sort for an example comparator.

IsSortedStrings validator

validator form

validator([...string])

call form

func(a: [...string]) -> bool

IsSortedStrings tests whether a list is a sorted list of strings.

MatchN validator

validator form

func(n: _ @schema(), matchValue: _ @schema()) -> validator([...])

call form

func(list: [...], n: _ @schema(), matchValue: _ @schema()) -> bool

MatchN is a validator that checks that the number of elements in the given list that unifies with the schema "matchValue" matches "n". "n" may be a number constraint and does not have to be a concrete number. Likewise, "matchValue" will usually be a non-concrete value.

Max

Max: func(xs: [...number]) -> number

Max returns the maximum value of a non empty list xs.

MaxItems validator

validator form

func(n: int) -> validator([...])

call form

func(list: [...], n: int) -> bool

MaxItems reports whether a has at most n items.

Min

Min: func(xs: [...number]) -> number

Min returns the minimum value of a non empty list xs.

MinItems validator

validator form

func(n: int) -> validator([...])

call form

func(list: [...], n: int) -> bool

MinItems reports whether a has at least n items.

Product

Product: func(xs: [...number]) -> number

Product returns the product of a non empty list xs.

Range

Range: func(start: number, limit: number, step: number) -> [...number]

Range generates a list of numbers using a start value, a limit value, and a step value.

For instance:

	Range(0, 5, 2)

results in

	[0, 2, 4]

Repeat

Repeat: func(x: [...], count: int) -> [...]

Repeat returns a new list consisting of count copies of list x.

For instance:

	Repeat([1, 2], 2)

results in

	[1, 2, 1, 2]

Reverse

Reverse: func(x: [...]) -> [...]

Reverse reverses a list.

For instance:

	Reverse([1, 2, 3, 4])

results in

	[4, 3, 2, 1]

Slice

Slice: func(x: [...], i: int, j: int) -> [...]

Slice extracts the consecutive elements from list x starting from position i up till, but not including, position j, where 0 <= i < j <= len(x).

For instance:

	Slice([1, 2, 3, 4], 1, 3)

results in

	[2, 3]

Sort

Sort: func(list: [...], cmp: Comparer) -> [...]

Sort sorts data while keeping the original order of equal elements. It does O(n*log(n)) comparisons.

cmp is a struct of the form {T: _, x: T, y: T, less: bool}, where less should reflect x < y.

Example:

	Sort([2, 3, 1], list.Ascending)

	Sort([{a: 2}, {a: 3}, {a: 1}], {x: {}, y: {}, less: x.a < y.a})

SortStable

SortStable: func(list: [...], cmp: Comparer) -> [...]

Deprecated: use [Sort], which is always stable

SortStrings

SortStrings: func(a: [...string]) -> [...string]

SortStrings sorts a list of strings in increasing order.

Sum

Sum: func(xs: [...number]) -> number

Sum returns the sum of a list non empty xs.

Take

Take: func(x: [...], n: int) -> [...]

Take reports the prefix of length n of list x, or x itself if n > len(x).

For instance:

	Take([1, 2, 3, 4], 2)

results in

	[1, 2]

UniqueItems validator

validator form

validator([...])

call form

func(a: [...]) -> bool

UniqueItems reports whether all elements in the list are unique.