List — essence

Ordered collections of items: reading, searching, transforming, sorting and totalling, each method returning a new List.

Taught on: Lists and Iteration.

At a glance

Declared: namespace List<infer ItemType> for List<ItemType>
Conforms to: Printable where ItemType is Printable
Equatable where ItemType is Equatable
Comparable where ItemType is Comparable
Refinements: type NonEmptyList<ItemType> = List<ItemType> where @::hasItems()A List proven to have an item in it, as a checked refinement of List.
Views: NestedList for List<List<ItemType>> in Nested lists
NonEmptyNestedList for NonEmptyList<NonEmptyList<ItemType>> in Nested lists
OptionalList for List<Optional<ItemType>> in Lists of Optionals and Results
ResultList for List<Result<ValueType, FailureType>> in Lists of Optionals and Results
GroupedList for List<ItemType> in Grouping into a Dictionary
GroupedNonEmptyList for NonEmptyList<ItemType> in Grouping into a Dictionary
IntegerList for List<Integer> in Lists of numbers: totals
RationalList for List<Rational> in Lists of numbers: totals
NumberList for List<Scalar> in Lists of numbers: totals
KeyedNumberList for List<ItemType> in Lists of numbers: totals
NonEmptyIntegerList for NonEmptyList<Integer> in Lists of numbers: statistics
NonEmptyRationalList for NonEmptyList<Rational> in Lists of numbers: statistics
NonEmptyNumberList for NonEmptyList<Scalar> in Lists of numbers: statistics
NonEmptyKeyedNumberList for NonEmptyList<ItemType> in Lists of numbers: statistics
A view is a namespace for a narrower type. A value of that type has the view's methods on top of its own.
Modes: SortOrderWhich way sort runs: #Ascending from the lowest, or #Descending from the highest.

Creating

repeat

on List

Answers a List holding the given item the given number of times.

A count of zero or less answers the empty List. A count proven to be above zero answers a List with something in it.

static repeat(_ item: ItemType, times count: Integer) -> List<ItemType>

Answers a List holding the given item the given number of times.

A count of zero or less answers the empty List.

NameTypeDescription

_ItemTypethe item to repeat

timesIntegerhow many copies the List holds

Returns the List of repeated items.

Example

expect List.repeat("ho", times 3)::is(["ho", "ho", "ho"])
expect List.repeat("ho", times 0)::isEmpty()

static repeat(
	_ item: ItemType,
	times count: PositiveInteger,
) -> NonEmptyList<ItemType>

Answers a List holding the given item a number of times proven to be above zero.

At least one copy is held, so the answer certainly has something in it.

NameTypeDescription

_ItemTypethe item to repeat

timesPositiveIntegerhow many copies the List holds, proven to be above zero

Returns the List of repeated items, which is never empty.

Example

constant row: NonEmptyList<String> = List.repeat("-", times 3)

expect row::is(["-", "-", "-"])

of

on List

Answers the Integers of a range, counting up or down, one step at a time.

The through: and upTo: entries count up, and the downTo: entry counts down. The by: entries move by the given step instead of by one. The end is included where the label is through: or downTo:, and excluded where it is upTo:.

Returns the List of Integers.

static of(integersFrom start: Integer, through end: Integer) -> List<Integer>

Answers the Integers from one value up through another, both included.

The count only runs up. An end below the start answers the empty List. To count down, use the downTo: entry.

NameTypeDescription

integersFromIntegerthe first Integer of the List

throughIntegerthe last Integer of the List, which is included

Returns the List of Integers. It is empty when the end is below the start.

Example

expect List.of(integersFrom 1, through 4)::is([1, 2, 3, 4])
expect List.of(integersFrom 4, through 1)::isEmpty()

static of(integersFrom start: Integer, upTo end: Integer) -> List<Integer>

Answers the Integers from one value up to, but not including, another.

The count only runs up. An end at or below the start answers the empty List.

NameTypeDescription

integersFromIntegerthe first Integer of the List

upToIntegerthe Integer the List stops before

Returns the List of Integers. It is empty when the end is not above the start.

Example

expect List.of(integersFrom 0, upTo 3)::is([0, 1, 2])
expect List.of(integersFrom 0, upTo 0)::isEmpty()

static of(
	integersFrom start: Integer,
	downTo end: Integer,
) -> NonEmptyList<Integer>

Answers the Integers from one value down through another, both included.

The count only runs down. The first value is always answered, so an end above the start answers a List holding that value alone. The answer certainly has something in it.

NameTypeDescription

integersFromIntegerthe first Integer of the List

downToIntegerthe last Integer of the List, which is included

Returns the List of Integers, which is never empty.

Example

expect List.of(integersFrom 3, downTo 1)::is([3, 2, 1])
expect List.of(integersFrom 3, downTo 9)::is([3])

static of(
	integersFrom start: Integer,
	through end: Integer,
	by step: NonZeroInteger,
) -> List<Integer>

Answers the Integers from one value through another, moving by the given step.

The step is added each turn, and the walk stops where a step passes the end. A step that moves away from the end answers the empty List.

NameTypeDescription

integersFromIntegerthe first Integer of the List

throughIntegerthe value the walk stops at or before, which is included when a step reaches it

byNonZeroIntegerhow far each step moves, which is never zero

Returns the List of Integers. It is empty when the step moves away from the end.

Example

expect List.of(integersFrom 0, through 9, by 3)::is([0, 3, 6, 9])
expect List.of(integersFrom 9, through 0, by -3)::is([9, 6, 3, 0])

static of(
	integersFrom start: Integer,
	upTo end: Integer,
	by step: NonZeroInteger,
) -> List<Integer>

Answers the Integers from one value up to, but not including, another, moving by the given step.

The step is added each turn, and the walk stops before the end. A step that moves away from the end answers the empty List.

NameTypeDescription

integersFromIntegerthe first Integer of the List

upToIntegerthe Integer the walk stops before

byNonZeroIntegerhow far each step moves, which is never zero

Returns the List of Integers. It is empty when the step moves away from the end.

Example

expect List.of(integersFrom 0, upTo 9, by 3)::is([0, 3, 6])
expect List.of(integersFrom 9, upTo 0, by -3)::is([9, 6, 3])

static of(
	integersFrom start: Integer,
	downTo end: Integer,
	by step: NonZeroInteger,
) -> NonEmptyList<Integer>

Answers the Integers from one value down through another, moving by the given step.

The step is added each turn, and the walk stops where a step passes the end. The first value is always answered, so a step that moves away from the end answers a List holding that value alone.

NameTypeDescription

integersFromIntegerthe first Integer of the List

downToIntegerthe value the walk stops at or before, which is included when a step reaches it

byNonZeroIntegerhow far each step moves, which is never zero

Returns the List of Integers, which is never empty.

Example

expect List.of(integersFrom 9, downTo 0, by -3)::is([9, 6, 3, 0])
expect List.of(integersFrom 9, downTo 0, by 3)::is([9])

Equality, ordering and printing

is

on List<ItemType>

is<ItemType is Equatable>(_ other: List<ItemType>) -> Boolean

Answers whether the two Lists hold the same items in the same order.

Each pair of items is compared with the items' own is. The Method is available whenever the items conform to Equatable.

NameTypeDescription

_List<ItemType>the List to compare with

Returns true when the Lists are equal.

Example

expect ["Ada", "Grace"]::is(["Ada", "Grace"])
expect ["Ada", "Grace"]::is(["Grace", "Ada"])::negate()

compare

on List<ItemType>

compare<ItemType is Comparable>(to other: List<ItemType>) -> Ordering

Answers how the List orders against another one, comparing them lexicographically.

The first differing pair of items decides. On an equal prefix the shorter List comes first. The Method is available whenever the items conform to Comparable.

NameTypeDescription

toList<ItemType>the List to compare with

Returns Ordering#Less, Ordering#Equal or Ordering#Greater.

Example

