kex docs Standard Library

List

type List<X>

An ordered, immutable sequence, written [1, 2, 3].

Lists are the default collection in Kex. Every operation answers with a new list rather than changing the receiver, so a chain of transformations is safe to read from either end.

let scores = [7, 2, 9, 4]
scores.filter { |n| n > 3 }      # => [7, 9, 4]
scores.sort                      # => [2, 4, 7, 9]
scores.map { |n| n * 10 }.sum    # => 220

Anything that might not be there — the first element, an element at an index, a search result — answers with an Optional, so an empty list is an ordinary case rather than a crash:

[].first.or(0)        # => 0
[1, 2].at(9).or(0)    # => 0

A list is Enumerable and Foldable, which is where map, filter, find, all? and reduce come from.

Examples

Building a report line by line

users
  .filter { |u| u.active? }
  .map { |u| "${u.name} <${u.email}>" }
  .join("\n")

Implements Monoid, Blankable, Enumerable, Foldable, Truthyable.

Methods

first

first : X?

Returns the first element wrapped in Just, or None if the list is empty.

Examples
[1, 2, 3].first   # => Just(1)
[].first          # => None

second

second : X?

Returns the second element wrapped in Just, or None if the list has fewer than two elements.

Examples
[1, 2, 3].second   # => Just(2)
[1].second         # => None

third

third : X?

Returns the third element wrapped in Just, or None if the list has fewer than three elements.

Examples
[1, 2, 3].third   # => Just(3)
[1, 2].third      # => None

rest

rest : [X]

Returns all elements after the first. Returns [] for an empty or single-element list.

Examples
[1, 2, 3].rest   # => [2, 3]
[1].rest         # => []
[].rest          # => []

last

last : X?

Returns the last element wrapped in Just, or None if the list is empty.

Examples
[1, 2, 3].last   # => Just(3)
[].last          # => None

count Foldable

count : Integer

Returns the number of elements. When given a predicate, returns the count of elements for which it holds.

Examples
[1, 2, 3].count              # => 3
[1, 2, 3, 4].count(~even?)   # => 2
count(pred: (X -> Bool)) -> Integer

Returns how many elements satisfy pred.

count(pred) is provided by the Enumerable trait.

Parameters
pred
the test applied to each element

Returns the number of matches

Examples
[1, 2, 3, 4].count(~even?)              # => 2
["a", "", "b"].count { |s| s.empty? }   # => 1

length

length : Integer

Returns the number of elements. The same as count, under the name String uses.

Returns the number of elements

Examples
[1, 2, 3].length   # => 3

empty?

empty? : Bool

Returns true if the list contains no elements.

Examples
[].empty?      # => true
[1, 2].empty?  # => false

find Foldable

find(pred: (X -> Bool)) -> X?

Returns the first element satisfying the predicate wrapped in Just, or None if no element matches.

find/any?/all? are provided by the Enumerable trait.

Parameters
pred
Examples
[1, 2, 3].find { |x| x > 1 }   # => Just(2)
[1, 2, 3].find { |x| x > 9 }   # => None

any? Foldable

any?(pred: (X -> Bool)) -> Bool

Returns true if at least one element satisfies the predicate.

Parameters
pred
Examples
[1, 2, 3].any? { |x| x > 2 }   # => true
[1, 2, 3].any? { |x| x > 9 }   # => false

all? Foldable

all?(pred: (X -> Bool)) -> Bool

Returns true if every element satisfies the predicate.

Parameters
pred
Examples
[1, 2, 3].all? { |x| x > 0 }   # => true
[1, 2, 3].all? { |x| x > 1 }   # => false

map Enumerable

map(f: (X -> Y)) -> [Y]

Transforms each element by applying f.

map/filter/each are provided by the Enumerable trait (in terms of reduce).

Parameters
f
Examples
[1, 2, 3].map { |x| x * 2 }   # => [2, 4, 6]

filter Enumerable

filter(pred: (X -> Bool)) -> [X]

