Dictionary

static of<KeyType is Equatable>(
	_ entries: List<{ key: KeyType, value: ValueType }>,
) -> Dictionary<KeyType, ValueType>

Answers a Dictionary built from a List of entries.

Two entries with equal keys collapse into one. The later value wins, and the key keeps the place of its first occurrence. Equality is the keys' own is.

Returns the Dictionary of those entries.

constant stock = Dictionary.of([
	{ key = "tea", value = 2 },
	{ key = "jam", value = 1 },
	{ key = "tea", value = 5 },
])

expect stock::is(["tea" = 5, "jam" = 1])
expect stock::keys()::is(["tea", "jam"])

static of<KeyType is Equatable>(
	_ keys: List<KeyType>,
	valuedBy valueOf: (_: KeyType) -> ValueType,
) -> Dictionary<KeyType, ValueType>

Answers a Dictionary of the given keys, each holding what the Function answers for it.

The Function is asked once for each key, in the order the keys stand in. A key written down twice keeps the place of its first occurrence and holds what the Function answered the second time. The empty List answers the empty Dictionary.

Returns the Dictionary of those keys.

constant lengths = Dictionary.of(["Ada", "Grace"], valuedBy (name) {
	<- name::length()
})

expect lengths::is(["Ada" = 3, "Grace" = 5])

is<KeyType is Equatable, ValueType is Equatable>(
	_ other: Dictionary<KeyType, ValueType>,
) -> Boolean

Answers whether the two Dictionaries hold the same keys with equal values.

The order the entries stand in does not matter. Each key is found by the keys' own is, and each pair of values is compared by the values' own is. The Method is available whenever the keys and the values conform to Equatable.

Returns true when the two hold the same entries.

expect ["tea" = 2, "jam" = 1]::is(["jam" = 1, "tea" = 2])
expect ["tea" = 2]::is(["tea" = 3])::negate()

toString<KeyType is Printable, ValueType is Printable>() -> String

Answers the Dictionary and its entries as a String, in the form ["a" = 1, "b" = 2].

Each key and each value is rendered by its own toString, and a String is quoted: ["a" = "b"]. The empty Dictionary answers [=]. The empty List answers [], so the two are never the same text. The Method is available whenever the keys and the values conform to Printable.

Returns the String representation of the Dictionary.

constant stock = ["tea" = 2, "jam" = 1]
constant empty: Dictionary<String, Integer> = [=]

expect stock::toString()::is("[\"tea\" = 2, \"jam\" = 1]")
expect empty::toString()::is("[=]")

isNot(_ other: Dictionary<KeyType, ValueType>) -> Boolean

Answers whether the values differ.

Returns true when the values differ.

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

isEmpty() -> Boolean

Answers whether the Dictionary has no entries at all.

Returns true for the empty Dictionary.

constant empty: Dictionary<String, Integer> = [=]

expect empty::isEmpty()
expect ["tea" = 2]::isEmpty()::negate()

hasEntries() -> Boolean

Answers whether the Dictionary has at least one entry.

It is the opposite of isEmpty.

Returns true when the Dictionary is not empty.

constant empty: Dictionary<String, Integer> = [=]

expect ["tea" = 2]::hasEntries()
expect empty::hasEntries()::negate()

hasEntries(
	where check: (_: { key: KeyType, value: ValueType }) -> Boolean,
) -> Boolean

Answers whether the check accepts at least one entry.

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

Returns true when the check accepts an entry.

constant stock = ["tea" = 2, "jam" = 0]
constant empty: Dictionary<String, Integer> = [=]

expect stock::hasEntries(where ({ value }) { <- value::is(0) })
expect empty::hasEntries(where (_) { <- true })::negate()

hasKey<KeyType is Equatable>(_ key: KeyType) -> Boolean

Answers whether the Dictionary holds a value for the given key.

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

Returns true when the key holds a value.

expect ["tea" = 2]::hasKey("tea")
expect ["tea" = 2]::hasKey("jam")::negate()

hasValue<ValueType is Equatable>(_ value: ValueType) -> Boolean

Answers whether an entry of the Dictionary holds the given value.

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

Returns true when an entry holds the value.

expect ["tea" = 2]::hasValue(2)
expect ["tea" = 2]::hasValue(5)::negate()

hasOnlyEntries(
	where check: (_: { key: KeyType, value: ValueType }) -> Boolean,
) -> Boolean

Answers whether the check accepts every entry.

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

Returns true when the check accepts every entry.