expect [1, 2, 9]::compare(to [1, 3])::is(#Less)
expect [1, 2]::compare(to [1, 2, 3])::is(#Less)

toString

on List<ItemType>

toString<ItemType is Printable>() -> String

Answers the List and its items as a String, in the form [1, 2, 3].

Each item is rendered by its own toString, and a String item is quoted: ["a", "b"] answers ["a", "b"]. A String prints bare on its own and quoted inside a structure. The empty List answers []. The Method is available whenever the items conform to Printable.

Returns the String representation of the List.

Example

expect [1, 2, 3]::toString()::is("[1, 2, 3]")
expect ["a", "b"]::toString()::is("[\"a\", \"b\"]")

isNot

on List<ItemType> · provided by Equatable where ItemType is Equatable

isNot(_ other: List<ItemType>) -> Boolean

Answers whether the values differ.

NameTypeDescription

_List<ItemType>the value to compare with

Returns true when the values differ.

Example

expect "Ada"::isNot("Grace")
expect 3::isNot(3)::negate()

Comparing

isLessThan

on List<ItemType> · provided by Comparable where ItemType is Comparable

isLessThan(_ other: List<ItemType>) -> Boolean

Answers whether the value is strictly below another.

NameTypeDescription

_List<ItemType>the value to compare with

Returns true when the value is below the given one.

Example

expect 3::isLessThan(5)
expect 5::isLessThan(5)::negate()

isLessThanOrEqualTo

on List<ItemType> · provided by Comparable where ItemType is Comparable

isLessThanOrEqualTo(_ other: List<ItemType>) -> Boolean

Answers whether the value is below another, or equal to it.

NameTypeDescription

_List<ItemType>the value to compare with

Returns true when the value is below the given one or equal to it.

Example

expect 3::isLessThanOrEqualTo(5)
expect 5::isLessThanOrEqualTo(5)

isGreaterThan

on List<ItemType> · provided by Comparable where ItemType is Comparable

isGreaterThan(_ other: List<ItemType>) -> Boolean

Answers whether the value is strictly above another.

NameTypeDescription

_List<ItemType>the value to compare with

Returns true when the value is above the given one.

Example

expect "pear"::isGreaterThan("apple")
expect "pear"::isGreaterThan("pear")::negate()

isGreaterThanOrEqualTo

on List<ItemType> · provided by Comparable where ItemType is Comparable

isGreaterThanOrEqualTo(_ other: List<ItemType>) -> Boolean

Answers whether the value is above another, or equal to it.

NameTypeDescription

_List<ItemType>the value to compare with

Returns true when the value is above the given one or equal to it.

Example

expect 5::isGreaterThanOrEqualTo(3)
expect 5::isGreaterThanOrEqualTo(5)

Testing

hasItems

on List<ItemType>

Answers whether the List has an item, or has an item the check accepts.

Returns true when the List has an item, or when the check accepts an item.

hasItems() -> Boolean

Answers whether the List has at least one item.

It is the opposite of isEmpty.

Returns true when the List is not empty.

Example

constant guests: List<String> = []

expect ["Ada"]::hasItems()
expect guests::hasItems()::negate()

hasItems(where check: (_: ItemType) -> Boolean) -> Boolean

Answers whether the check accepts at least one item.

The walk stops at the first accepted item. The empty List has no item to accept, so it answers false.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns true when the check accepts an item.

Example

constant none: List<Integer> = []

expect [1, 2, 3]::hasItems(where (n) { <- n::isEven() })
expect none::hasItems(where (n) { <- n::isEven() })::negate()

isEmpty

on List<ItemType>

isEmpty() -> Boolean

Answers whether the List has no items at all.

Returns true for the empty List.

Example

constant guests: List<String> = []

expect guests::isEmpty()
expect ["Ada"]::isEmpty()::negate()

hasOnlyItems

on List<ItemType>

hasOnlyItems(where check: (_: ItemType) -> Boolean) -> Boolean

Answers whether the check accepts every item.

The walk stops at the first item the check refuses. The empty List has no item to fail the check, so it answers true.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns true when the check accepts every item.

Example

constant none: List<Integer> = []

expect [2, 4]::hasOnlyItems(where (n) { <- n::isEven() })
expect [2, 3]::hasOnlyItems(where (n) { <- n::isEven() })::negate()
expect none::hasOnlyItems(where (n) { <- n::isEven() })

hasNoItems

on List<ItemType>

hasNoItems(where check: (_: ItemType) -> Boolean) -> Boolean

Answers whether the check accepts no item at all.

The walk stops at the first accepted item. The empty List has no item to accept, so it answers true.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns true when the check accepts no item.

Example

constant none: List<Integer> = []

expect [1, 3]::hasNoItems(where (n) { <- n::isEven() })
expect [1, 2]::hasNoItems(where (n) { <- n::isEven() })::negate()
expect none::hasNoItems(where (n) { <- n::isEven() })

hasDuplicates

on List<ItemType>

Answers whether any item occurs twice, or whether any two items share a key.

Equality is the items' own is, or the keys' own where a key is read. The walk stops at the first repeat.

Returns true when something occurs twice.

hasDuplicates<ItemType is Equatable>() -> Boolean

Answers whether any item occurs twice.

The walk stops at the first repeated item. The empty List and a List of one item answer false. Equality is the items' own is. The entry is available whenever the items conform to Equatable.

Returns true when an item occurs twice.

Example

expect [1, 2, 1]::hasDuplicates()

hasDuplicates<infer Key is Equatable>(on key: (_: ItemType) -> Key) -> Boolean

Answers whether any two items share the key the given Function reads off each one.

The walk stops at the first repeated key. Equality is the keys' own is. The entry is available whenever what the key answers conforms to Equatable.

NameTypeDescription

on(_: ItemType) -> Keythe key read off each item

Returns true when two items share a key.

Example

constant rows = [{ sku = "a" }, { sku = "a" }]

expect rows::hasDuplicates(on .sku)

isSorted

on List<ItemType>

isSorted<ItemType is Comparable>(
	in order: SortOrder = #Ascending,
) -> Boolean

Answers whether the items are in order.

Items the order does not tell apart are in order either way. The empty List and a List of one item are both in order. The Method is available whenever the items conform to Comparable.

NameTypeDescription

inSortOrder = #Ascendingthe direction to check for, #Ascending when it is left out

Returns true when no item stands out of that order.

Example

expect [1, 2, 2, 3]::isSorted()
expect [3, 2, 1]::isSorted(in #Descending)

Searching

contains

on List<ItemType>

Answers whether an item equal to the given one is in the List, or whether every item of another List is.

Equality is the items' own is. The Method is available whenever the items conform to Equatable.

Returns true when the item occurs, or when every item of the other List does.

contains<ItemType is Equatable>(_ item: ItemType) -> Boolean

Answers whether an item equal to the given one is in the List.

Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

_ItemTypethe item to look for

Returns true when the item occurs.

Example

expect ["Ada", "Grace"]::contains("Grace")
expect ["Ada", "Grace"]::contains("Alan")::negate()

contains<ItemType is Equatable>(
	everyItemOf other: List<ItemType>,
) -> Boolean

Answers whether every item of the given List occurs in this one.

How many times an item occurs is not asked, so a List holding one 1 contains every item of [1, 1]. The empty List has no item to look for, so every List contains its items. The walk stops at the first item that does not occur. Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

everyItemOfList<ItemType>the List whose items to look for

Returns true when every item of it occurs.

Example

expect [1, 2, 3]::contains(everyItemOf [3, 1])
expect [1, 2]::contains(everyItemOf [])

doesNotContain

on List<ItemType>

doesNotContain<ItemType is Equatable>(_ item: ItemType) -> Boolean

Answers whether no item equal to the given one is in the List.

Equality is the items' own is. The Method is available whenever the items conform to Equatable.

NameTypeDescription

_ItemTypethe item to look for

Returns true when the item does not occur.

Example

expect ["Ada", "Grace"]::doesNotContain("Alan")
expect ["Ada", "Grace"]::doesNotContain("Ada")::negate()

starts

on List<ItemType>

starts<ItemType is Equatable>(with prefix: List<ItemType>) -> Boolean

Answers whether the List begins with the items of the given one.

Equality is the items' own is. The Method is available whenever the items conform to Equatable. Every List begins with the empty List.

NameTypeDescription

withList<ItemType>the leading items to look for

Returns true when the List begins with those items.

Example

expect [1, 2, 3]::starts(with [1, 2])
expect [1, 2, 3]::doesNotStart(with [2])

doesNotStart

on List<ItemType>

doesNotStart<ItemType is Equatable>(
	with prefix: List<ItemType>,
) -> Boolean

Answers whether the List does not begin with the items of the given one.

Equality is the items' own is. The Method is available whenever the items conform to Equatable.

NameTypeDescription

withList<ItemType>the leading items to look for

Returns true when the List begins with other items.

Example

expect [1, 2, 3]::doesNotStart(with [2, 3])
expect [1, 2, 3]::doesNotStart(with [1])::negate()

ends

on List<ItemType>

ends<ItemType is Equatable>(with suffix: List<ItemType>) -> Boolean

Answers whether the List ends with the items of the given one.

Equality is the items' own is. The Method is available whenever the items conform to Equatable. Every List ends with the empty List.

NameTypeDescription

withList<ItemType>the trailing items to look for

Returns true when the List ends with those items.

Example

expect [1, 2, 3]::ends(with [2, 3])
expect [1, 2, 3]::ends(with [])

doesNotEnd

on List<ItemType>

doesNotEnd<ItemType is Equatable>(
	with suffix: List<ItemType>,
) -> Boolean

Answers whether the List does not end with the items of the given one.

Equality is the items' own is. The Method is available whenever the items conform to Equatable.

NameTypeDescription

withList<ItemType>the trailing items to look for

Returns true when the List ends with other items.

Example

expect [1, 2, 3]::doesNotEnd(with [1, 2])
expect [1, 2, 3]::doesNotEnd(with [3])::negate()

firstIndex

on List<ItemType>

Answers the position of the first item equal to the given one, or of the first item the check accepts.

A List without such an item answers nothing, and the defaultingTo: entries answer the given position instead.

firstIndex<ItemType is Equatable>(of item: ItemType) -> Optional<Integer>

Answers the position of the first item equal to the given one.

Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

ofItemTypethe item to look for

Returns the zero-based position, or nothing when the item is absent.

Example

expect ["a", "b", "a"]::firstIndex(of "a")::is(0)
expect ["a", "b", "a"]::firstIndex(of "z")::isEmpty()

firstIndex(where check: (_: ItemType) -> Boolean) -> Optional<Integer>

Answers the position of the first item the check accepts.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns the zero-based position, or nothing when no item is accepted.

Example

expect [1, 4, 6]::firstIndex(where (n) { <- n::isEven() })::is(1)
expect [1, 3]::firstIndex(where (n) { <- n::isEven() })::isEmpty()

firstIndex<ItemType is Equatable>(
	of item: ItemType,
	defaultingTo fallback: Integer,
) -> Integer

Answers the position of the first item equal to the given one, or the given fallback when the item is absent.

Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

ofItemTypethe item to look for

defaultingToIntegerthe position to answer with when the item is absent

Returns the zero-based position, or the fallback in its place.

Example

expect ["a", "b", "a"]::firstIndex(of "a", defaultingTo -1)::is(0)
expect ["a", "b", "a"]::firstIndex(of "z", defaultingTo -1)::is(-1)

firstIndex(
	where check: (_: ItemType) -> Boolean,
	defaultingTo fallback: Integer,
) -> Integer

Answers the position of the first item the check accepts, or the given fallback when it accepts none.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

defaultingToIntegerthe position to answer with when no item is accepted

Returns the zero-based position, or the fallback in its place.

Example

constant isEven = (_ n: Integer) -> Boolean { <- n::isEven() }

expect [1, 4, 6]::firstIndex(where isEven, defaultingTo -1)::is(1)
expect [1, 3]::firstIndex(where isEven, defaultingTo -1)::is(-1)

lastIndex

on List<ItemType>

Answers the position of the last item equal to the given one, or of the last item the check accepts.

A List without such an item answers nothing, and the defaultingTo: entries answer the given position instead.

lastIndex<ItemType is Equatable>(of item: ItemType) -> Optional<Integer>

Answers the position of the last item equal to the given one.

Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

ofItemTypethe item to look for

Returns the zero-based position, or nothing when the item is absent.

Example

expect ["a", "b", "a"]::lastIndex(of "a")::is(2)
expect ["a", "b", "a"]::lastIndex(of "z")::isEmpty()

lastIndex<ItemType is Equatable>(
	of item: ItemType,
	defaultingTo fallback: Integer,
) -> Integer

Answers the position of the last item equal to the given one, or the given fallback when the item is absent.

Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

ofItemTypethe item to look for

defaultingToIntegerthe position to answer with when the item is absent

Returns the zero-based position, or the fallback in its place.

Example

expect ["a", "b", "a"]::lastIndex(of "a", defaultingTo -1)::is(2)
expect ["a", "b", "a"]::lastIndex(of "z", defaultingTo -1)::is(-1)

lastIndex(where check: (_: ItemType) -> Boolean) -> Optional<Integer>

Answers the position of the last item the check accepts.

The walk runs backwards and stops at the first item it accepts.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns the zero-based position, or nothing when no item is accepted.

Example

expect [2, 4, 5]::lastIndex(where (n) { <- n::isEven() })::is(1)
expect [1, 3]::lastIndex(where (n) { <- n::isEven() })::isEmpty()

lastIndex(
	where check: (_: ItemType) -> Boolean,
	defaultingTo fallback: Integer,
) -> Integer

Answers the position of the last item the check accepts, or the given fallback when it accepts none.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

defaultingToIntegerthe position to answer with when no item is accepted

Returns the zero-based position, or the fallback in its place.

Example

constant isEven = (_ n: Integer) -> Boolean { <- n::isEven() }

expect [2, 4, 5]::lastIndex(where isEven, defaultingTo -1)::is(1)
expect [1, 3]::lastIndex(where isEven, defaultingTo -1)::is(-1)

everyIndex

on List<ItemType>

everyIndex<ItemType is Equatable>(of item: ItemType) -> List<Integer>

Answers the positions of every item equal to the given one, in order.

Equality is the items' own is. The Method is available whenever the items conform to Equatable. A List without the item answers no positions.

NameTypeDescription

ofItemTypethe item to look for

Returns the List of positions the item stands at.

Example

expect [1, 2, 1]::everyIndex(of 1)::is([0, 2])

count

on List<ItemType>

Answers how many items equal the given one, or how many items the check accepts.

Equality is the items' own is. The by-value entry is available whenever the items conform to Equatable.

Returns the count.

count<ItemType is Equatable>(of item: ItemType) -> NonNegativeInteger

Answers how many items equal the given one.

Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

ofItemTypethe item to look for

Returns how many items equal it, which is never negative.

Example

expect ["a", "b", "a"]::count(of "a")::is(2)
expect ["a", "b", "a"]::count(of "z")::is(0)

count(where check: (_: ItemType) -> Boolean) -> NonNegativeInteger

Answers how many items the check accepts.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns how many items the check accepts, which is never negative.

Example

expect [1, 2, 3, 4]::count(where (n) { <- n::isEven() })::is(2)

Reading

length

on List<ItemType>

length() -> NonNegativeInteger

Answers how many items the List has.

Returns the number of items, which is never negative.

Example

constant guests: List<String> = ["Ada", "Grace"]

expect guests::length()::is(2)

on NonEmptyList<ItemType>

length() -> PositiveInteger

Answers how many items the List has, which is at least one.

Returns the number of items, which is above zero.

Example

constant queue: NonEmptyList<String> = ["Ada", "Grace"]
constant count: PositiveInteger = queue::length()

expect count::is(2)

firstItem

on List<ItemType>

Answers the first item, or the first item the check accepts.

The empty List has no first item, and a check can accept none of the items. The defaultingTo: entries answer the given item in place of nothing.

firstItem() -> Optional<ItemType>

Answers the first item of the List.

Returns the item, or nothing for the empty List.

Example

constant queue: List<String> = ["Ada", "Grace"]
constant nobody: List<String> = []

expect queue::firstItem()::is("Ada")
expect nobody::firstItem()::isEmpty()

firstItem(where check: (_: ItemType) -> Boolean) -> Optional<ItemType>

Answers the first item the check accepts.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns the matching item, or nothing when no item is accepted.

Example

expect [1, 4, 6]::firstItem(where (n) { <- n::isEven() })::is(4)
expect [1, 3]::firstItem(where (n) { <- n::isEven() })::isEmpty()

firstItem(defaultingTo fallback: ItemType) -> ItemType

Answers the first item, or the given fallback for the empty List.

NameTypeDescription

defaultingToItemTypethe item to answer with when there is none

Returns the first item, or the fallback in its place.

Example

constant queue: List<String> = ["Ada", "Grace"]
constant nobody: List<String> = []

expect queue::firstItem(defaultingTo "none")::is("Ada")
expect nobody::firstItem(defaultingTo "none")::is("none")

firstItem(
	where check: (_: ItemType) -> Boolean,
	defaultingTo fallback: ItemType,
) -> ItemType

Answers the first item the check accepts, or the given fallback when it accepts none.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

defaultingToItemTypethe item to answer with when there is none

Returns the matching item, or the fallback in its place.

Example

constant isEven = (_ n: Integer) -> Boolean { <- n::isEven() }

expect [1, 4, 6]::firstItem(where isEven, defaultingTo 0)::is(4)
expect [1, 3]::firstItem(where isEven, defaultingTo 0)::is(0)

on NonEmptyList<ItemType>

firstItem() -> ItemType

Answers the first item of the List, which certainly has one.

Returns the first item.

Example

constant queue: NonEmptyList<String> = ["Ada", "Grace"]
constant first: String = queue::firstItem()

expect first::is("Ada")

lastItem

on List<ItemType>

Answers the last item, or the last item the check accepts.

The empty List has no last item, and a check can accept none of the items. The defaultingTo: entries answer the given item in place of nothing.

lastItem() -> Optional<ItemType>

Answers the last item of the List.

Returns the item, or nothing for the empty List.

Example

constant queue: List<String> = ["Ada", "Grace"]
constant nobody: List<String> = []

expect queue::lastItem()::is("Grace")
expect nobody::lastItem()::isEmpty()

lastItem(where check: (_: ItemType) -> Boolean) -> Optional<ItemType>

Answers the last item the check accepts.

The walk runs backwards and stops at the first item it accepts.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns the matching item, or nothing when no item is accepted.

Example

expect [2, 4, 5]::lastItem(where (n) { <- n::isEven() })::is(4)
expect [1, 3]::lastItem(where (n) { <- n::isEven() })::isEmpty()

lastItem(defaultingTo fallback: ItemType) -> ItemType

Answers the last item, or the given fallback for the empty List.

NameTypeDescription

defaultingToItemTypethe item to answer with when there is none

Returns the last item, or the fallback in its place.

Example

constant queue: List<String> = ["Ada", "Grace"]
constant nobody: List<String> = []

expect queue::lastItem(defaultingTo "none")::is("Grace")
expect nobody::lastItem(defaultingTo "none")::is("none")

lastItem(
	where check: (_: ItemType) -> Boolean,
	defaultingTo fallback: ItemType,
) -> ItemType

Answers the last item the check accepts, or the given fallback when it accepts none.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

defaultingToItemTypethe item to answer with when there is none

Returns the matching item, or the fallback in its place.

Example

constant isEven = (_ n: Integer) -> Boolean { <- n::isEven() }

expect [2, 4, 5]::lastItem(where isEven, defaultingTo 0)::is(4)
expect [1, 3]::lastItem(where isEven, defaultingTo 0)::is(0)

on NonEmptyList<ItemType>

lastItem() -> ItemType

Answers the last item of the List, which certainly has one.

Returns the last item.

Example

constant queue: NonEmptyList<String> = ["Ada", "Grace"]
constant last: String = queue::lastItem()

expect last::is("Grace")

item

on List<ItemType>

Answers the item at the given position.

The position counts from zero. A negative position counts back from the end: -1 is the last item. A position outside the List answers nothing, and the defaultingTo: entry answers the given item instead.

item(at index: Integer) -> Optional<ItemType>

Answers the item at the given position.

NameTypeDescription

atIntegerthe position of the item

Returns the item, or nothing when the position is outside the List.

Example

expect ["a", "b", "c"]::item(at 0)::is("a")
expect ["a", "b", "c"]::item(at -1)::is("c")
expect ["a", "b", "c"]::item(at 3)::isEmpty()

item(at index: Integer, defaultingTo fallback: ItemType) -> ItemType

Answers the item at the given position, or the given fallback when the position is outside the List.

NameTypeDescription

atIntegerthe position of the item

defaultingToItemTypethe item to answer with when the position names none

Returns the item at that position, or the fallback in its place.

Example

expect ["a", "b"]::item(at 1, defaultingTo "?")::is("b")
expect ["a", "b"]::item(at 5, defaultingTo "?")::is("?")

indices

on List<ItemType>

Answers the positions the List has, or the positions of the items a check accepts.

The positions count from zero and stop before the length. The empty List answers no positions.

Returns the List of positions.

indices() -> List<Integer>

Answers the positions the List has, in order.

The positions count from zero and stop before the length. The empty List answers no positions. The answer is a whole List of positions: to walk the items beside their positions in one pass, use enumerate().

Returns the List of positions.

Example

constant letters: List<String> = ["a", "b", "c"]
constant none: List<String> = []

expect letters::indices()::is([0, 1, 2])
expect none::indices()::isEmpty()

indices(where check: (_: ItemType) -> Boolean) -> List<Integer>

Answers the positions of the items the check accepts, in order.

The positions count from zero. A check that accepts no item answers no positions.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns the List of positions the check accepted.

Example

expect [3, 4, 5, 6]::indices(where (n) { <- n::isEven() })::is([1, 3])

on NonEmptyList<ItemType>

indices() -> NonEmptyList<Integer>

Answers the positions the List has, in order.

The positions count from zero and stop before the length. The answer is a whole List of positions: to walk the items beside their positions in one pass, use enumerate().

Returns the List of positions, which is never empty.

Example

constant letters: NonEmptyList<String> = ["a", "b", "c"]
constant positions: NonEmptyList<Integer> = letters::indices()

expect positions::is([0, 1, 2])

onlyItem

on List<ItemType>

Answers the only item of the List.

A List of any other length has no only item, and the defaultingTo: entry answers the given item in place of nothing.

onlyItem() -> Optional<ItemType>

Answers the only item of the List.

Returns the item, or nothing when the List does not hold exactly one.

Example

expect [7]::onlyItem()::is(7)
expect [7, 8]::onlyItem()::isEmpty()

onlyItem(defaultingTo fallback: ItemType) -> ItemType

Answers the only item of the List, or the given fallback for a List of any other length.

NameTypeDescription

defaultingToItemTypethe item to answer with when there is no only item

Returns the item, or the fallback in its place.

Example

expect [7]::onlyItem(defaultingTo 0)::is(7)
expect [7, 8]::onlyItem(defaultingTo 0)::is(0)

enumerate

on List<ItemType>

enumerate() -> List<{ index: Integer, item: ItemType }>

Answers every item beside the position it stands at.

The position counts from zero. The empty List answers no entries.

Returns the List of Records, each holding a position under index and the item at it under item.

Example

constant letters: List<String> = ["a", "b"]

expect letters::enumerate()::is([
	{ index = 0, item = "a" },
	{ index = 1, item = "b" },
])

on NonEmptyList<ItemType>

enumerate() -> NonEmptyList<{ index: Integer, item: ItemType }>

Answers every item beside the position it stands at.

The position counts from zero.

Returns the List of Records, each holding a position under index and the item at it under item. It is never empty.

Example

constant letters: NonEmptyList<String> = ["a", "b"]

expect letters::enumerate()::firstItem()::is({ index = 0, item = "a" })

lowestItem

on List<ItemType>

Answers the lowest item, or the item whose key is lowest.

Ties keep the earlier item. The empty List has no such item, and the defaultingTo: entries answer the given item in place of nothing.

lowestItem<infer Key is Comparable>(
	on key: (_: ItemType) -> Key,
) -> Optional<ItemType>

Answers the item whose key is lowest.

NameTypeDescription

on(_: ItemType) -> Keythe key the items are ordered by

Returns the item, or nothing for the empty List.

Example

constant fruit: List<String> = ["pear", "fig", "kiwi"]
constant none: List<String> = []

expect fruit::lowestItem(on (word) { <- word::length() })::is("fig")
expect none::lowestItem(on (word) { <- word::length() })::isEmpty()

lowestItem<infer Key is Comparable>(
	on key: (_: ItemType) -> Key,
	defaultingTo fallback: ItemType,
) -> ItemType

Answers the item whose key is lowest, or the given fallback for the empty List.

NameTypeDescription

on(_: ItemType) -> Keythe key the items are ordered by

defaultingToItemTypethe item to answer with when there is none

Returns the item, or the fallback in its place.

Example

constant length = (_ word: String) -> Integer { <- word::length() }
constant fruit: List<String> = ["pear", "fig"]
constant none: List<String> = []

expect fruit::lowestItem(on length, defaultingTo "none")::is("fig")
expect none::lowestItem(on length, defaultingTo "none")::is("none")

lowestItem<ItemType is Comparable>() -> Optional<ItemType>

Answers the lowest item.

Ties keep the earlier item. The entry is available whenever the items conform to Comparable.

Returns the item, or nothing for the empty List.

Example

constant fruit: List<String> = ["pear", "apple"]

expect fruit::lowestItem()::is("apple")

lowestItem<ItemType is Comparable>(
	defaultingTo fallback: ItemType,
) -> ItemType

Answers the lowest item, or the given fallback for the empty List.

The entry is available whenever the items conform to Comparable.

NameTypeDescription

defaultingToItemTypethe item to answer with when there is none

Returns the item, or the fallback in its place.

Example

constant scores: List<Integer> = [3, 1, 2]
constant none: List<Integer> = []

expect scores::lowestItem(defaultingTo 0)::is(1)
expect none::lowestItem(defaultingTo 0)::is(0)

on NonEmptyList<ItemType>

Answers the lowest item, or the item whose key is lowest, which a non-empty List always has.

Ties keep the earlier item.

Returns the item.

lowestItem<infer Key is Comparable>(
	on key: (_: ItemType) -> Key,
) -> ItemType

Answers the item whose key is lowest, which a non-empty List always has.

Ties keep the earlier item.

NameTypeDescription

on(_: ItemType) -> Keythe key the items are ordered by

Returns the item.

Example

constant people: NonEmptyList<{ name: String, age: Integer }> = [
	{ name = "Ada", age = 36 },
	{ name = "Bo", age = 7 },
]

expect people::lowestItem(on .age).name::is("Bo")

lowestItem<ItemType is Comparable>() -> ItemType

Answers the lowest item, which a non-empty List always has.

Ties keep the earlier item. The entry is available whenever the items conform to Comparable.

Returns the item.

Example

constant scores: NonEmptyList<Integer> = [3, 1, 2]
constant lowest: Integer = scores::lowestItem()

expect lowest::is(1)

highestItem

on List<ItemType>

Answers the highest item, or the item whose key is highest.

Ties keep the earlier item. The empty List has no such item, and the defaultingTo: entries answer the given item in place of nothing.

highestItem<infer Key is Comparable>(
	on key: (_: ItemType) -> Key,
) -> Optional<ItemType>

Answers the item whose key is highest.

NameTypeDescription

on(_: ItemType) -> Keythe key the items are ordered by

Returns the item, or nothing for the empty List.

Example

constant fruit: List<String> = ["pear", "fig", "kiwi"]
constant none: List<String> = []

expect fruit::highestItem(on (word) { <- word::length() })::is("pear")
expect none::highestItem(on (word) { <- word::length() })::isEmpty()

highestItem<infer Key is Comparable>(
	on key: (_: ItemType) -> Key,
	defaultingTo fallback: ItemType,
) -> ItemType

Answers the item whose key is highest, or the given fallback for the empty List.

NameTypeDescription

on(_: ItemType) -> Keythe key the items are ordered by

defaultingToItemTypethe item to answer with when there is none

Returns the item, or the fallback in its place.

Example

constant length = (_ word: String) -> Integer { <- word::length() }
constant fruit: List<String> = ["fig", "pear"]
constant none: List<String> = []

expect fruit::highestItem(on length, defaultingTo "none")::is("pear")
expect none::highestItem(on length, defaultingTo "none")::is("none")

highestItem<ItemType is Comparable>() -> Optional<ItemType>

Answers the highest item.

Ties keep the earlier item. The entry is available whenever the items conform to Comparable.

Returns the item, or nothing for the empty List.

Example

constant fruit: List<String> = ["pear", "apple"]

expect fruit::highestItem()::is("pear")

highestItem<ItemType is Comparable>(
	defaultingTo fallback: ItemType,
) -> ItemType

Answers the highest item, or the given fallback for the empty List.

The entry is available whenever the items conform to Comparable.

NameTypeDescription

defaultingToItemTypethe item to answer with when there is none

Returns the item, or the fallback in its place.

Example

constant scores: List<Integer> = [3, 1, 2]
constant none: List<Integer> = []

expect scores::highestItem(defaultingTo 0)::is(3)
expect none::highestItem(defaultingTo 0)::is(0)

on NonEmptyList<ItemType>

Answers the highest item, or the item whose key is highest, which a non-empty List always has.

Ties keep the earlier item.

Returns the item.

highestItem<infer Key is Comparable>(
	on key: (_: ItemType) -> Key,
) -> ItemType

Answers the item whose key is highest, which a non-empty List always has.

Ties keep the earlier item.

NameTypeDescription

on(_: ItemType) -> Keythe key the items are ordered by

Returns the item.

Example

constant people: NonEmptyList<{ name: String, age: Integer }> = [
	{ name = "Ada", age = 36 },
	{ name = "Bo", age = 7 },
]

expect people::highestItem(on .age).name::is("Ada")

highestItem<ItemType is Comparable>() -> ItemType

Answers the highest item, which a non-empty List always has.

Ties keep the earlier item. The entry is available whenever the items conform to Comparable.

Returns the item.

Example

constant scores: NonEmptyList<Integer> = [3, 1, 2]
constant highest: Integer = scores::highestItem()

expect highest::is(3)

firstItems

on List<ItemType>

Answers a new List of the leading items, up to the given count, or of the leading items a check accepts.

A count below one answers the empty List. A count past the length answers every item.

Returns the List of leading items, in the order they were in.

firstItems(_ count: Integer) -> List<ItemType>

Answers a new List of the leading items, up to the given count.

A count below one answers the empty List. A count past the length answers every item.

NameTypeDescription

_Integerhow many leading items to keep

Returns the List of leading items, in the order they were in.

Example

expect [1, 2, 3]::firstItems(2)::is([1, 2])
expect [1, 2, 3]::firstItems(5)::is([1, 2, 3])
expect [1, 2, 3]::firstItems(0)::isEmpty()

firstItems(while check: (_: ItemType) -> Boolean) -> List<ItemType>

Answers a new List of the leading items the check accepts.

The walk stops at the first item the check refuses, and that item is left out. A check that accepts every item answers every item.

NameTypeDescription

while(_: ItemType) -> Booleanthe check the leading items are offered to

Returns the List up to the first refused item.

Example

expect [1, 2, 3, 1]::firstItems(while (n) { <- n::isLessThan(3) })::is([1, 2])

lastItems

on List<ItemType>

Answers a new List of the trailing items, up to the given count, or of the trailing items a check accepts.

A count below one answers the empty List. A count past the length answers every item.

Returns the List of trailing items, in the order they were in.

lastItems(_ count: Integer) -> List<ItemType>

Answers a new List of the trailing items, up to the given count.

A count below one answers the empty List. A count past the length reaches back past the start, where slice settles on zero, so it answers every item.

NameTypeDescription

_Integerhow many trailing items to keep

Returns the List of trailing items, in the order they were in.

Example

expect [1, 2, 3]::lastItems(2)::is([2, 3])
expect [1, 2, 3]::lastItems(5)::is([1, 2, 3])
expect [1, 2, 3]::lastItems(0)::isEmpty()

lastItems(while check: (_: ItemType) -> Boolean) -> List<ItemType>

Answers a new List of the trailing items the check accepts.

The walk runs backwards and stops at the last item the check refuses, which is left out. A check that accepts every item answers every item.

NameTypeDescription

while(_: ItemType) -> Booleanthe check the trailing items are offered to

Returns the List from after the last refused item.

Example

expect [1, 3, 2, 1]::lastItems(while (n) { <- n::isLessThan(3) })::is([2, 1])

Adding and replacing

prepend

on List<ItemType>

Answers a new List with the given item, or with the contents of the given List, added at the front.

prepend(_ item: ItemType) -> NonEmptyList<ItemType>

Answers a new List with the given item added at the front.

The item is never dropped, so the answer certainly has something in it.

NameTypeDescription

_ItemTypethe item to add

Returns the extended List, which is never empty.

Example

constant guests: List<String> = ["Grace"]
constant queue: NonEmptyList<String> = guests::prepend("Ada")

expect queue::is(["Ada", "Grace"])

prepend(contentsOf other: List<ItemType>) -> List<ItemType>

Answers a new List with the contents of the given List added at the front.

NameTypeDescription

contentsOfList<ItemType>the List whose items to add

Returns the extended List.

Example

constant queue: List<String> = ["Cy"]

expect queue::prepend(contentsOf ["Ada", "Bo"])::is(["Ada", "Bo", "Cy"])

on NonEmptyList<ItemType>

prepend(contentsOf other: List<ItemType>) -> NonEmptyList<ItemType>

Answers a new List with the contents of the given List added at the front.

NameTypeDescription

contentsOfList<ItemType>the List whose items to add

Returns the extended List, which is never empty.

Example

constant queue: NonEmptyList<String> = ["Cy"]

expect queue::prepend(contentsOf ["Ada", "Bo"])::is(["Ada", "Bo", "Cy"])

append

on List<ItemType>

Answers a new List with the given item, or with the contents of the given List, added at the end.

append(_ item: ItemType) -> NonEmptyList<ItemType>

Answers a new List with the given item added at the end.

The item is never dropped, so the answer certainly has something in it.

NameTypeDescription

_ItemTypethe item to add

Returns the extended List, which is never empty.

Example

constant guests: List<String> = ["Ada"]
constant queue: NonEmptyList<String> = guests::append("Grace")

expect queue::is(["Ada", "Grace"])

append(contentsOf other: List<ItemType>) -> List<ItemType>

Answers a new List with the contents of the given List added at the end.

NameTypeDescription

contentsOfList<ItemType>the List whose items to add

Returns the extended List.

Example

constant queue: List<String> = ["Ada"]

expect queue::append(contentsOf ["Bo", "Cy"])::is(["Ada", "Bo", "Cy"])

on NonEmptyList<ItemType>

append(contentsOf other: List<ItemType>) -> NonEmptyList<ItemType>

Answers a new List with the contents of the given List added at the end.

NameTypeDescription

contentsOfList<ItemType>the List whose items to add

Returns the extended List, which is never empty.

Example

constant queue: NonEmptyList<String> = ["Ada"]

expect queue::append(contentsOf ["Bo", "Cy"])::is(["Ada", "Bo", "Cy"])

insert

on List<ItemType>

insert(_ item: ItemType, at index: Integer) -> NonEmptyList<ItemType>

Answers a new List with the given item inserted before the given position.

A negative position counts back from the end, so insert(_, at -1) puts the item before the last one. A position outside the List clamps to the nearer end. The item is never dropped, so the answer certainly has something in it.

NameTypeDescription

_ItemTypethe item to insert

atIntegerthe position to insert the item before

Returns the List with the item inserted. It is never empty.

Example

expect ["a", "c"]::insert("b", at 1)::is(["a", "b", "c"])
expect ["a", "b", "d"]::insert("c", at -1)::is(["a", "b", "c", "d"])
expect ["a", "b"]::insert("z", at 9)::is(["a", "b", "z"])

replace

on List<ItemType>

Answers a new List with the item at the given position replaced by a given item, or by a transform of it.

A negative position counts back from the end: -1 is the last item. A position outside the List leaves it unchanged.

Returns the List with the item replaced.

replace(_ item: ItemType, at index: Integer) -> List<ItemType>

Answers a new List with the item at the given position replaced.

A negative position counts back from the end: -1 is the last item. A position outside the List leaves it unchanged.

NameTypeDescription

_ItemTypethe item to put at that position

atIntegerthe position of the item to replace

Returns the List with the item replaced.

Example

constant letters: List<String> = ["a", "b", "c"]

expect letters::replace("B", at 1)::is(["a", "B", "c"])
expect letters::replace("C", at -1)::is(["a", "b", "C"])
expect letters::replace("z", at 5)::is(["a", "b", "c"])

replace(
	at index: Integer,
	_ transform: (_: ItemType) -> ItemType,
) -> List<ItemType>

Answers a new List with the item at the given position replaced by what the transform answers for it.

A negative position counts back from the end: -1 is the last item. A position outside the List leaves it unchanged, and the transform is not run.

NameTypeDescription

atIntegerthe position of the item to replace

_(_: ItemType) -> ItemTypethe transform the item at that position is handed to

Returns the List with the item replaced.

Example

constant scores: List<Integer> = [10, 20, 30]

expect scores::replace(at 1, (n) { <- n::add(5) })::is([10, 25, 30])
expect scores::replace(at 7, (n) { <- n::add(5) })::is([10, 20, 30])

on NonEmptyList<ItemType>

Answers a new List with the item at the given position replaced by a given item, or by a transform of it.

A negative position counts back from the end: -1 is the last item. A position outside the List leaves it unchanged. No case can empty the List.

Returns the List with the item replaced, which is never empty.

replace(_ item: ItemType, at index: Integer) -> NonEmptyList<ItemType>

Answers a new List with the item at the given position replaced.

A negative position counts back from the end: -1 is the last item. A position outside the List leaves it unchanged. Neither case can empty the List.

NameTypeDescription

_ItemTypethe item to put at that position

atIntegerthe position of the item to replace

Returns the List with the item replaced, which is never empty.

Example

constant names: NonEmptyList<String> = ["Ada", "Bo"]

expect names::replace("Al", at -1)::is(["Ada", "Al"])
expect names::replace("Al", at 5)::is(["Ada", "Bo"])

replace(
	at index: Integer,
	_ transform: (_: ItemType) -> ItemType,
) -> NonEmptyList<ItemType>

Answers a new List with the item at the given position replaced by what the transform answers for it.

A negative position counts back from the end: -1 is the last item. A position outside the List leaves it unchanged, and the transform is not run.

NameTypeDescription

atIntegerthe position of the item to replace

_(_: ItemType) -> ItemTypethe transform the item at that position is handed to

Returns the List with the item replaced, which is never empty.

Example

constant scores: NonEmptyList<Integer> = [10, 20]

expect scores::replace(at 0, (n) { <- n::add(5) })::is([15, 20])

pad

on List<ItemType>

pad(
	to length: Integer,
	with filler: ItemType,
	at side: Side = #End,
) -> List<ItemType>

Answers the List filled up to the given length with the given item.

The filler goes at the end when no side is named. A #BothEnds side splits it between the two ends, and an odd count leaves the extra one at the end. A length at or below the one the List has answers it unchanged, so nothing is ever dropped.

NameTypeDescription

toIntegerthe length to fill up to

withItemTypethe item to fill with

atSide = #Endthe end to fill at, #End when it is left out

Returns the filled List. It is the receiver where the List is already that long.

Example

expect [1, 2]::pad(to 4, with 0)::is([1, 2, 0, 0])
expect [1, 2]::pad(to 4, with 0, at #Start)::is([0, 0, 1, 2])

Removing

removeFirst

on List<ItemType>

Answers a new List without the first item, without the given number of leading items, or without the leading items a check accepts.

The answer is empty when every item is removed. A count below one removes nothing.

Returns the shortened List.

removeFirst(_ count: Integer = 1) -> List<ItemType>

Answers a new List without the first item, or without the given number of leading items.

The answer is empty when more items are removed than the List has. A count below one removes nothing.

NameTypeDescription

_Integer = 1how many leading items to remove, which is one when it is left out

Returns the shortened List.

Example

expect [1, 2, 3]::removeFirst()::is([2, 3])
expect [1, 2, 3]::removeFirst(2)::is([3])
expect [1, 2, 3]::removeFirst(5)::isEmpty()

removeFirst(while check: (_: ItemType) -> Boolean) -> List<ItemType>

Answers a new List without the leading items the check accepts.

The walk stops at the first item the check refuses, and that item and every item after it are kept. A check that accepts every item answers the empty List.

NameTypeDescription

while(_: ItemType) -> Booleanthe check the leading items are offered to

Returns the List from the first refused item on.

Example

expect [1, 2, 3, 1]::removeFirst(while (n) { <- n::isLessThan(3) })::is([3, 1])

remove

on List<ItemType>

remove(at index: Integer) -> List<ItemType>

Answers a new List without the item at the given position.

The position counts from zero. A negative position counts back from the end: -1 is the last item. A position outside the List leaves it unchanged.

NameTypeDescription

atIntegerthe position of the item to remove

Returns the List without that item.

Example

expect ["a", "b", "c"]::remove(at 1)::is(["a", "c"])
expect ["a", "b", "c"]::remove(at -1)::is(["a", "b"])
expect ["a", "b", "c"]::remove(at 5)::is(["a", "b", "c"])

removeEvery

on List<ItemType>

Answers a new List without every item equal to the given one, or without every item the check accepts.

Equality is the items' own is. The by-value entry is available whenever the items conform to Equatable.

Returns the List of remaining items.

removeEvery<ItemType is Equatable>(_ item: ItemType) -> List<ItemType>

Answers a new List without every item equal to the given one.

Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

_ItemTypethe item to remove

Returns the List of remaining items.

Example

expect [1, 2, 1, 3]::removeEvery(1)::is([2, 3])

removeEvery(where check: (_: ItemType) -> Boolean) -> List<ItemType>

Answers a new List without every item the check accepts.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns the List of the items the check rejects.

Example

constant odds = [1, 2, 3, 4]::removeEvery(where (n) { <- n::isEven() })

expect odds::is([1, 3])

removeEvery<ItemType is Equatable>(
	contentsOf other: List<ItemType>,
) -> List<ItemType>

Answers a new List without any item the given List holds.

Every occurrence of such an item goes, and the rest keep their order. An item of the given List that this one does not hold changes nothing. Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

contentsOfList<ItemType>the List whose items to remove

Returns the List of remaining items.

Example

expect [1, 2, 3, 2]::removeEvery(contentsOf [2])::is([1, 3])

removeLast

on List<ItemType>

Answers a new List without the last item, without the given number of trailing items, or without the trailing items a check accepts.

The answer is empty when every item is removed. A count below one removes nothing.

Returns the shortened List.

removeLast(_ count: Integer = 1) -> List<ItemType>

Answers a new List without the last item, or without the given number of trailing items.

The answer is empty when more items are removed than the List has. A count below one removes nothing.

NameTypeDescription

_Integer = 1how many trailing items to remove, which is one when it is left out

Returns the shortened List.

Example

expect [1, 2, 3]::removeLast()::is([1, 2])
expect [1, 2, 3]::removeLast(2)::is([1])
expect [1, 2, 3]::removeLast(5)::isEmpty()

removeLast(while check: (_: ItemType) -> Boolean) -> List<ItemType>

Answers a new List without the trailing items the check accepts.

The walk runs backwards and stops at the last item the check refuses. That item and every item before it are kept. A check that accepts every item answers the empty List.

NameTypeDescription

while(_: ItemType) -> Booleanthe check the trailing items are offered to

Returns the List up to the last refused item.

Example

expect [1, 3, 2, 1]::removeLast(while (n) { <- n::isLessThan(3) })::is([1, 3])

removeDuplicates

on List<ItemType>

Answers a new List keeping only the first occurrence of each item, or the first item met at each key.

The kept items keep the order they had. Equality is the items' own is, or the keys' own where a key is read.

Returns the List without duplicates.

removeDuplicates<ItemType is Equatable>() -> List<ItemType>

Answers a new List keeping only the first occurrence of each item.

The kept items keep the order they had. Equality is the items' own is. The entry is available whenever the items conform to Equatable. The union of two Lists is append(contentsOf other)::removeDuplicates().

Returns the List without duplicates.

Example

expect ["a", "b", "a"]::removeDuplicates()::is(["a", "b"])

removeDuplicates<infer Key is Equatable>(
	on key: (_: ItemType) -> Key,
) -> List<ItemType>

Answers a new List keeping only the first item met at each key.

The kept items keep the order they had. A later item whose key is already met goes, whatever the rest of it holds. Equality is the keys' own is. The entry is available whenever what the key answers conforms to Equatable.

NameTypeDescription

on(_: ItemType) -> Keythe key read off each item

Returns the List holding the first item met at each key.

Example

constant rows = [{ id = 1, name = "a" }, { id = 1, name = "b" }]

expect rows::removeDuplicates(on .id)::is([{ id = 1, name = "a" }])

on NonEmptyList<ItemType>

Answers a new List keeping only the first occurrence of each item, or the first item met at each key.

The kept items keep the order they had. Equality is the items' own is, or the keys' own where a key is read.

Returns the List without duplicates, which certainly has something in it.

removeDuplicates<ItemType is Equatable>() -> NonEmptyList<ItemType>

Answers a new List keeping only the first occurrence of each item.

The kept items keep the order they had. Equality is the items' own is. The entry is available whenever the items conform to Equatable.

Returns the List without duplicates, which certainly has something in it.

Example

constant tags: NonEmptyList<String> = ["a", "b", "a"]
constant unique: NonEmptyList<String> = tags::removeDuplicates()

expect unique::is(["a", "b"])

removeDuplicates<infer Key is Equatable>(
	on key: (_: ItemType) -> Key,
) -> NonEmptyList<ItemType>

Answers a new List keeping only the first item met at each key.

The kept items keep the order they had. Equality is the keys' own is. The entry is available whenever what the key answers conforms to Equatable.

NameTypeDescription

on(_: ItemType) -> Keythe key read off each item

Returns the List holding the first item met at each key, which certainly has something in it.

Example

constant rows: NonEmptyList<{ id: Integer, name: String }> = [
	{ id = 1, name = "a" },
	{ id = 1, name = "b" },
]

expect rows::removeDuplicates(on .id)::is([{ id = 1, name = "a" }])

Transforming

map

on List<ItemType>

map<infer Other>(_ transform: (_: ItemType) -> Other) -> List<Other>

Answers a new List with the given transform applied to every item.

NameTypeDescription

_(_: ItemType) -> Otherthe transform each item is handed to

Returns the List of transformed items.

Example

constant names: List<String> = ["Ada", "Grace"]

expect names::map((name) { <- name::length() })::is([3, 5])

on NonEmptyList<ItemType>

map<infer Other>(
	_ transform: (_: ItemType) -> Other,
) -> NonEmptyList<Other>

Answers a new List with the given transform applied to every item.

NameTypeDescription

_(_: ItemType) -> Otherthe transform each item is handed to

Returns the List of transformed items, which certainly has something in it.

Example

constant names: NonEmptyList<String> = ["Ada", "Grace"]
constant lengths: NonEmptyList<Integer> = names::map((name) {
	<- name::length()
})

expect lengths::is([3, 5])

reduce

on List<ItemType>

Answers the items combined into a single value, starting from the given one.

The fold runs to the end, or stops early when the combiner says to.

Returns the combined value.

reduce<infer Answer>(
	startingWith initial: Answer,
	_ combine: (_: Answer, _: ItemType) -> Answer,
) -> Answer

Answers the items combined into a single value, starting from the given one.

NameTypeDescription

startingWithAnswerthe value the first combination builds on

_(_: Answer, _: ItemType) -> Answerthe combiner, handed the value so far and each item

Returns the combined value.

Example

constant total = [1, 2, 3]::reduce(startingWith 10, (sum, item) {
	<- sum::add(item)
})

expect total::is(16)

reduce<infer Answer>(
	startingWith initial: Answer,
	step combine: (_: Answer, _: ItemType) -> Step<Answer, Answer>,
) -> Answer

Answers the items combined into a single value, starting from the given one, and can stop before the end.

The step combiner answers with a Step: #Continue carries the value forward, and #Done finishes at once with its own value. Both of that Step's Type Parameters are the Answer here, so a fold stops with the Type it carries. The empty List answers the starting value untouched.

NameTypeDescription

startingWithAnswerthe value the first combination builds on

step(_: Answer, _: ItemType) -> Step<Answer, Answer>the combiner, handed the value so far and each item, answering with a Step

Returns the combined value, or the value the first #Done carries.

Example

constant spent = [40, 30, 50, 20]::reduce(
	startingWith 0,
	step (total, price) {
		constant next = total::add(price)

		if next::isGreaterThan(100) {
			<- #Done(total)
		}

		<- #Continue(next)
	},
)

expect spent::is(70)

on NonEmptyList<ItemType>

reduce(_ combine: (_: ItemType, _: ItemType) -> ItemType) -> ItemType

Answers the items combined into a single value, with no starting value to give.

The first item opens the fold and each item after it is combined into what came before. A List of one item answers that item, and the combiner is not run.

NameTypeDescription

_(_: ItemType, _: ItemType) -> ItemTypethe combiner, handed the value so far and each item

Returns the combined value.

Example

constant total = [1, 2, 3]::reduce((running, item) { <- running::add(item) })

expect total::is(6)

everyItem

on List<ItemType>

Answers a new List of every item the check accepts, or of every item another List holds too.

The kept items keep their order.

Returns the List of kept items.

everyItem(where check: (_: ItemType) -> Boolean) -> List<ItemType>

Answers a new List of every item the check accepts.

Each item is offered to the check, and the accepted items keep their order.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns the List of accepted items.

Example

constant evens = [1, 2, 3, 4]::everyItem(where (n) { <- n::isEven() })

expect evens::is([2, 4])

everyItem<ItemType is Equatable>(
	alsoIn other: List<ItemType>,
) -> List<ItemType>

Answers a new List of every item the given List holds too.

The kept items keep the order they had here, and an item kept once for every time it occurs. How many times the other List holds it is not asked. Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

alsoInList<ItemType>the List whose items to keep

Returns the List of items both Lists hold.

Example

expect [3, 1, 2]::everyItem(alsoIn [2, 3])::is([3, 2])

accumulate

on List<ItemType>

accumulate<infer Answer>(
	startingWith initial: Answer,
	_ combine: (_: Answer, _: ItemType) -> Answer,
) -> NonEmptyList<Answer>

Answers every value the combiner builds, starting from the given one.

The answer opens with the starting value and holds one value for every item after it. So it is one longer than the List, and it is never empty. The empty List answers the starting value alone.

NameTypeDescription

startingWithAnswerthe value the first combination builds on

_(_: Answer, _: ItemType) -> Answerthe combiner, handed the value so far and each item

Returns the List of values, which is never empty.

Example

constant totals = [1, 2, 3]::accumulate(startingWith 0, (total, item) {
  <- total::add(item)
})

expect totals::is([0, 1, 3, 6])

everyValue

on List<ItemType>

everyValue<infer Other>(
	from transform: (_: ItemType) -> Optional<Other>,
) -> List<Other>

Answers every value the transform answers for an item.

The items the transform answers nothing for are left out, so the answer can be shorter than the receiver. It is map(transform)::values() in one walk.

NameTypeDescription

from(_: ItemType) -> Optional<Other>the transform each item is handed to

Returns the List of values.

Example

constant parsed = ["1", "x", "22"]::everyValue(from (text) {
  <- Integer.parse(text)
})

expect parsed::is([1, 22])

Ordering

reverse

on List<ItemType>

reverse() -> List<ItemType>

Answers a new List with the items in the opposite order.

Returns the reversed List.

Example

constant reversed = [1, 2, 3]::reverse()

expect reversed::is([3, 2, 1])

on NonEmptyList<ItemType>

reverse() -> NonEmptyList<ItemType>

Answers a new List with the items in the opposite order.

Returns the reversed List, which certainly has something in it.

Example

constant names: NonEmptyList<String> = ["Ada", "Grace"]

expect names::reverse()::is(["Grace", "Ada"])

sort

on List<ItemType>

Answers a new List in order, by the items' own ordering, by the given comparison, or by a key.

The sort is stable, so items the order does not tell apart keep the order they had, in either direction. The first entry is available whenever the items conform to Comparable.

A direction is read where one is taken, and it is #Ascending when a call names none.

Returns the ordered List.

sort<ItemType is Comparable>(
	in order: SortOrder = #Ascending,
) -> List<ItemType>

Answers a new List in the given direction, by the items' own ordering.

The sort is stable. The entry is available whenever the items conform to Comparable. The direction is #Ascending when a call names none. For any other order, use the by: entry.

NameTypeDescription

inSortOrder = #Ascendingthe direction to order in, #Ascending when it is left out

Returns the ordered List.

Example

constant scores: List<Integer> = [3, 1, 2]

expect scores::sort()::is([1, 2, 3])
expect scores::sort(in #Descending)::is([3, 2, 1])

sort(
	by comparison: (_: ItemType, _: ItemType) -> Ordering,
) -> List<ItemType>

Answers a new List ordered by the given comparison, applied to each pair of items.

The sort is stable.

NameTypeDescription

by(_: ItemType, _: ItemType) -> Orderingthe comparison to order the items with

Returns the ordered List.

Example

constant fruit: List<String> = ["pear", "fig", "apple"]
constant byLength = fruit::sort(by (a, b) {
	<- a::length()::compare(to b::length())
})

expect byLength::is(["fig", "pear", "apple"])

sort<infer Key is Comparable>(
	on key: (_: ItemType) -> Key,
	in order: SortOrder = #Ascending,
) -> List<ItemType>

Answers a new List in the given direction of what the key reads off each item.

The key is read once per item. The sort is stable, so items whose keys compare equal keep the order they had. The entry is available whenever what the key answers conforms to Comparable. The direction is #Ascending when a call names none.

NameTypeDescription

on(_: ItemType) -> Keythe key each item is ordered by

inSortOrder = #Ascendingthe direction to order in, #Ascending when it is left out

Returns the ordered List.

Example

constant fruit: List<String> = ["pear", "fig", "kiwi"]
constant bySize = fruit::sort(on (word) { <- word::length() })

expect bySize::is(["fig", "pear", "kiwi"])

on NonEmptyList<ItemType>

Answers a new List in order, by the items' own ordering, by the given comparison, or by a key.

The sort is stable, so items the order does not tell apart keep the order they had, in either direction. The first entry is available whenever the items conform to Comparable.

A direction is read where one is taken, and it is #Ascending when a call names none.

Returns the ordered List, which certainly has something in it.

sort<ItemType is Comparable>(
	in order: SortOrder = #Ascending,
) -> NonEmptyList<ItemType>

Answers a new List in the given direction, by the items' own ordering.

The sort is stable. The entry is available whenever the items conform to Comparable. The direction is #Ascending when a call names none. For any other order, use the by: entry.

NameTypeDescription

inSortOrder = #Ascendingthe direction to order in, #Ascending when it is left out

Returns the ordered List, which certainly has something in it.

Example

constant scores: NonEmptyList<Integer> = [3, 1, 2]

expect scores::sort()::is([1, 2, 3])
expect scores::sort(in #Descending)::is([3, 2, 1])

sort(
	by comparison: (_: ItemType, _: ItemType) -> Ordering,
) -> NonEmptyList<ItemType>

Answers a new List ordered by the given comparison, applied to each pair of items.

The sort is stable.

NameTypeDescription

by(_: ItemType, _: ItemType) -> Orderingthe comparison to order the items with

Returns the ordered List, which certainly has something in it.

Example

constant fruit: NonEmptyList<String> = ["pear", "fig", "apple"]
constant longestFirst = fruit::sort(by (a, b) {
	<- b::length()::compare(to a::length())
})

expect longestFirst::is(["apple", "pear", "fig"])

sort<infer Key is Comparable>(
	on key: (_: ItemType) -> Key,
	in order: SortOrder = #Ascending,
) -> NonEmptyList<ItemType>

Answers a new List in the given direction of what the key reads off each item.

NameTypeDescription

on(_: ItemType) -> Keythe key each item is ordered by

inSortOrder = #Ascendingthe direction to order in, #Ascending when it is left out

Returns the ordered List, which certainly has something in it.

Example

constant fruit: NonEmptyList<String> = ["fig", "pear", "kiwi"]
constant longestFirst = fruit::sort(
	on (word) { <- word::length() },
	in #Descending,
)

expect longestFirst::is(["pear", "kiwi", "fig"])

Slicing and splitting

slice

on List<ItemType>

slice(
	from start: Integer = 0,
	to end: Integer = @::length(),
) -> List<ItemType>

Answers a new List of the items from one position up to, but not including, another.

A negative position counts back from the end, so slice(from 0, to -1) drops the last item.

NameTypeDescription

fromInteger = 0the first position to include, counting from zero, or back from the end when negative. It is zero when the call leaves it out.

toInteger = @::length()the position to stop before, counting the same way. It is the length when the call leaves it out.

Returns the List of items in that range. It is empty when the range is empty, inverted, or entirely outside the List.

Example

constant letters = ["a", "b", "c", "d"]

expect letters::slice(from 1, to 3)::is(["b", "c"])
expect letters::slice(from 0, to -1)::is(["a", "b", "c"])
expect letters::slice(from 2)::is(["c", "d"])

partition

on List<ItemType>

Answers the List split in two: by a check, at the end of the leading run a check accepts, or at a position.

Both halves keep the original order, and every item of the receiver is in exactly one of them.

Returns a Record holding the two halves.

partition(
	where check: (_: ItemType) -> Boolean,
) -> { accepted: List<ItemType>, refused: List<ItemType> }

Answers the List split in two by the check: the items it accepts, and the items it refuses.

Both halves keep the original order. Each item is offered to the check once.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns a Record holding the accepted items under accepted and the others under refused.

Example

constant halves = [1, 2, 3, 4]::partition(where (n) { <- n::isEven() })

expect halves.accepted::is([2, 4])
expect halves.refused::is([1, 3])

partition(
	while check: (_: ItemType) -> Boolean,
) -> { leading: List<ItemType>, trailing: List<ItemType> }

Answers the List split at the end of the leading run the check accepts.

The walk stops at the first item the check refuses. That item opens the trailing half. A check that accepts every item answers the whole List under leading.

NameTypeDescription

while(_: ItemType) -> Booleanthe check the leading items are offered to

Returns a Record holding the leading run under leading and the rest under trailing.

Example

constant halves = [1, 2, 3, 1]::partition(while (n) { <- n::isLessThan(3) })

expect halves.leading::is([1, 2])
expect halves.trailing::is([3, 1])

partition(
	at index: Integer,
) -> { leading: List<ItemType>, trailing: List<ItemType> }

Answers the List split in two at the given position.

The item at that position opens the trailing half. A negative position counts back from the end: -1 cuts before the last item. A position outside the List leaves one half empty.

NameTypeDescription

atIntegerthe position to cut before

Returns a Record holding the items before that position under leading and the rest under trailing.

Example

constant halves = [1, 2, 3]::partition(at 1)

expect halves.leading::is([1])
expect halves.trailing::is([2, 3])

on List<Result<ValueType, FailureType>>

partition() -> { values: List<ValueType>, reasons: List<FailureType> }

Answers the Results split in two: the values they hold, and the reasons they failed with.

Both halves keep the original order. Every item of the receiver is in exactly one of them.

Returns a Record holding the values under values and the reasons under reasons.

Example

constant rows: List<Result<Integer, String>> = [
	#Value(1),
	#Failure("bad row"),
	#Value(3),
]
constant halves = rows::partition()

expect halves.values::is([1, 3])
expect halves.reasons::is(["bad row"])

split

on List<ItemType>

Answers the List split into groups of a given size, or into the pieces around the items a separator or a check picks out.

Returns the List of pieces.

split(intoGroupsOf size: Integer) -> List<NonEmptyList<ItemType>>

Answers the List split into groups of the given size, in order.

The last group holds whatever remains, so it can be shorter. Every group holds at least one item. A size below one names no grouping, and the answer is one group holding every item. The empty List answers no groups at all, whatever the size.

NameTypeDescription

intoGroupsOfIntegerhow many items each group holds

Returns the List of groups, each of which certainly has something in it.

Example

constant digits: List<Integer> = [1, 2, 3, 4, 5]
constant none: List<Integer> = []

expect digits::split(intoGroupsOf 2)::is([[1, 2], [3, 4], [5]])
expect digits::split(intoGroupsOf 0)::is([[1, 2, 3, 4, 5]])
expect none::split(intoGroupsOf 2)::isEmpty()

split<ItemType is Equatable>(
	on separator: ItemType,
) -> NonEmptyList<List<ItemType>>

Answers the pieces around every item equal to the given one.

The separators are not in the answer. Two separators next to each other leave the empty piece between them, and a separator at an end leaves one there. Equality is the items' own is. The entry is available whenever the items conform to Equatable.

NameTypeDescription

onItemTypethe item to split at

Returns the List of pieces, which always holds at least one.

Example

expect [1, 0, 2, 3]::split(on 0)::is([[1], [2, 3]])

split(
	where check: (_: ItemType) -> Boolean,
) -> NonEmptyList<List<ItemType>>

Answers the pieces around every item the check accepts.

The accepted items are not in the answer. Two accepted items next to each other leave the empty piece between them, and one at an end leaves one there. The empty List answers one empty piece.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns the List of pieces, which always holds at least one.

Example

expect [1, 2, 3]::split(where (n) { <- n::isEven() })::is([[1], [3]])

on NonEmptyList<ItemType>

split(
	intoGroupsOf size: Integer,
) -> NonEmptyList<NonEmptyList<ItemType>>

Answers the List split into groups of the given size, in order.

The last group holds whatever remains, so it can be shorter. A size below one names no grouping, and the answer is one group holding every item.

NameTypeDescription

intoGroupsOfIntegerhow many items each group holds

Returns the List of groups, which certainly has one, and each group certainly has an item.

Example

constant digits: NonEmptyList<Integer> = [1, 2, 3]
constant groups = digits::split(intoGroupsOf 2)

expect groups::is([[1, 2], [3]])
expect groups::firstItem()::firstItem()::is(1)

windows

on List<ItemType>

windows(of size: PositiveInteger) -> List<NonEmptyList<ItemType>>

Answers every stretch of the given size, one position at a time.

The stretches overlap: each starts one position after the one before it. A size above the length answers no stretches at all, and so does the empty List. Every stretch holds the given number of items. For the pairs of neighbours alone, list::pair(with list::removeFirst()) answers a Record of first and second per pair and reads better.

NameTypeDescription

ofPositiveIntegerhow many items each stretch holds, which is above zero

Returns the List of stretches, each of which certainly has something in it.

Example

expect [1, 2, 3, 4]::windows(of 2)::is([[1, 2], [2, 3], [3, 4]])
expect [1, 2]::windows(of 3)::isEmpty()

runs

on List<ItemType>

runs(
	where check: (_: ItemType) -> Boolean,
) -> List<NonEmptyList<ItemType>>

Answers the stretches of neighbouring items the check accepts.

A stretch ends at the first item the check refuses, and the refused items are in no stretch. Every stretch holds at least one item. A List the check accepts no item of answers no stretches, and so does the empty List.

NameTypeDescription

where(_: ItemType) -> Booleanthe check each item is offered to

Returns the List of stretches, each of which certainly has something in it.

Example

expect [1, 3, 2, 5, 7]::runs(where (n) { <- n::isOdd() })
    ::is([[1, 3], [5, 7]])

Combining

join

on List<ItemType>

join<ItemType is Printable>(with separator: String) -> String

Answers the items joined into one String, with the given separator between them.

Each item is rendered by its own toString: [1, 2, 3]::join(with ", ") is "1, 2, 3". The answer is the raw text, so a String item is not quoted, which is where joining differs from toString. For a List of Strings the Method undoes String::split(on:). It is available whenever the items conform to Printable.

NameTypeDescription

withStringthe separator to place between the items

Returns the joined String. The empty List answers the empty String.

Example

expect [1, 2, 3]::join(with ", ")::is("1, 2, 3")
expect ["Ada", "Grace"]::join(with " & ")::is("Ada & Grace")

pair

on List<ItemType>

pair<infer Other>(
	with other: List<Other>,
) -> List<{ first: ItemType, second: Other }>

Answers the items of the two Lists paired position by position.

The pairing stops with the shorter List.

NameTypeDescription

withList<Other>the List to pair the items with

Returns a List of Records, each holding one item of this List under first and its counterpart under second.

Example

constant letters: List<String> = ["a", "b", "c"]

expect letters::pair(with [1, 2])::is([
	{ first = "a", second = 1 },
	{ first = "b", second = 2 },
])

on NonEmptyList<ItemType>

pair<infer Other>(
	with other: NonEmptyList<Other>,
) -> NonEmptyList<{ first: ItemType, second: Other }>

Answers the items of the two Lists paired position by position.

The pairing stops with the shorter List, which certainly has something in it.

NameTypeDescription

withNonEmptyList<Other>the List to pair the items with

Returns a List of Records, each holding one item of this List under first and its counterpart under second. It is never empty.

Example

constant letters: NonEmptyList<String> = ["a", "b"]
constant pairs = letters::pair(with [1, 2, 3])

expect pairs::firstItem()::is({ first = "a", second = 1 })
expect pairs::length()::is(2)

Nested lists

flatten

on List<List<ItemType>>

flatten() -> List<ItemType>

Answers the inner Lists flattened by one level, into a single List.

Every inner List's items keep their order.

Returns the flattened List.

Example

expect [[1, 2], [], [3]]::flatten()::is([1, 2, 3])

on NonEmptyList<NonEmptyList<ItemType>>

flatten() -> NonEmptyList<ItemType>

Answers the inner Lists flattened by one level, into a single List.

Every inner List's items keep their order.

Returns the flattened List, which certainly has something in it.

Example

constant groups: NonEmptyList<NonEmptyList<Integer>> = [[1, 2], [3]]
constant digits: NonEmptyList<Integer> = groups::flatten()

expect digits::is([1, 2, 3])

transpose

on List<List<ItemType>>

transpose() -> List<List<ItemType>>

Answers the inner Lists turned round: one List per position, holding what each inner List has there.

The shortest inner List decides how many the answer holds, as pair(with:) does. An empty inner List answers no Lists at all, and so does the empty List of Lists. Transposing twice answers the receiver where every inner List is the same length.

Returns the List of positions, each holding one item of every inner List.

Example

expect [[1, 2, 3], [4, 5, 6]]::transpose()::is([[1, 4], [2, 5], [3, 6]])

Lists of Optionals and Results

values

on List<Optional<ItemType>>

values() -> List<ItemType>

Answers the values the Optionals hold, in order.

The empty Optionals are left out, so the answer can be shorter than the receiver. A List of empty Optionals answers the empty List. Where one empty Optional has to answer nothing at all, the Method is allValues().

Returns the List of values.

Example

constant parsed = ["1", "x", "3"]::map((text) {
	<- Integer.parse(text)
})

expect parsed::values()::is([1, 3])

on List<Result<ValueType, FailureType>>

values() -> List<ValueType>

Answers the values the Results hold, in order.

The failed Results are left out, so the answer can be shorter than the receiver. A List of failed Results answers the empty List. Where one failure has to answer nothing at all, the Method is allValues().

Returns the List of values.

Example

constant rows: List<Result<Integer, String>> = [
	#Value(1),
	#Failure("bad row"),
	#Value(3),
]

expect rows::values()::is([1, 3])

allValues

on List<Optional<ItemType>>

allValues() -> Optional<List<ItemType>>

Answers every value in order, and nothing where an Optional is empty.

The answer holds one value for every item of the receiver. The empty List answers the empty List, held in an Optional.

Returns the List of every value, or an empty Optional.

Example

constant rows: List<Optional<Integer>> = [#Value(1), #Value(2)]

expect rows::allValues()::is(#Value([1, 2]))

on List<Result<ValueType, FailureType>>

allValues() -> Result<List<ValueType>, NonEmptyList<FailureType>>

Answers every value in order, and every reason where anything failed.

The answer holds one value for every item of the receiver. A single failure decides the answer, and the reasons are kept in the order they stand in. The empty List answers the empty List, held in a value. Where only the first reason is wanted, reason()::map((reasons) { <- reasons::firstItem() }) reads it.

Returns every value in a Result, or every reason in one.

Example

constant rows: List<Result<Integer, String>> = [#Value(1), #Value(2)]

expect rows::allValues()::is(#Value([1, 2]))

firstValue

on List<Optional<ItemType>>

firstValue() -> Optional<ItemType>

Answers the value of the first Optional that holds one.

The walk stops at that Optional. A List holding nothing but empty Optionals answers empty, and so does the empty List.

Returns the first value, or an empty Optional.

Example

constant parsed = ["x", "2", "3"]::map((text) {
	<- Integer.parse(text)
})
constant none: List<Optional<Integer>> = [#Empty, #Empty]

expect parsed::firstValue()::is(2)
expect none::firstValue()::isEmpty()

reasons

on List<Result<ValueType, FailureType>>

reasons() -> List<FailureType>

Answers the reasons the failed Results hold, in order.

The Results holding a value are left out. A List of values answers the empty List.

Returns the List of reasons.

Example

constant rows: List<Result<Integer, String>> = [
	#Value(1),
	#Failure("bad row"),
	#Value(3),
]

expect rows::reasons()::is(["bad row"])

partition on List<Result<ValueType, FailureType>> is listed under partition, with the other entries of that name.

Grouping into a Dictionary

group

on List<ItemType>

group<infer Key is Equatable>(
	on key: (_: ItemType) -> Key,
) -> Dictionary<Key, NonEmptyList<ItemType>>

Answers the items grouped under the key the given Function reads off each one.

The groups stand in the order their keys first appear, and the items of a group keep the order they had. Every group holds at least one item, and the empty List answers the empty Dictionary. Equality is the keys' own is. The List of groups is what entries() answers: one Record per group, holding the key and its items under value.

NameTypeDescription

on(_: ItemType) -> Keythe key read off each item

Returns the Dictionary of groups, each of which has an item in it.

Example

constant names = ["Ada", "Alan", "Bob"]
constant nobody: List<String> = []
constant byLength = names::group(on (name) { <- name::length() })

expect byLength::is([3 = ["Ada", "Bob"], 4 = ["Alan"]])
expect byLength::keys()::is([3, 4])
expect nobody::group(on (name) { <- name::length() })::isEmpty()

on NonEmptyList<ItemType>

group<infer Key is Equatable>(
	on key: (_: ItemType) -> Key,
) -> NonEmptyDictionary<Key, NonEmptyList<ItemType>>

Answers the items grouped under the key the given Function reads off each one.

The groups stand in the order their keys first appear, and the items of a group keep the order they had. Every group holds at least one item. Equality is the keys' own is.

NameTypeDescription

on(_: ItemType) -> Keythe key read off each item

Returns the Dictionary of groups, which certainly has a group in it.

Example

constant byLength = ["Ada", "Alan", "Bob"]::group(on (name) {
	<- name::length()
})

expect byLength::is([3 = ["Ada", "Bob"], 4 = ["Alan"]])

tally

on List<ItemType>

tally<ItemType is Equatable>() -> Dictionary<ItemType, PositiveInteger>

Answers how many times each item occurs.

The items stand in the order they first appear. Equality is the items' own is.

Returns the Dictionary of counts, each of which is above zero.

Example

constant orders = ["tea", "jam", "tea"]

expect orders::tally()::is(["tea" = 2, "jam" = 1])
expect orders::tally()::keys()::is(["tea", "jam"])

on NonEmptyList<ItemType>

tally<ItemType is Equatable>()
	-> NonEmptyDictionary<ItemType, PositiveInteger>

Answers how many times each item occurs.

The items stand in the order they first appear. Equality is the items' own is.

Returns the Dictionary of counts, which certainly has a count in it.

Example

constant { key, value } = ["tea", "jam", "tea"]::tally()::firstEntry()

expect key::is("tea")
expect value::is(2)

index

on List<ItemType>

index<infer Key is Equatable>(
	on key: (_: ItemType) -> Key,
) -> Dictionary<Key, ItemType>

Answers the items under the key the given Function reads off each one, one item per key.

A later item with the same key replaces the earlier one as the value. The key keeps the place it was first met at, as set does. The keys stand in the order they first appear. Equality is the keys' own is. To keep every item under a key, use group(on:).

NameTypeDescription

on(_: ItemType) -> Keythe key read off each item

Returns the Dictionary of items, keyed by what the Function read off each.

Example

constant names = ["Ada", "Alan", "Bob"]
constant byLength = names::index(on (name) { <- name::length() })

expect byLength::is([3 = "Bob", 4 = "Alan"])
expect byLength::keys()::is([3, 4])

on NonEmptyList<ItemType>

index<infer Key is Equatable>(
	on key: (_: ItemType) -> Key,
) -> NonEmptyDictionary<Key, ItemType>

Answers the items under the key the given Function reads off each one, one item per key.

NameTypeDescription

on(_: ItemType) -> Keythe key read off each item

Returns the Dictionary of items, which certainly has an entry in it.

Example

constant byLength = ["Ada", "Alan", "Bob"]::index(on (name) {
	<- name::length()
})

expect byLength::is([3 = "Bob", 4 = "Alan"])

Lists of numbers: totals

sum

on List<Integer>

sum() -> Integer

Adds every item together.

The empty List totals zero.

Returns the total.

Example

constant empty: List<Integer> = []

expect [3, 5, 2]::sum()::is(10)
expect empty::sum()::is(0)

on List<Rational>

sum() -> Rational

Adds every item together.

The empty List totals zero.

Returns the total.

Example

constant empty: List<Rational> = []

expect [1/2, 1/4, 1/4]::sum()::is(1/1)
expect empty::sum()::is(0/1)

on List<Scalar>

sum() -> Scalar

Adds every item together.

The empty List totals zero. A whole total answers as an Integer, and a fractional one as a Rational.

Returns the total.

Example

constant empty: List<Scalar> = []

expect [1, 1/2, 1/2]::sum()::is(2)
expect [1, 1/2]::sum()::is(3/2)
expect empty::sum()::is(0)

on List<ItemType>

Adds together what the key reads off every item.

The empty List totals zero.

Returns the total.

sum(on key: (_: ItemType) -> Integer) -> Integer

Adds together the Integers the key reads off the items.

NameTypeDescription

on(_: ItemType) -> Integerthe key read off each item

Returns the total.

Example

constant orders = [{ total = 30 }, { total = 12 }]

expect orders::sum(on .total)::is(42)

sum(on key: (_: ItemType) -> Rational) -> Rational

Adds together the Rationals the key reads off the items.

NameTypeDescription

on(_: ItemType) -> Rationalthe key read off each item

Returns the total.

Example

constant parcels = [{ weight = 1/2 }, { weight = 3/4 }]

expect parcels::sum(on .weight)::is(5/4)

sum(on key: (_: ItemType) -> Scalar) -> Scalar

Adds together the Numbers the key reads off the items.

A whole total answers as an Integer, and a fractional one as a Rational.

NameTypeDescription

on(_: ItemType) -> Scalarthe key read off each item

Returns the total.

Example

constant cells = ["3", "1/2", "1/2"]
constant total = cells::sum(on (text) {
	<- Number.parse(text, defaultingTo 0)
})

expect total::is(4)

product

on List<Integer>

product() -> Integer

Multiplies every item together.

The empty List answers one.

Returns the product.

Example

constant empty: List<Integer> = []

expect [2, 3, 4]::product()::is(24)
expect empty::product()::is(1)

on List<Rational>

product() -> Rational

Multiplies every item together.

The empty List answers one.

Returns the product.

Example

constant empty: List<Rational> = []

expect [1/2, 2/3]::product()::is(1/3)
expect empty::product()::is(1/1)

on List<Scalar>

product() -> Scalar

Multiplies every item together.

The empty List answers one. A whole product answers as an Integer, and a fractional one as a Rational.

Returns the product.

Example

constant empty: List<Scalar> = []

expect [4, 1/2]::product()::is(2)
expect [3, 1/2]::product()::is(3/2)
expect empty::product()::is(1)

on List<ItemType>

Multiplies together what the key reads off every item.

The empty List answers one.

Returns the product.

product(on key: (_: ItemType) -> Integer) -> Integer

Multiplies together the Integers the key reads off the items.

NameTypeDescription

on(_: ItemType) -> Integerthe key read off each item

Returns the product.

Example

constant dice = [{ sides = 6 }, { sides = 4 }]

expect dice::product(on .sides)::is(24)

product(on key: (_: ItemType) -> Rational) -> Rational

Multiplies together the Rationals the key reads off the items.

NameTypeDescription

on(_: ItemType) -> Rationalthe key read off each item

Returns the product.

Example

constant steps = [{ chance = 1/2 }, { chance = 1/3 }]

expect steps::product(on .chance)::is(1/6)

product(on key: (_: ItemType) -> Scalar) -> Scalar

Multiplies together the Numbers the key reads off the items.

A whole product answers as an Integer, and a fractional one as a Rational.

NameTypeDescription

on(_: ItemType) -> Scalarthe key read off each item

Returns the product.

Example

constant cells   = ["4", "1/2"]
constant product = cells::product(on (text) {
	<- Number.parse(text, defaultingTo 0)
})

expect product::is(2)

runningTotal

on List<Integer>

runningTotal() -> NonEmptyList<Integer>

Every total the items build, one after another.

The answer opens with zero and holds one total for every item after it. So it is one longer than the List, and it is never empty. The last total is what sum answers.

Returns the List of totals, which is never empty.

Example

constant empty: List<Integer> = []

expect [3, 5, 2]::runningTotal()::is([0, 3, 8, 10])
expect empty::runningTotal()::is([0])

on List<Rational>

runningTotal() -> NonEmptyList<Rational>

Every total the items build, one after another.

The answer opens with zero and holds one total for every item after it. So it is one longer than the List, and it is never empty. The last total is what sum answers.

Returns the List of totals, which is never empty.

Example

constant empty: List<Rational> = []

expect [1/2, 1/4, 1/4]::runningTotal()::is([0/1, 1/2, 3/4, 1/1])
expect empty::runningTotal()::is([0/1])

on List<Scalar>

runningTotal() -> NonEmptyList<Scalar>

Every total the items build, one after another.

The answer opens with zero and holds one total for every item after it. So it is one longer than the List, and it is never empty. A total stays a Rational once a Rational has been added to it, where sum collapses a whole total to an Integer.

Returns the List of totals, which is never empty.

Example

constant empty: List<Scalar> = []

expect [1, 1/2, 1/2]::runningTotal()::is([0, 1, 3/2, 2])
expect empty::runningTotal()::is([0])

Lists of numbers: statistics

average

on List<Integer>

The mean of the items: their total divided by their count.

The empty List has no mean, and the defaultingTo: entry answers the given Rational in place of nothing.

average() -> Optional<Rational>

The mean of the items.

Returns the mean, or nothing for the empty List.

Example

constant scores: List<Integer> = [1, 2, 3, 4]
constant empty: List<Integer>  = []

expect scores::average()::is(5/2)
expect empty::average()::isEmpty()

average(defaultingTo fallback: Rational) -> Rational

The mean of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToRationalthe mean to answer with when there is none

Returns the mean, or the fallback in its place.

Example

constant scores: List<Integer> = [1, 2, 3, 4]
constant empty: List<Integer>  = []

expect scores::average(defaultingTo 0/1)::is(5/2)
expect empty::average(defaultingTo 0/1)::is(0/1)

on List<Rational>

The mean of the items: their total divided by their count.

The empty List has no mean, and the defaultingTo: entry answers the given Rational in place of nothing.

average() -> Optional<Rational>

The mean of the items.

Returns the mean, or nothing for the empty List.

Example

constant weights: List<Rational> = [1/2, 3/2]
constant empty: List<Rational>   = []

expect weights::average()::is(1/1)
expect empty::average()::isEmpty()

average(defaultingTo fallback: Rational) -> Rational

The mean of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToRationalthe mean to answer with when there is none

Returns the mean, or the fallback in its place.

Example

constant weights: List<Rational> = [1/2, 3/2]
constant empty: List<Rational>   = []

expect weights::average(defaultingTo 0/1)::is(1/1)
expect empty::average(defaultingTo 0/1)::is(0/1)

on List<Scalar>

The mean of the items: their total divided by their count.

The empty List has no mean, and the defaultingTo: entry answers the given Rational in place of nothing.

average() -> Optional<Rational>

The mean of the items.

Returns the mean, or nothing for the empty List.

Example

constant amounts: List<Scalar> = [1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::average()::is(3/4)
expect empty::average()::isEmpty()

average(defaultingTo fallback: Rational) -> Rational

The mean of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToRationalthe mean to answer with when there is none

Returns the mean, or the fallback in its place.

Example

constant amounts: List<Scalar> = [1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::average(defaultingTo 0/1)::is(3/4)
expect empty::average(defaultingTo 0/1)::is(0/1)

on List<ItemType>

The mean of what the key reads off every item: their total divided by their count.

The empty List has no mean, and the defaultingTo: entry answers the given Rational in place of nothing.

average(on key: (_: ItemType) -> Scalar) -> Optional<Rational>

The mean of what the key reads off the items.

NameTypeDescription

on(_: ItemType) -> Scalarthe key read off each item

Returns the mean, or nothing for the empty List.

Example

constant orders: List<{ total: Integer }> = [
	{ total = 30 },
	{ total = 12 },
]
constant empty: List<{ total: Integer }>  = []

expect orders::average(on .total)::is(21/1)
expect empty::average(on .total)::isEmpty()

average(
	on key: (_: ItemType) -> Scalar,
	defaultingTo fallback: Rational,
) -> Rational

The mean of what the key reads off the items, or the given fallback for the empty List.

NameTypeDescription

on(_: ItemType) -> Scalarthe key read off each item

defaultingToRationalthe mean to answer with when there is none

Returns the mean, or the fallback in its place.

Example

constant orders: List<{ total: Integer }> = [
	{ total = 30 },
	{ total = 12 },
]
constant empty: List<{ total: Integer }>  = []

expect orders::average(on .total, defaultingTo 0/1)::is(21/1)
expect empty::average(on .total, defaultingTo 0/1)::is(0/1)

on NonEmptyList<Integer>

average() -> Rational

The mean of the items: their total divided by their count.

Returns the mean.

Example

expect [1, 2, 3, 4]::average()::is(5/2)

on NonEmptyList<Rational>

average() -> Rational

The mean of the items: their total divided by their count.

Returns the mean.

Example

expect [1/2, 3/2]::average()::is(1/1)

on NonEmptyList<Scalar>

average() -> Rational

The mean of the items: their total divided by their count.

Returns the mean.

Example

expect [1, 1/2]::average()::is(3/4)

on NonEmptyList<ItemType>

average(on key: (_: ItemType) -> Scalar) -> Rational

The mean of what the key reads off every item: their total divided by their count.

The List has an item, so the answer is the mean itself rather than an Optional.

NameTypeDescription

on(_: ItemType) -> Scalarthe key read off each item

Returns the mean.

Example

constant orders: NonEmptyList<{ total: Integer }> = [
	{ total = 30 },
	{ total = 12 },
]

expect orders::average(on .total)::is(21/1)

lowestNumber

on List<Integer>

The lowest item.

The empty List has no lowest item, and the defaultingTo: entry answers the given item in place of nothing.

lowestNumber() -> Optional<Integer>

The lowest item.

Returns the lowest item, or nothing for the empty List.

Example

constant scores: List<Integer> = [7, 3, 9]
constant empty: List<Integer>  = []

expect scores::lowestNumber()::is(3)
expect empty::lowestNumber()::isEmpty()

lowestNumber(defaultingTo fallback: Integer) -> Integer

The lowest item, or the given fallback for the empty List.

NameTypeDescription

defaultingToIntegerthe item to answer with when there is none

Returns the lowest item, or the fallback in its place.

Example

constant scores: List<Integer> = [7, 3, 9]
constant empty: List<Integer>  = []

expect scores::lowestNumber(defaultingTo 0)::is(3)
expect empty::lowestNumber(defaultingTo 0)::is(0)

on List<Rational>

The lowest item.

The empty List has no lowest item, and the defaultingTo: entry answers the given item in place of nothing.

lowestNumber() -> Optional<Rational>

The lowest item.

Returns the lowest item, or nothing for the empty List.

Example

constant weights: List<Rational> = [3/4, 1/2, 5/4]
constant empty: List<Rational>   = []

expect weights::lowestNumber()::is(1/2)
expect empty::lowestNumber()::isEmpty()

lowestNumber(defaultingTo fallback: Rational) -> Rational

The lowest item, or the given fallback for the empty List.

NameTypeDescription

defaultingToRationalthe item to answer with when there is none

Returns the lowest item, or the fallback in its place.

Example

constant weights: List<Rational> = [3/4, 1/2, 5/4]
constant empty: List<Rational>   = []

expect weights::lowestNumber(defaultingTo 0/1)::is(1/2)
expect empty::lowestNumber(defaultingTo 0/1)::is(0/1)

on List<Scalar>

The lowest item.

The empty List has no lowest item, and the defaultingTo: entry answers the given item in place of nothing.

lowestNumber() -> Optional<Scalar>

The lowest item.

Returns the lowest item, or nothing for the empty List.

Example

constant amounts: List<Scalar> = [2, 1/2, 1]
constant empty: List<Scalar>   = []

expect amounts::lowestNumber()::is(1/2)
expect empty::lowestNumber()::isEmpty()

lowestNumber(defaultingTo fallback: Scalar) -> Scalar

The lowest item, or the given fallback for the empty List.

NameTypeDescription

defaultingToScalarthe item to answer with when there is none

Returns the lowest item, or the fallback in its place.

Example

constant amounts: List<Scalar> = [2, 1/2, 1]
constant empty: List<Scalar>   = []

expect amounts::lowestNumber(defaultingTo 0)::is(1/2)
expect empty::lowestNumber(defaultingTo 0)::is(0)

on NonEmptyList<Integer>

lowestNumber() -> Integer

The lowest item, which a non-empty List always has.

Returns the lowest item.

Example

expect [7, 3, 9]::lowestNumber()::is(3)

on NonEmptyList<Rational>

lowestNumber() -> Rational

The lowest item, which a non-empty List always has.

Returns the lowest item.

Example

expect [3/4, 1/2, 5/4]::lowestNumber()::is(1/2)

on NonEmptyList<Scalar>

lowestNumber() -> Scalar

The lowest item, which a non-empty List always has.

Returns the lowest item.

Example

expect [2, 1/2, 1]::lowestNumber()::is(1/2)

highestNumber

on List<Integer>

The highest item.

The empty List has no highest item, and the defaultingTo: entry answers the given item in place of nothing.

highestNumber() -> Optional<Integer>

The highest item.

Returns the highest item, or nothing for the empty List.

Example

constant scores: List<Integer> = [7, 3, 9]
constant empty: List<Integer>  = []

expect scores::highestNumber()::is(9)
expect empty::highestNumber()::isEmpty()

highestNumber(defaultingTo fallback: Integer) -> Integer

The highest item, or the given fallback for the empty List.

NameTypeDescription

defaultingToIntegerthe item to answer with when there is none

Returns the highest item, or the fallback in its place.

Example

constant scores: List<Integer> = [7, 3, 9]
constant empty: List<Integer>  = []

expect scores::highestNumber(defaultingTo 0)::is(9)
expect empty::highestNumber(defaultingTo 0)::is(0)

on List<Rational>

The highest item.

The empty List has no highest item, and the defaultingTo: entry answers the given item in place of nothing.

highestNumber() -> Optional<Rational>

The highest item.

Returns the highest item, or nothing for the empty List.

Example

constant weights: List<Rational> = [3/4, 1/2, 5/4]
constant empty: List<Rational>   = []

expect weights::highestNumber()::is(5/4)
expect empty::highestNumber()::isEmpty()

highestNumber(defaultingTo fallback: Rational) -> Rational

The highest item, or the given fallback for the empty List.

NameTypeDescription

defaultingToRationalthe item to answer with when there is none

Returns the highest item, or the fallback in its place.

Example

constant weights: List<Rational> = [3/4, 1/2, 5/4]
constant empty: List<Rational>   = []

expect weights::highestNumber(defaultingTo 0/1)::is(5/4)
expect empty::highestNumber(defaultingTo 0/1)::is(0/1)

on List<Scalar>

The highest item.

The empty List has no highest item, and the defaultingTo: entry answers the given item in place of nothing.

highestNumber() -> Optional<Scalar>

The highest item.

Returns the highest item, or nothing for the empty List.

Example

constant amounts: List<Scalar> = [2, 1/2, 1]
constant empty: List<Scalar>   = []

expect amounts::highestNumber()::is(2)
expect empty::highestNumber()::isEmpty()

highestNumber(defaultingTo fallback: Scalar) -> Scalar

The highest item, or the given fallback for the empty List.

NameTypeDescription

defaultingToScalarthe item to answer with when there is none

Returns the highest item, or the fallback in its place.

Example

constant amounts: List<Scalar> = [2, 1/2, 1]
constant empty: List<Scalar>   = []

expect amounts::highestNumber(defaultingTo 0)::is(2)
expect empty::highestNumber(defaultingTo 0)::is(0)

on NonEmptyList<Integer>

highestNumber() -> Integer

The highest item, which a non-empty List always has.

Returns the highest item.

Example

expect [7, 3, 9]::highestNumber()::is(9)

on NonEmptyList<Rational>

highestNumber() -> Rational

The highest item, which a non-empty List always has.

Returns the highest item.

Example

expect [3/4, 1/2, 5/4]::highestNumber()::is(5/4)

on NonEmptyList<Scalar>

highestNumber() -> Scalar

The highest item, which a non-empty List always has.

Returns the highest item.

Example

expect [2, 1/2, 1]::highestNumber()::is(2)

median

on List<Integer>

The middle item, once the items are put in order.

A count that is even has two middle items, and the answer is their mean. The empty List has no median, and the defaultingTo: entry answers the given Rational in place of nothing.

median() -> Optional<Rational>

The median of the items.

Returns the median, or nothing for the empty List.

Example

constant scores: List<Integer> = [9, 1, 5]
constant empty: List<Integer>  = []

expect scores::median()::is(5/1)
expect empty::median()::isEmpty()

median(defaultingTo fallback: Rational) -> Rational

The median of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToRationalthe median to answer with when there is none

Returns the median, or the fallback in its place.

Example

constant scores: List<Integer> = [9, 1, 5]
constant empty: List<Integer>  = []

expect scores::median(defaultingTo 0/1)::is(5/1)
expect empty::median(defaultingTo 0/1)::is(0/1)

on List<Rational>

The middle item, once the items are put in order.

A count that is even has two middle items, and the answer is their mean. The empty List has no median, and the defaultingTo: entry answers the given Rational in place of nothing.

median() -> Optional<Rational>

The median of the items.

Returns the median, or nothing for the empty List.

Example

constant weights: List<Rational> = [3/4, 1/4, 1/2]
constant empty: List<Rational>   = []

expect weights::median()::is(1/2)
expect empty::median()::isEmpty()

median(defaultingTo fallback: Rational) -> Rational

The median of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToRationalthe median to answer with when there is none

Returns the median, or the fallback in its place.

Example

constant weights: List<Rational> = [3/4, 1/4, 1/2]
constant empty: List<Rational>   = []

expect weights::median(defaultingTo 0/1)::is(1/2)
expect empty::median(defaultingTo 0/1)::is(0/1)

on List<Scalar>

The middle item, once the items are put in order.

A count that is even has two middle items, and the answer is their mean. The empty List has no median, and the defaultingTo: entry answers the given Rational in place of nothing.

median() -> Optional<Rational>

The median of the items.

Returns the median, or nothing for the empty List.

Example

constant amounts: List<Scalar> = [2, 1/2, 1]
constant empty: List<Scalar>   = []

expect amounts::median()::is(1/1)
expect empty::median()::isEmpty()

median(defaultingTo fallback: Rational) -> Rational

The median of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToRationalthe median to answer with when there is none

Returns the median, or the fallback in its place.

Example

constant amounts: List<Scalar> = [2, 1/2, 1]
constant empty: List<Scalar>   = []

expect amounts::median(defaultingTo 0/1)::is(1/1)
expect empty::median(defaultingTo 0/1)::is(0/1)

on NonEmptyList<Integer>

median() -> Rational

The middle item, once the items are put in order.

A count that is even has two middle items, and the answer is their mean.

Returns the median.

Example

expect [9, 1, 5]::median()::is(5/1)
expect [4, 1, 3, 2]::median()::is(5/2)

on NonEmptyList<Rational>

median() -> Rational

The middle item, once the items are put in order.

A count that is even has two middle items, and the answer is their mean.

Returns the median.

Example

expect [3/4, 1/4, 1/2]::median()::is(1/2)
expect [3/4, 1/4]::median()::is(1/2)

on NonEmptyList<Scalar>

median() -> Rational

The middle item, once the items are put in order.

A count that is even has two middle items, and the answer is their mean.

Returns the median.

Example

expect [2, 1/2, 1]::median()::is(1/1)
expect [1, 1/2]::median()::is(3/4)

percentile

on List<Integer>

The value at the given position through the items, once they are put in order.

A position between two items answers the point between those items, in proportion. The fraction is clamped between zero and one. The empty List has no such value, and the defaultingTo: entry answers the given Rational in place of nothing.

percentile(_ fraction: Rational) -> Optional<Rational>

The value at the given position through the items.

NameTypeDescription

_Rationalthe position through the items, from zero to one

Returns the value, or nothing for the empty List.

Example

constant scores: List<Integer> = [40, 10, 30, 20]
constant empty: List<Integer>  = []

expect scores::percentile(1/2)::is(25/1)
expect empty::percentile(1/2)::isEmpty()

percentile(
	_ fraction: Rational,
	defaultingTo fallback: Rational,
) -> Rational

The value at the given position, or the given fallback for the empty List.

NameTypeDescription

_Rationalthe position through the items, from zero to one

defaultingToRationalthe value to answer with when there is none

Returns the value, or the fallback in its place.

Example

constant scores: List<Integer> = [40, 10, 30, 20]
constant empty: List<Integer>  = []

expect scores::percentile(1/2, defaultingTo 0/1)::is(25/1)
expect empty::percentile(1/2, defaultingTo 0/1)::is(0/1)

on List<Rational>

The value at the given position through the items, once they are put in order.

percentile(_ fraction: Rational) -> Optional<Rational>

The value at the given position through the items.

NameTypeDescription

_Rationalthe position through the items, from zero to one

Returns the value, or nothing for the empty List.

Example

constant weights: List<Rational> = [3/4, 1/4]
constant empty: List<Rational>   = []

expect weights::percentile(1/2)::is(1/2)
expect empty::percentile(1/2)::isEmpty()

percentile(
	_ fraction: Rational,
	defaultingTo fallback: Rational,
) -> Rational

The value at the given position, or the given fallback for the empty List.

NameTypeDescription

_Rationalthe position through the items, from zero to one

defaultingToRationalthe value to answer with when there is none

Returns the value, or the fallback in its place.

Example

constant weights: List<Rational> = [3/4, 1/4]
constant empty: List<Rational>   = []

expect weights::percentile(1/2, defaultingTo 0/1)::is(1/2)
expect empty::percentile(1/2, defaultingTo 0/1)::is(0/1)

on List<Scalar>

The value at the given position through the items, once they are put in order.

percentile(_ fraction: Rational) -> Optional<Rational>

The value at the given position through the items.

NameTypeDescription

_Rationalthe position through the items, from zero to one

Returns the value, or nothing for the empty List.

Example

constant amounts: List<Scalar> = [1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::percentile(1/2)::is(3/4)
expect empty::percentile(1/2)::isEmpty()

percentile(
	_ fraction: Rational,
	defaultingTo fallback: Rational,
) -> Rational

The value at the given position, or the given fallback for the empty List.

NameTypeDescription

_Rationalthe position through the items, from zero to one

defaultingToRationalthe value to answer with when there is none

Returns the value, or the fallback in its place.

Example

constant amounts: List<Scalar> = [1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::percentile(1/2, defaultingTo 0/1)::is(3/4)
expect empty::percentile(1/2, defaultingTo 0/1)::is(0/1)

on NonEmptyList<Integer>

percentile(_ fraction: Rational) -> Rational

The value at the given position through the items, once they are put in order.

A position between two items answers the point between those items, in proportion. The fraction is clamped between zero and one.

NameTypeDescription

_Rationalthe position through the items, from zero to one

Returns the value at that position.

Example

constant scores: NonEmptyList<Integer> = [40, 10, 30, 20]

expect scores::percentile(1/2)::is(25/1)
expect scores::percentile(2/1)::is(40/1)

on NonEmptyList<Rational>

percentile(_ fraction: Rational) -> Rational

The value at the given position through the items, once they are put in order.

A position between two items answers the point between those items, in proportion. The fraction is clamped between zero and one.

NameTypeDescription

_Rationalthe position through the items, from zero to one

Returns the value at that position.

Example

constant weights: NonEmptyList<Rational> = [3/4, 1/4]

expect weights::percentile(1/2)::is(1/2)
expect weights::percentile(2/1)::is(3/4)

on NonEmptyList<Scalar>

percentile(_ fraction: Rational) -> Rational

The value at the given position through the items, once they are put in order.

A position between two items answers the point between those items, in proportion. The fraction is clamped between zero and one.

NameTypeDescription

_Rationalthe position through the items, from zero to one

Returns the value at that position.

Example

constant amounts: NonEmptyList<Scalar> = [1, 1/2]

expect amounts::percentile(1/2)::is(3/4)
expect amounts::percentile(2/1)::is(1/1)

mode

on List<Integer>

The item that occurs most often.

Items occurring equally often keep the earlier one, by where each first stands. The empty List has no such item, and the defaultingTo: entry answers the given item in place of nothing.

mode() -> Optional<Integer>

The item that occurs most often.

Returns the item, or nothing for the empty List.

Example

constant rolls: List<Integer> = [2, 6, 6, 3]
constant empty: List<Integer> = []

expect rolls::mode()::is(6)
expect empty::mode()::isEmpty()

mode(defaultingTo fallback: Integer) -> Integer

The item that occurs most often, or the given fallback for the empty List.

NameTypeDescription

defaultingToIntegerthe item to answer with when there is none

Returns the item, or the fallback in its place.

Example

constant rolls: List<Integer> = [2, 6, 6, 3]
constant empty: List<Integer> = []

expect rolls::mode(defaultingTo 0)::is(6)
expect empty::mode(defaultingTo 0)::is(0)

on List<Rational>

The item that occurs most often.

Items occurring equally often keep the earlier one, by where each first stands. The empty List has no such item, and the defaultingTo: entry answers the given item in place of nothing.

mode() -> Optional<Rational>

The item that occurs most often.

Returns the item, or nothing for the empty List.

Example

constant weights: List<Rational> = [1/2, 1/3, 1/2]
constant empty: List<Rational>   = []

expect weights::mode()::is(1/2)
expect empty::mode()::isEmpty()

mode(defaultingTo fallback: Rational) -> Rational

The item that occurs most often, or the given fallback for the empty List.

NameTypeDescription

defaultingToRationalthe item to answer with when there is none

Returns the item, or the fallback in its place.

Example

constant weights: List<Rational> = [1/2, 1/3, 1/2]
constant empty: List<Rational>   = []

expect weights::mode(defaultingTo 0/1)::is(1/2)
expect empty::mode(defaultingTo 0/1)::is(0/1)

on List<Scalar>

The item that occurs most often.

Items occurring equally often keep the earlier one, by where each first stands. The empty List has no such item, and the defaultingTo: entry answers the given item in place of nothing.

mode() -> Optional<Scalar>

The item that occurs most often.

Returns the item, or nothing for the empty List.

Example

constant amounts: List<Scalar> = [1/2, 1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::mode()::is(1/2)
expect empty::mode()::isEmpty()

mode(defaultingTo fallback: Scalar) -> Scalar

The item that occurs most often, or the given fallback for the empty List.

NameTypeDescription

defaultingToScalarthe item to answer with when there is none

Returns the item, or the fallback in its place.

Example

constant amounts: List<Scalar> = [1/2, 1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::mode(defaultingTo 0)::is(1/2)
expect empty::mode(defaultingTo 0)::is(0)

on NonEmptyList<Integer>

mode() -> Integer

The item that occurs most often.

Items occurring equally often keep the earlier one, by where each first stands.

Returns the item that occurs most often.

Example

expect [2, 6, 6, 3]::mode()::is(6)
expect [3, 1, 1, 3]::mode()::is(3)

on NonEmptyList<Rational>

mode() -> Rational

The item that occurs most often.

Items occurring equally often keep the earlier one, by where each first stands.

Returns the item that occurs most often.

Example

expect [1/2, 1/3, 1/2]::mode()::is(1/2)
expect [1/3, 1/2]::mode()::is(1/3)

on NonEmptyList<Scalar>

mode() -> Scalar

The item that occurs most often.

Items occurring equally often keep the earlier one, by where each first stands.

Returns the item that occurs most often.

Example

expect [1/2, 1, 1/2]::mode()::is(1/2)
expect [1, 1/2]::mode()::is(1)

variance

on List<Integer>

The mean of the squared distances from the mean.

The count divides, so the answer is the variance of the items as a whole population. The empty List has no variance, and the defaultingTo: entry answers the given Rational in place of nothing.

variance() -> Optional<NonNegativeRational>

The variance of the items.

Returns the variance, which is never negative, or nothing for the empty List.

Example

constant scores: List<Integer> = [1, 5]
constant empty: List<Integer>  = []

expect scores::variance()::is(4/1)
expect empty::variance()::isEmpty()

variance(
	defaultingTo fallback: NonNegativeRational,
) -> NonNegativeRational

The variance of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToNonNegativeRationalthe variance to answer with when there is none

Returns the variance, or the fallback in its place.

Example

constant scores: List<Integer> = [1, 5]
constant empty: List<Integer>  = []

expect scores::variance(defaultingTo 0/1)::is(4/1)
expect empty::variance(defaultingTo 0/1)::is(0/1)

on List<Rational>

The mean of the squared distances from the mean.

The count divides, so the answer is the variance of the items as a whole population. The empty List has no variance, and the defaultingTo: entry answers the given Rational in place of nothing.

variance() -> Optional<NonNegativeRational>

The variance of the items.

Returns the variance, which is never negative, or nothing for the empty List.

Example

constant weights: List<Rational> = [1/2, 3/2]
constant empty: List<Rational>   = []

expect weights::variance()::is(1/4)
expect empty::variance()::isEmpty()

variance(
	defaultingTo fallback: NonNegativeRational,
) -> NonNegativeRational

The variance of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToNonNegativeRationalthe variance to answer with when there is none

Returns the variance, or the fallback in its place.

Example

constant weights: List<Rational> = [1/2, 3/2]
constant empty: List<Rational>   = []

expect weights::variance(defaultingTo 0/1)::is(1/4)
expect empty::variance(defaultingTo 0/1)::is(0/1)

on List<Scalar>

The mean of the squared distances from the mean.

The count divides, so the answer is the variance of the items as a whole population. The empty List has no variance, and the defaultingTo: entry answers the given Rational in place of nothing.

variance() -> Optional<NonNegativeRational>

The variance of the items.

Returns the variance, which is never negative, or nothing for the empty List.

Example

constant amounts: List<Scalar> = [1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::variance()::is(1/16)
expect empty::variance()::isEmpty()

variance(
	defaultingTo fallback: NonNegativeRational,
) -> NonNegativeRational

The variance of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToNonNegativeRationalthe variance to answer with when there is none

Returns the variance, or the fallback in its place.

Example

constant amounts: List<Scalar> = [1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::variance(defaultingTo 0/1)::is(1/16)
expect empty::variance(defaultingTo 0/1)::is(0/1)

on NonEmptyList<Integer>

variance() -> NonNegativeRational

The mean of the squared distances from the mean.

The count divides, so the answer is the variance of the items as a whole population.

Returns the variance, which is never negative.

Example

expect [1, 5]::variance()::is(4/1)

on NonEmptyList<Rational>

variance() -> NonNegativeRational

The mean of the squared distances from the mean.

The count divides, so the answer is the variance of the items as a whole population.

Returns the variance, which is never negative.

Example

expect [1/2, 3/2]::variance()::is(1/4)

on NonEmptyList<Scalar>

variance() -> NonNegativeRational

The mean of the squared distances from the mean.

The count divides, so the answer is the variance of the items as a whole population.

Returns the variance, which is never negative.

Example

expect [1, 1/2]::variance()::is(1/16)

standardDeviation

on List<Integer>

The square root of the variance.

A variance that is a ratio of two perfect squares answers a Rational, and every other variance answers an exact Algebraic. The empty List has none, and the defaultingTo: entry answers the given value in place of nothing.

standardDeviation() -> Optional<Rational | Algebraic>

The standard deviation of the items.

Returns the standard deviation, or nothing for the empty List.

Example

constant scores: List<Integer> = [1, 5]
constant empty: List<Integer>  = []

expect scores::standardDeviation()::is(2/1)
expect empty::standardDeviation()::isEmpty()

standardDeviation(
	defaultingTo fallback: Rational | Algebraic,
) -> Rational | Algebraic

The standard deviation of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToRational | Algebraicthe value to answer with when there is none

Returns the standard deviation, or the fallback in its place.

Example

constant scores: List<Integer> = [1, 5]
constant empty: List<Integer>  = []

expect scores::standardDeviation(defaultingTo 0/1)::is(2/1)
expect empty::standardDeviation(defaultingTo 0/1)::is(0/1)

on List<Rational>

The square root of the variance.

standardDeviation() -> Optional<Rational | Algebraic>

The standard deviation of the items.

Returns the standard deviation, or nothing for the empty List.

Example

constant weights: List<Rational> = [1/2, 3/2]
constant empty: List<Rational>   = []

expect weights::standardDeviation()::is(1/2)
expect empty::standardDeviation()::isEmpty()

standardDeviation(
	defaultingTo fallback: Rational | Algebraic,
) -> Rational | Algebraic

The standard deviation of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToRational | Algebraicthe value to answer with when there is none

Returns the standard deviation, or the fallback in its place.

Example

constant weights: List<Rational> = [1/2, 3/2]
constant empty: List<Rational>   = []

expect weights::standardDeviation(defaultingTo 0/1)::is(1/2)
expect empty::standardDeviation(defaultingTo 0/1)::is(0/1)

on List<Scalar>

The square root of the variance.

standardDeviation() -> Optional<Rational | Algebraic>

The standard deviation of the items.

Returns the standard deviation, or nothing for the empty List.

Example

constant amounts: List<Scalar> = [1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::standardDeviation()::is(1/4)
expect empty::standardDeviation()::isEmpty()

standardDeviation(
	defaultingTo fallback: Rational | Algebraic,
) -> Rational | Algebraic

The standard deviation of the items, or the given fallback for the empty List.

NameTypeDescription

defaultingToRational | Algebraicthe value to answer with when there is none

Returns the standard deviation, or the fallback in its place.

Example

constant amounts: List<Scalar> = [1, 1/2]
constant empty: List<Scalar>   = []

expect amounts::standardDeviation(defaultingTo 0/1)::is(1/4)
expect empty::standardDeviation(defaultingTo 0/1)::is(0/1)

on NonEmptyList<Integer>

standardDeviation() -> Rational | Algebraic

The square root of the variance.

A variance that is a ratio of two perfect squares answers a Rational, and every other variance answers an exact Algebraic.

Returns the standard deviation.

Example

expect [1, 5]::standardDeviation()::is(2/1)
expect [0, 2, 2, 4]::standardDeviation()::is(2::squareRoot())

on NonEmptyList<Rational>

standardDeviation() -> Rational | Algebraic

The square root of the variance.

A variance that is a ratio of two perfect squares answers a Rational, and every other variance answers an exact Algebraic.

Returns the standard deviation.

Example

expect [1/2, 3/2]::standardDeviation()::is(1/2)

on NonEmptyList<Scalar>

standardDeviation() -> Rational | Algebraic

The square root of the variance.

A variance that is a ratio of two perfect squares answers a Rational, and every other variance answers an exact Algebraic.

Returns the standard deviation.

Example

expect [1, 1/2]::standardDeviation()::is(1/4)

Each type below is a checked refinement: a type with a condition. A value has the type only once the compiler knows the condition holds, and Checked refinements shows how it finds out. Under each one, Tighter here lists the methods above that return a more precise type when called on it. Returned by lists the methods that return it.

NonEmptyList

type NonEmptyList<ItemType> = List<ItemType> where @::hasItems()

A List proven to have an item in it, as a checked refinement of List.

The proof is what lets firstItem and lastItem answer an item rather than an Optional. A List written down with items in it carries the proof. A List a Program is handed earns it through an if asking hasItems.

append(_:), prepend(_:) and insert(_:at:) each put something into what they were given, so each answers with this Type. The of(integersFrom:downTo:) entry answers it too, because a count down always answers its first value.

Tighter here length, firstItem, lastItem, indices, enumerate, lowestItem, highestItem, prepend, append, replace, removeDuplicates, map, reduce, reverse, sort, split, pair, flatten, group, tally, index, average, lowestNumber, highestNumber, median, percentile, mode, variance, standardDeviation

Returned by NonEmptyDictionary::keys(), NonEmptyDictionary::values(), NonEmptyDictionary::entries(), GroupedList::group(on:), GroupedNonEmptyList::group(on:), List.repeat(_:times:), List.of(integersFrom:downTo:), List.of(integersFrom:downTo:by:), List::prepend(_:), List::append(_:), List::insert(_:at:), List::split(intoGroupsOf:), List::split(on:), List::split(where:), List::accumulate(startingWith:_:), List::windows(of:), List::runs(where:), ResultList::allValues(), NonEmptyList::indices(), NonEmptyList::enumerate(), NonEmptyList::prepend(contentsOf:), NonEmptyList::append(contentsOf:), NonEmptyList::map(_:), NonEmptyList::reverse(), NonEmptyList::sort(in:), NonEmptyList::sort(by:), NonEmptyList::sort(on:in:), NonEmptyList::replace(_:at:), NonEmptyList::replace(at:_:), NonEmptyList::pair(with:), NonEmptyList::split(intoGroupsOf:), NonEmptyList::removeDuplicates(), NonEmptyList::removeDuplicates(on:), NonEmptyNestedList::flatten(), IntegerList::runningTotal(), RationalList::runningTotal(), NumberList::runningTotal(), Randomness::pick(_:from:), Randomness::shuffle(_:), String::lines(), String::split(on:), String::split(on:atMost:), NonEmptyString::characters()

Modes

Each mode below is a choice whose cases carry no payload. You pass one to a method to choose how the method works. Every mode has is, isNot and toString, and cases() on its name lists its cases, as in SortOrder.cases(). None of them is written out for a mode: Protocols says where each one comes from.

SortOrder

choice SortOrder {
	Ascending,
	Descending,
}

Which way sort runs: #Ascending from the lowest, or #Descending from the highest.

#Ascending is what a call that names no order gets. Descending is not a sort followed by a reverse. The comparison is turned around instead, so items the order does not tell apart keep the order they had.

Cases #Ascending, #Descending

Taken by

Dictionary::sort(in:), default #Ascending
Dictionary::sort(on:in:), default #Ascending
NonEmptyDictionary::sort(in:), default #Ascending
NonEmptyDictionary::sort(on:in:), default #Ascending
List::isSorted(in:), default #Ascending
List::sort(in:), default #Ascending
List::sort(on:in:), default #Ascending
NonEmptyList::sort(in:), default #Ascending
NonEmptyList::sort(on:in:), default #Ascending