Returns a new list containing only the elements for which pred is true.

Parameters
pred
Examples
[1, 2, 3, 4].filter { |x| x.even? }   # => [2, 4]

reject

reject(pred: (X -> Bool)) -> [X]

Returns a new list with all elements for which pred is true removed. The inverse of filter.

Parameters
pred
Examples
[1, 2, 3, 4].reject { |x| x.even? }   # => [1, 3]

each Foldable

each(f: (X -> Void)) -> Void

Calls f with each element for its side effects. Returns unit.

Parameters
f
Examples
[1, 2, 3].each { |x| IO.printLine(x) }

reduce Enumerable Foldable

reduce(acc: A, f: (A -> X -> A)) -> A

Folds the list from the left, starting with acc and combining each element via f.

Parameters
acc
initial accumulator value
f
Examples
[1, 2, 3].reduce(0) { |acc, x| acc + x }   # => 6
[1, 2, 3].reduce(1) { |acc, x| acc * x }   # => 6

flatMap Enumerable

flatMap(f: (X -> [Y])) -> [Y]

Maps each element to a list and concatenates the results.

Parameters
f
Examples
[1, 2, 3].flatMap { |n| [n, n * 10] }   # => [1, 10, 2, 20, 3, 30]

at

at(i: Integer) -> X?

Returns the element at position i (0-based) wrapped in Just, or None if the index is out of range.

Parameters
i
Examples
[10, 20, 30].at(1)   # => Just(20)
[10, 20, 30].at(9)   # => None

get

get(i: Integer) -> X?
get(i: Integer, default: X) -> X

Returns the element at position i (0-based), or None when the index is out of range. The same as at.

Parameters
i
the 0-based index

Returns the element, or None

Examples
[10, 20, 30].get(1)   # => Just(20)
[10, 20, 30].get(9)   # => None

contains?

contains?(elem: X) -> Bool

Returns true if elem is present in the list.

Parameters
elem
Examples
[1, 2, 3].contains?(2)   # => true
[1, 2, 3].contains?(9)   # => false

indexOf

indexOf(elem: X) -> Integer?

Returns true if the first index at which elem appears, wrapped in Just, or None if the element is not present.

Parameters
elem
Examples
[10, 20, 30].indexOf(20)   # => Just(1)
[10, 20, 30].indexOf(99)   # => None

findIndex

findIndex(pred: (X -> Bool)) -> Integer?

Returns the index of the first element satisfying pred, wrapped in Just, or None if none does. The predicate counterpart of indexOf, which searches by value.

Parameters
pred
Examples
[10, 25, 30].findIndex { |n| n > 20 }   # => Just(1)
[10, 25, 30].findIndex { |n| n > 99 }   # => None

takeWhile

takeWhile(pred: (X -> Bool)) -> [X]

Returns the longest leading run of elements satisfying pred. Stops at the first element that does not, so it is not filter — later matches are dropped with everything after the first failure.

Parameters
pred
Examples
[1, 2, 9, 1].takeWhile { |n| n < 5 }   # => [1, 2]

dropWhile

dropWhile(pred: (X -> Bool)) -> [X]

Returns what is left after takeWhile — everything from the first element that does not satisfy pred onwards.

Parameters
pred
Examples
[1, 2, 9, 1].dropWhile { |n| n < 5 }   # => [9, 1]

uniq

uniq : [X]

Returns a new list with duplicate elements removed, preserving the first occurrence of each element.

Examples
[1, 2, 3, 2, 1].uniq   # => [1, 2, 3]

partition

partition(pred: (X -> Bool)) -> ([X], [X])

Splits the list into two lists: those for which pred is true (first) and those for which it is false (second).

Parameters
pred
Examples
[1, 2, 3, 4].partition { |n| n.even? }   # => ([2, 4], [1, 3])

collect Enumerable

collect(f: (X -> Y?)) -> [Y]

Maps each element through f (which returns an Optional), keeping and unwrapping the Just(y) results and dropping None. Filter + map fused.