constant stock = ["tea" = 2, "jam" = 5]
constant empty: Dictionary<String, Integer> = [=]

expect stock::hasOnlyEntries(where ({ value }) { <- value::isNot(0) })
expect empty::hasOnlyEntries(where (_) { <- false })

hasNoEntries(
	where check: (_: { key: KeyType, value: ValueType }) -> Boolean,
) -> Boolean

Answers whether the check accepts no entry at all.

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

Returns true when the check accepts no entry.

constant stock = ["tea" = 2, "jam" = 5]
constant empty: Dictionary<String, Integer> = [=]

expect stock::hasNoEntries(where ({ value }) { <- value::is(0) })
expect empty::hasNoEntries(where (_) { <- true })

length() -> NonNegativeInteger

Answers how many entries the Dictionary has.

Returns the number of entries, which is never negative.

constant stock = ["tea" = 2, "jam" = 1]
constant empty: Dictionary<String, Integer> = [=]

expect stock::length()::is(2)
expect empty::length()::is(0)

length() -> PositiveInteger

Answers how many entries the Dictionary has, which is at least one.

Returns the number of entries, which is above zero.

constant size: PositiveInteger = ["tea" = 2, "jam" = 1]::length()

expect size::is(2)

value<KeyType is Equatable>(at key: KeyType) -> Optional<ValueType>

Answers the value the given key holds.

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

Returns the value in an Optional, or an empty Optional when the key holds no value.

constant stock = ["tea" = 2, "jam" = 1]

expect stock::value(at "tea")::is(2)
expect stock::value(at "milk")::isEmpty()

value<KeyType is Equatable>(
	at key: KeyType,
	defaultingTo fallback: ValueType,
) -> ValueType

Answers the value the given key holds, or the given fallback when the key holds no value.

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

Returns the value, or the fallback in its place.

constant stock = ["tea" = 2, "jam" = 1]

expect stock::value(at "tea", defaultingTo 0)::is(2)
expect stock::value(at "milk", defaultingTo 0)::is(0)

keys() -> List<KeyType>

Answers the keys, in the order they were first set.

Returns the List of keys.

constant stock = ["tea" = 2, "jam" = 1]

expect stock::keys()::is(["tea", "jam"])

keys() -> NonEmptyList<KeyType>

Answers the keys, in the order they were first set.

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

constant first: String = ["tea" = 2, "jam" = 1]::keys()::firstItem()

expect first::is("tea")

values() -> List<ValueType>

Answers the values, in the order their keys were first set.

Returns the List of values.

constant stock = ["tea" = 2, "jam" = 1]

expect stock::values()::is([2, 1])

values() -> NonEmptyList<ValueType>

Answers the values, in the order their keys were first set.

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

constant first: Integer = ["tea" = 2, "jam" = 1]::values()::firstItem()

expect first::is(2)

entries() -> List<{ key: KeyType, value: ValueType }>

Answers the entries, in the order their keys were first set.

Each entry is a Record of a key and a value, which a Pattern can take apart.

Returns the List of entries.

constant stock = ["tea" = 2]

expect stock::entries()::is([{ key = "tea", value = 2 }])

entries() -> NonEmptyList<{ key: KeyType, value: ValueType }>

Answers the entries, in the order their keys were first set.

Each entry is a Record of a key and a value, which a Pattern can take apart.

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

constant { key, value } = ["tea" = 2, "jam" = 1]::entries()::firstItem()

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

firstEntry() -> Optional<{ key: KeyType, value: ValueType }>

Answers the first entry of the Dictionary.

The entry is a Record of a key and a value, which a Pattern can take apart.

Returns the entry in an Optional, or an empty Optional for the empty Dictionary.

constant stock = ["tea" = 2, "jam" = 1]
constant empty: Dictionary<String, Integer> = [=]

expect stock::firstEntry()::is({ key = "tea", value = 2 })
expect empty::firstEntry()::isEmpty()

firstEntry(
	defaultingTo fallback: { key: KeyType, value: ValueType },
) -> { key: KeyType, value: ValueType }

Answers the first entry of the Dictionary, or the given entry where it has none.

Returns the entry, or the given one in its place.

constant stock = ["tea" = 2, "jam" = 1]
constant empty: Dictionary<String, Integer> = [=]
constant fallback = { key = "none", value = 0 }

expect stock::firstEntry(defaultingTo fallback).key::is("tea")
expect empty::firstEntry(defaultingTo fallback)::is(fallback)

