aiken/collection/pairs
A module for working with associative lists (a.k.a Pairs).
While any function that works on List also work on Pairs, this module provides some extra helpers
that are specifically tailored to working with associative lists. Fundamentally, a Pairs<k, v> is
a type-alias to List<Pair<k, v>>.
Unlike dictionnaries (a.k.a.
Dict, associative lists make no assumption about the ordering of elements within the list. As a result, lookup functions do traverse the entire list when invoked. They are also not sets, and thus allow for duplicate keys. This is reflected in the functions used to interact with them.
Functions
Inspecting
Get all values in the alist associated with a given key.
pairs.get_all([], "a") == []
pairs.get_all([Pair("a", 1)], "a") == [1]
pairs.get_all([Pair("a", 1), Pair("b", 2)], "a") == [1]
pairs.get_all([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == [1, 3]
Get the value in the alist by its key.
If multiple values with the same key exist, only the first one is returned.
pairs.get_first([], "a") == None
pairs.get_first([Pair("a", 1)], "a") == Some(1)
pairs.get_first([Pair("a", 1), Pair("b", 2)], "a") == Some(1)
pairs.get_first([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == Some(1)
Get the value in the alist by its key.
If multiple values with the same key exist, only the last one is returned.
pairs.get_last([], "a") == None
pairs.get_last([Pair("a", 1)], "a") == Some(1)
pairs.get_last([Pair("a", 1), Pair("b", 2)], "a") == Some(1)
pairs.get_last([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == Some(3)
Finds all keys in the alist associated with a given value.
pairs.find_all([], 1) == []
pairs.find_all([Pair("a", 1)], 1) == ["a"]
pairs.find_all([Pair("a", 1), Pair("b", 2)], 1) == ["a"]
pairs.find_all([Pair("a", 1), Pair("b", 2), Pair("c", 1)], 1) == ["a", "c"]
Finds the first key in the alist associated with a given value, if any.
pairs.find_first([], 1) == None
pairs.find_first([Pair("a", 1)], 1) == Some("a")
pairs.find_first([Pair("a", 1), Pair("b", 2)], 1) == Some("a")
pairs.find_first([Pair("a", 1), Pair("b", 2), Pair("c", 1)], 1) == Some("a")
Finds the last key in the alist associated with a given value, if any.
pairs.find_last([], 1) == None
pairs.find_last([Pair("a", 1)], 1) == Some("a")
pairs.find_last([Pair("a", 1), Pair("b", 2)], 1) == Some("a")
pairs.find_last([Pair("a", 1), Pair("b", 2), Pair("c", 1)], 1) == Some("c")
Check if a key exists in the pairs.
pairs.has_key([], "a") == False
pairs.has_key([Pair("a", 1)], "a") == True
pairs.has_key([Pair("a", 1), Pair("b", 2)], "a") == True
pairs.has_key([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == True
Extract all the keys present in a given Pairs.
pairs.keys([]) == []
pairs.keys([Pair("a", 1)]) == ["a"]
pairs.keys([Pair("a", 1), Pair("b", 2)]) == ["a", "b"]
pairs.keys([Pair("a", 1), Pair("b", 2), Pair("a", 3)]) == ["a", "b", "a"]
Extract all the values present in a given Pairs.
pairs.values([]) == []
pairs.values([Pair("a", 1)]) == [1]
pairs.values([Pair("a", 1), Pair("b", 2)]) == [1, 2]
pairs.values([Pair("a", 1), Pair("b", 2), Pair("a", 3)]) == [1, 2, 3]
Modifying
Remove all key-value pairs matching the key from the Pairs. If the key is not found, no changes are made.
pairs.delete_all([], "a") == []
pairs.delete_all([Pair("a", 1)], "a") == []
pairs.delete_all([Pair("a", 1), Pair("b", 2)], "a") == [Pair("b", 2)]
pairs.delete_all([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == [Pair("b", 2)]
Remove a single key-value pair from the Pairs. If the key is not found, no changes are made.
Duplicate keys are not deleted. Only the first key found is deleted.
pairs.delete_first([], "a") == []
pairs.delete_first([Pair("a", 1)], "a") == []
pairs.delete_first([Pair("a", 1), Pair("b", 2)], "a") == [Pair("b", 2)]
pairs.delete_first([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == [Pair("b", 2), Pair("a", 3)]
Remove a single key-value pair from the Pairs. If the key is not found, no changes are made.
Duplicate keys are not deleted. Only the last key found is deleted.
pairs.delete_last([], "a") == []
pairs.delete_last([Pair("a", 1)], "a") == []
pairs.delete_last([Pair("a", 1), Pair("b", 2)], "a") == [Pair("b", 2)]
pairs.delete_last([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == [Pair("a", 1), Pair("b", 2)]
insert_by_ascending_key(
self: Pairs<key, value>,
key: key,
value: value,
compare: fn(key, key) -> Ordering,
) -> Pairs<key, value>
Insert a value in the Pairs at a given key. If the key already exists,
the value is added in front.
The list is only traversed up to the given key and the traversal
stops as soon as a higher key is encountered. Said differently, the list
is assumed to be ordered by ascending keys! If it is not, expect the
unexpected.
use aiken/primitive/bytearray
let result =
[]
|> pairs.insert_by_ascending_key(key: "foo", value: 1, compare: bytearray.compare)
|> pairs.insert_by_ascending_key(key: "bar", value: 2, compare: bytearray.compare)
|> pairs.insert_by_ascending_key(key: "foo", value: 3, compare: bytearray.compare)
result == [Pair("bar", 2), Pair("foo", 3), Pair("foo", 1)]
insert_with_by_ascending_key(
self: Pairs<key, value>,
key: key,
value: value,
compare: fn(key, key) -> Ordering,
with: fn(value, value) -> value,
) -> Pairs<key, value>
Like insert_by_ascending_key but specifies
how to combine two values on a key conflict.
The list is only traversed up to the given key and the traversal
stops as soon as a higher key is encountered. Said differently, the list
is assumed to be ordered by ascending keys! If it is not, expect the
unexpected.
use aiken/primitive/bytearray
let add_integer = fn(x, y) { x + y }
let result =
[]
|> pairs.insert_with_by_ascending_key(key: "foo", value: 1, compare: bytearray.compare, with: add_integer)
|> pairs.insert_with_by_ascending_key(key: "bar", value: 2, compare: bytearray.compare, with: add_integer)
|> pairs.insert_with_by_ascending_key(key: "foo", value: 3, compare: bytearray.compare, with: add_integer)
result == [Pair("bar", 2), Pair("foo", 4)]
Apply a function to all key-value pairs in a alist, replacing the values.
let fixture = [Pair("a", 100), Pair("b", 200)]
pairs.map(fixture, fn(_k, v) { v * 2 }) == [Pair("a", 200), Pair("b", 400)]
repsert_by_ascending_key(
self: Pairs<key, value>,
key: key,
value: value,
compare: fn(key, key) -> Ordering,
) -> Pairs<key, value>
Insert a value in the Pairs at a given key. If the key already exists,
its value is replaced.
The list is only traversed up to the given key and the traversal
stops as soon as a higher key is encountered. Said differently, the list
is assumed to be ordered by ascending keys! If it is not, expect the
unexpected.
use aiken/primitive/bytearray
let result =
[]
|> pairs.repsert_by_ascending_key(key: "foo", value: 1, compare: bytearray.compare)
|> pairs.repsert_by_ascending_key(key: "bar", value: 2, compare: bytearray.compare)
|> pairs.repsert_by_ascending_key(key: "foo", value: 3, compare: bytearray.compare)
result == [Pair("bar", 2), Pair("foo", 3)]
Transforming
Fold over the key-value pairs in a pairs. The fold direction follows keys
in ascending order and is done from left-to-right.
let fixture = [
Pair(1, 100),
Pair(2, 200),
Pair(3, 300),
]
pairs.foldl(fixture, 0, fn(k, v, result) { k * v + result }) == 1400
Fold over the key-value pairs in a Pairs. The fold direction follows the
order of elements in the Pairs and is done from right-to-left.
let fixture = [
Pair(1, 100),
Pair(2, 200),
Pair(3, 300),
]
pairs.foldr(fixture, 0, fn(k, v, result) { k * v + result }) == 1400
Get all values in the alist associated with a given key.
pairs.get_all([], "a") == []
pairs.get_all([Pair("a", 1)], "a") == [1]
pairs.get_all([Pair("a", 1), Pair("b", 2)], "a") == [1]
pairs.get_all([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == [1, 3]
Get the value in the alist by its key. If multiple values with the same key exist, only the first one is returned.
pairs.get_first([], "a") == None
pairs.get_first([Pair("a", 1)], "a") == Some(1)
pairs.get_first([Pair("a", 1), Pair("b", 2)], "a") == Some(1)
pairs.get_first([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == Some(1)
Get the value in the alist by its key. If multiple values with the same key exist, only the last one is returned.
pairs.get_last([], "a") == None
pairs.get_last([Pair("a", 1)], "a") == Some(1)
pairs.get_last([Pair("a", 1), Pair("b", 2)], "a") == Some(1)
pairs.get_last([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == Some(3)
Finds all keys in the alist associated with a given value.
pairs.find_all([], 1) == []
pairs.find_all([Pair("a", 1)], 1) == ["a"]
pairs.find_all([Pair("a", 1), Pair("b", 2)], 1) == ["a"]
pairs.find_all([Pair("a", 1), Pair("b", 2), Pair("c", 1)], 1) == ["a", "c"]
Finds the first key in the alist associated with a given value, if any.
pairs.find_first([], 1) == None
pairs.find_first([Pair("a", 1)], 1) == Some("a")
pairs.find_first([Pair("a", 1), Pair("b", 2)], 1) == Some("a")
pairs.find_first([Pair("a", 1), Pair("b", 2), Pair("c", 1)], 1) == Some("a")
Finds the last key in the alist associated with a given value, if any.
pairs.find_last([], 1) == None
pairs.find_last([Pair("a", 1)], 1) == Some("a")
pairs.find_last([Pair("a", 1), Pair("b", 2)], 1) == Some("a")
pairs.find_last([Pair("a", 1), Pair("b", 2), Pair("c", 1)], 1) == Some("c")
Check if a key exists in the pairs.
pairs.has_key([], "a") == False
pairs.has_key([Pair("a", 1)], "a") == True
pairs.has_key([Pair("a", 1), Pair("b", 2)], "a") == True
pairs.has_key([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == True
Extract all the keys present in a given Pairs.
pairs.keys([]) == []
pairs.keys([Pair("a", 1)]) == ["a"]
pairs.keys([Pair("a", 1), Pair("b", 2)]) == ["a", "b"]
pairs.keys([Pair("a", 1), Pair("b", 2), Pair("a", 3)]) == ["a", "b", "a"]
Extract all the values present in a given Pairs.
pairs.values([]) == []
pairs.values([Pair("a", 1)]) == [1]
pairs.values([Pair("a", 1), Pair("b", 2)]) == [1, 2]
pairs.values([Pair("a", 1), Pair("b", 2), Pair("a", 3)]) == [1, 2, 3]
Remove all key-value pairs matching the key from the Pairs. If the key is not found, no changes are made.
pairs.delete_all([], "a") == []
pairs.delete_all([Pair("a", 1)], "a") == []
pairs.delete_all([Pair("a", 1), Pair("b", 2)], "a") == [Pair("b", 2)]
pairs.delete_all([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == [Pair("b", 2)]
Remove a single key-value pair from the Pairs. If the key is not found, no changes are made.
Duplicate keys are not deleted. Only the first key found is deleted.
pairs.delete_first([], "a") == []
pairs.delete_first([Pair("a", 1)], "a") == []
pairs.delete_first([Pair("a", 1), Pair("b", 2)], "a") == [Pair("b", 2)]
pairs.delete_first([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == [Pair("b", 2), Pair("a", 3)]
Remove a single key-value pair from the Pairs. If the key is not found, no changes are made. Duplicate keys are not deleted. Only the last key found is deleted.
pairs.delete_last([], "a") == []
pairs.delete_last([Pair("a", 1)], "a") == []
pairs.delete_last([Pair("a", 1), Pair("b", 2)], "a") == [Pair("b", 2)]
pairs.delete_last([Pair("a", 1), Pair("b", 2), Pair("a", 3)], "a") == [Pair("a", 1), Pair("b", 2)]
insert_by_ascending_key(
self: Pairs<key, value>,
key: key,
value: value,
compare: fn(key, key) -> Ordering,
) -> Pairs<key, value>
Insert a value in the Pairs at a given key. If the key already exists,
the value is added in front.
The list is only traversed up to the given key and the traversal stops as soon as a higher key is encountered. Said differently, the list is assumed to be ordered by ascending keys! If it is not, expect the unexpected.
use aiken/primitive/bytearray
let result =
[]
|> pairs.insert_by_ascending_key(key: "foo", value: 1, compare: bytearray.compare)
|> pairs.insert_by_ascending_key(key: "bar", value: 2, compare: bytearray.compare)
|> pairs.insert_by_ascending_key(key: "foo", value: 3, compare: bytearray.compare)
result == [Pair("bar", 2), Pair("foo", 3), Pair("foo", 1)]
insert_with_by_ascending_key(
self: Pairs<key, value>,
key: key,
value: value,
compare: fn(key, key) -> Ordering,
with: fn(value, value) -> value,
) -> Pairs<key, value>
Like insert_by_ascending_key but specifies
how to combine two values on a key conflict.
The list is only traversed up to the given key and the traversal stops as soon as a higher key is encountered. Said differently, the list is assumed to be ordered by ascending keys! If it is not, expect the unexpected.
use aiken/primitive/bytearray
let add_integer = fn(x, y) { x + y }
let result =
[]
|> pairs.insert_with_by_ascending_key(key: "foo", value: 1, compare: bytearray.compare, with: add_integer)
|> pairs.insert_with_by_ascending_key(key: "bar", value: 2, compare: bytearray.compare, with: add_integer)
|> pairs.insert_with_by_ascending_key(key: "foo", value: 3, compare: bytearray.compare, with: add_integer)
result == [Pair("bar", 2), Pair("foo", 4)]
Apply a function to all key-value pairs in a alist, replacing the values.
let fixture = [Pair("a", 100), Pair("b", 200)]
pairs.map(fixture, fn(_k, v) { v * 2 }) == [Pair("a", 200), Pair("b", 400)]
repsert_by_ascending_key(
self: Pairs<key, value>,
key: key,
value: value,
compare: fn(key, key) -> Ordering,
) -> Pairs<key, value>
Insert a value in the Pairs at a given key. If the key already exists,
its value is replaced.
The list is only traversed up to the given key and the traversal stops as soon as a higher key is encountered. Said differently, the list is assumed to be ordered by ascending keys! If it is not, expect the unexpected.
use aiken/primitive/bytearray
let result =
[]
|> pairs.repsert_by_ascending_key(key: "foo", value: 1, compare: bytearray.compare)
|> pairs.repsert_by_ascending_key(key: "bar", value: 2, compare: bytearray.compare)
|> pairs.repsert_by_ascending_key(key: "foo", value: 3, compare: bytearray.compare)
result == [Pair("bar", 2), Pair("foo", 3)]
Transforming
Fold over the key-value pairs in a pairs. The fold direction follows keys
in ascending order and is done from left-to-right.
let fixture = [
Pair(1, 100),
Pair(2, 200),
Pair(3, 300),
]
pairs.foldl(fixture, 0, fn(k, v, result) { k * v + result }) == 1400
Fold over the key-value pairs in a Pairs. The fold direction follows the
order of elements in the Pairs and is done from right-to-left.
let fixture = [
Pair(1, 100),
Pair(2, 200),
Pair(3, 300),
]
pairs.foldr(fixture, 0, fn(k, v, result) { k * v + result }) == 1400
Fold over the key-value pairs in a pairs. The fold direction follows keys in ascending order and is done from left-to-right.
let fixture = [
Pair(1, 100),
Pair(2, 200),
Pair(3, 300),
]
pairs.foldl(fixture, 0, fn(k, v, result) { k * v + result }) == 1400
Fold over the key-value pairs in a Pairs. The fold direction follows the order of elements in the Pairs and is done from right-to-left.
let fixture = [
Pair(1, 100),
Pair(2, 200),
Pair(3, 300),
]
pairs.foldr(fixture, 0, fn(k, v, result) { k * v + result }) == 1400