Parameters
f
Examples
[1, 2, 3, 4].collect { |n| n > 2 then Just(n * 10) else None }   # => [30, 40]

take

take(n: Integer) -> [X]

Returns the first n elements.

Parameters
n
Examples
[1, 2, 3, 4, 5].take(3)   # => [1, 2, 3]

drop

drop(n: Integer) -> [X]

Drops the first n elements.

Parameters
n
Examples
[1, 2, 3, 4, 5].drop(2)   # => [3, 4, 5]

push

push(x: X) -> [X]

Returns a new list with x appended at the end.

Parameters
x
Examples
[1, 2].push(3)   # => [1, 2, 3]

reverse

reverse : [X]

Returns the elements in reverse order.

Examples
[1, 2, 3].reverse   # => [3, 2, 1]

zip

zip(other: [Y]) -> [(X, Y)]

Pairs each element of this list with the corresponding element of other. Stops at the end of the shorter list.

Parameters
other
Examples
[1, 2, 3].zip(["a", "b", "c"])   # => [(1, "a"), (2, "b"), (3, "c")]

flatten

flatten : [X]

Flattens exactly one level of nesting. Only valid on lists of lists.

Examples
[[1, 2], [3, 4]].flatten   # => [1, 2, 3, 4]

sort

sort : [X]

Returns the elements sorted in ascending natural order.

Examples
[3, 1, 2].sort   # => [1, 2, 3]
sort(comp: (X -> X -> Bool)) -> [X]

Returns the elements sorted using a custom comparator. comp should return true when its first argument should come before its second.

Parameters
comp
Examples
[3, 1, 2].sort { |a, b| a > b }   # => [3, 2, 1]

min

min(f: (X -> Y)) -> X?

Returns the element with the smallest f key wrapped in Just, or None for an empty list.

Parameters
f
Examples
["hey", "hi"].min { |s| s.count }   # => Just("hi")

max

max(f: (X -> Y)) -> X?

Returns the element with the largest f key wrapped in Just, or None for an empty list.

Parameters
f
Examples
["hey", "hi"].max { |s| s.count }   # => Just("hey")

sum

sum(f: (X -> Number)) -> Number

Maps each element through f and sums the results.

Parameters
f
Examples
["hello", "hi"].sum { |s| s.count }   # => 7

join

join(sep: String) -> String
join : String

Receiver is [X], not [String | Char]: the intrinsic renders whatever it is given, so [1, 2].join(", ") is "1, 2" on both backends. The narrower receiver only ever fired once element types became precise enough to catch it — until then map/filter handed join an unknown element type and the restriction checked nothing. Concatenates all elements, placing sep between each adjacent pair. With no separator the elements are joined directly.

Parameters
sep
Examples
["hello", "world", "kex"].join(", ")   # => "hello, world, kex"
["a", "b", "c"].join                   # => "abc"

On [Number]

sum

sum : Number

Sums all elements. Returns 0 for an empty list.

Examples
[1, 2, 3].sum   # => 6
[].sum          # => 0

product

product : Number

Multiplies all elements. Returns 1 for an empty list.

Examples
[1, 2, 3].product   # => 6
[].product          # => 1
product(f: (X -> Number)) -> Number

Maps each element through f and multiplies the results.

Parameters
f
Examples
[[1,2],[3,4]].product { |pair| pair.first.or(1) }   # => 3

min

min : X?

Returns the smallest element wrapped in Just, or None for an empty list.

Examples
[3, 1, 2].min   # => Just(1)
[].min          # => None

max

max : X?

Returns the largest element wrapped in Just, or None for an empty list.

Examples
[3, 1, 2].max   # => Just(3)
[].max          # => None

From Monoid

repeat
Combines this value with itself n times.

From Enumerable

mapIndexed
Applies f to each item and its 0-based position, and collects the results into a list.

From Foldable

eachIndexed
Calls f with each item and its 0-based position, for its side effects.

Defined in other modules

Algebra
identity, combine
Blankable
blank?
Truthyable
truthy?