firstEntry() -> { key: KeyType, value: ValueType }

Answers the first entry, in the order the keys were first set.

The entry is a Record of a key and a value, which a Pattern can take apart.

Returns the entry, which certainly is there.

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

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

set<KeyType is Equatable>(
	_ key: KeyType,
	to value: ValueType,
) -> NonEmptyDictionary<KeyType, ValueType>

Answers a new Dictionary with the given key holding the given value.

A key that is already there keeps its place and takes the new value. A key that is not there is added at the end. Equality is the keys' own is. The answer holds the entry that was set, so it is never empty.

Returns the Dictionary with that entry, which certainly has an entry.

constant stock = ["tea" = 2, "jam" = 1]

expect stock::set("tea", to 5)::is(["tea" = 5, "jam" = 1])
expect stock::set("tea", to 5)::keys()::is(["tea", "jam"])
expect stock::set("milk", to 4)::keys()::is(["tea", "jam", "milk"])

update<KeyType is Equatable>(
	at key: KeyType,
	with transform: (_: ValueType) -> ValueType,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary with the given key's value transformed.

A key that holds no value answers the receiver unchanged, and the transform does not run.

Returns the Dictionary with the transformed value.

constant stock = ["tea" = 2, "jam" = 1]
constant addTen = (_ count: Integer) -> Integer { <- count::add(10) }

expect stock::update(at "tea", with addTen)::is(["tea" = 12, "jam" = 1])
expect stock::update(at "milk", with addTen)::is(stock)

update<KeyType is Equatable>(
	at key: KeyType,
	defaultingTo start: ValueType,
	with transform: (_: ValueType) -> ValueType,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary with the given key's value transformed, starting from the given value where the key holds no value.

A key that holds no value is set to the transform of the given value.

Returns the Dictionary with the transformed value.

constant stock = ["tea" = 2]
constant addOne = (_ count: Integer) -> Integer { <- count::add(1) }
constant more = stock::update(at "tea", defaultingTo 0, with addOne)
constant added = stock::update(at "jam", defaultingTo 0, with addOne)

expect more::is(["tea" = 3])
expect added::is(["tea" = 2, "jam" = 1])

remove<KeyType is Equatable>(
	at key: KeyType,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary without the given key.

A key that is not there answers the receiver unchanged. Equality is the keys' own is.

Returns the Dictionary without that entry.

constant stock = ["tea" = 2, "jam" = 1]

expect stock::remove(at "tea")::is(["jam" = 1])
expect stock::remove(at "milk")::is(stock)

remove<KeyType is Equatable>(
	atEvery keys: List<KeyType>,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary without any of the given keys.

A key that is not there changes nothing, and a key written down twice is removed once. The empty List answers the receiver unchanged. The entries that are left keep the order they had. Equality is the keys' own is.

Returns the Dictionary without those entries.

constant stock = ["tea" = 2, "jam" = 1]

expect stock::remove(atEvery ["tea", "milk"])::is(["jam" = 1])
expect stock::remove(atEvery [])::is(stock)

removeEvery(
	where check: (_: { key: KeyType, value: ValueType }) -> Boolean,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary without every entry the check accepts.

Each entry is offered to the check, and the entries it rejects keep their order. A check that accepts every entry answers the empty Dictionary.

Returns the Dictionary of the entries the check rejects.

constant stock = ["tea" = 2, "jam" = 0, "milk" = 4]
constant inStock = stock::removeEvery(where ({ value }) {
	<- value::is(0)
})

expect inStock::is(["tea" = 2, "milk" = 4])

everyEntry(
	where check: (_: { key: KeyType, value: ValueType }) -> Boolean,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary of every entry the check accepts.

Each entry is offered to the check, and the accepted entries keep their order. It is named as List::everyItem(where:) is.

Returns the Dictionary of accepted entries.

constant stock = ["tea" = 2, "jam" = 0, "milk" = 4]
constant soldOut = stock::everyEntry(where ({ value }) {
	<- value::is(0)
})

expect soldOut::is(["jam" = 0])

map<infer Other>(
	_ transform: (_: { key: KeyType, value: ValueType }) -> Other,
) -> Dictionary<KeyType, Other>

Answers a new Dictionary with the given transform applied to every entry.

The keys are kept, and what the transform answers becomes the value of the entry it was handed. The answer holds the same keys in the same order.

Returns the Dictionary of transformed values.

constant prices = ["tea" = 3, "jam" = 5]
constant doubled = prices::map(({ value }) {
	<- value::multiply(with 2)
})

expect doubled::is(["tea" = 6, "jam" = 10])

map<infer Other>(
	_ transform: (_: { key: KeyType, value: ValueType }) -> Other,
) -> NonEmptyDictionary<KeyType, Other>

Answers a new Dictionary with the given transform applied to every entry.

The keys are kept, and what the transform answers becomes the value of the entry it was handed. The answer holds the same keys in the same order.

Returns the Dictionary of transformed values, which certainly has an entry.

constant doubled = ["tea" = 3, "jam" = 5]::map(({ value }) {
	<- value::multiply(with 2)
})

expect doubled::is(["tea" = 6, "jam" = 10])

merge<KeyType is Equatable>(
	with other: Dictionary<KeyType, ValueType>,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary holding the entries of both, where the given Dictionary wins.

A key both hold takes the given Dictionary's value. A key only the given Dictionary holds is added at the end.

Returns the merged Dictionary.

constant shelf = ["tea" = 2, "jam" = 1]
constant delivery = ["tea" = 5, "milk" = 3]
constant merged = shelf::merge(with delivery)

expect merged::is(["tea" = 5, "jam" = 1, "milk" = 3])
expect merged::keys()::is(["tea", "jam", "milk"])

merge<KeyType is Equatable>(
	with other: Dictionary<KeyType, ValueType>,
	choosing choose: (_: ValueType, _: ValueType) -> ValueType,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary holding the entries of both, asking the given Function for the value of a key both hold.

The Function is handed the receiver's value and then the given Dictionary's value. A key only one of the two holds is taken as it stands.

Returns the merged Dictionary.

constant shelf = ["tea" = 2, "jam" = 1]
constant delivery = ["tea" = 5, "milk" = 3]
constant total = shelf::merge(with delivery, choosing (held, arrived) {
	<- held::add(arrived)
})

expect total::is(["tea" = 7, "jam" = 1, "milk" = 3])

sort<KeyType is Comparable>(
	in order: SortOrder = #Ascending,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary in the given direction, by the keys' own ordering.

The sort is stable. The entry is available whenever the keys conform to Comparable. The direction is #Ascending when a call names none.

Returns the ordered Dictionary.

constant stock = ["tea" = 2, "jam" = 1, "milk" = 4]

expect stock::sort()::keys()::is(["jam", "milk", "tea"])
expect stock::sort(in #Descending)::keys()::is(["tea", "milk", "jam"])

sort<infer Key is Comparable>(
	on key: (_: { key: KeyType, value: ValueType }) -> Key,
	in order: SortOrder = #Ascending,
) -> Dictionary<KeyType, ValueType>

Answers a new Dictionary in the given direction of what the key reads off each entry.

The key is read once per entry. The sort is stable, so entries 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.

Returns the ordered Dictionary.

constant stock = ["tea" = 2, "jam" = 1, "milk" = 2]
constant fullest = stock::sort(on .value, in #Descending)

expect stock::sort(on .value)::keys()::is(["jam", "tea", "milk"])
expect fullest::keys()::is(["tea", "milk", "jam"])

sort<KeyType is Comparable>(
	in order: SortOrder = #Ascending,
) -> NonEmptyDictionary<KeyType, ValueType>

Answers a new Dictionary in the given direction, by the keys' own ordering.

The sort is stable. The entry is available whenever the keys conform to Comparable. The direction is #Ascending when a call names none.

Returns the ordered Dictionary, which certainly has an entry.

expect ["tea" = 2, "jam" = 1]::sort()::firstEntry().key::is("jam")

sort<infer Key is Comparable>(
	on key: (_: { key: KeyType, value: ValueType }) -> Key,
	in order: SortOrder = #Ascending,
) -> NonEmptyDictionary<KeyType, ValueType>

Answers a new Dictionary in the given direction of what the key reads off each entry.

The key is read once per entry. The sort is stable, so entries 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.

Returns the ordered Dictionary, which certainly has an entry.

constant first = ["tea" = 2, "jam" = 1]::sort(on .value)::firstEntry()

expect first.key::is("jam")

count(
	where check: (_: { key: KeyType, value: ValueType }) -> Boolean,
) -> NonNegativeInteger

Answers how many entries the check accepts.

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

constant stock = ["tea" = 2, "jam" = 0, "milk" = 0]

expect stock::count(where ({ value }) { <- value::is(0) })::is(2)