6.32. kink/container/MAP¶
6.32.1. type map¶
`map` is an abstract type of key-value containers.
Keys must be unique in a `map`, in an equivalence relation among keys.
Equivalence relation of keys
The equivalence relation of keys, `equivalent-to`, must suffice the following conditions for all X, Y, and Z in the domain of keys.
• reflexive: X equivalent-to X
• symmetric: (if X equivalent-to Y then Y equivalent-to X) and (if not (X equivalent-to Y) then not (Y equivalent-to X))
• transitive: if X equivalent-to Y and Y equivalent-to Z then X equivalent-to Z
6.32.1.1. Map.eq¶
`eq` returns the function of the equivalence relation of keys of `Map`.
The result function, $equivalent_to?, is a function which takes two args `X` and `Y`. `equivalent_to?(X Y)` returns the bool value of `X equivalent-to Y`, where `equivalent-to` is the equivalence relation of keys of `Map`.
6.32.1.2. Map.get(Key ...[$if_absent])¶
`get` returns the value associated with a key equivalent to `Key`.
If `Map` does not have such a key, `get` tail-calls $if_absent. The default value of $if_absent is a fun which raises an exception.
Preconditions
`Key` must be in the domain of the equivalence relation of keys.
$if_absent must be a thunk.
Example
:FLAT_MAP.require_from('kink/container/')
:Map <- FLAT_MAP.of('one' 1 'two' 2 'three' 3 'four' 4)
stdout.print_line(Map.get('one').repr) # => 1
stdout.print_line(Map.get('five'){ 'big' }.repr) # => "big"
Map.get('five')
# Output:
# ...
# -- main exception
# ,,,
# {builtin:kink-mods/kink/container/FLAT_MAP.kn L138 C9 raise} { -->raise('{}: no such key: {}'.format(Desc Key.repr)) }
# Flat_map.get(Key ...[$if_absent]): no such key: "five"
6.32.1.3. Map.get_opt(Key)¶
If `Map` has a key equivalent to `Key`, `get_opt` returns [Val] where `Val` is the value associated with the key.
If `Map` does not have such a key, `get_opt` returns [].
Precondition
`Key` must be in the domain of the equivalence relation of keys.
Example
:FLAT_MAP.require_from('kink/container/')
:Map <- FLAT_MAP.of('one' 1 'two' 2 'three' 3 'four' 4)
stdout.print_line(Map.get_opt('one').repr) # => [1]
stdout.print_line(Map.get_opt('five').repr) # => []
6.32.1.4. Map.have_key?(Key)¶
`have_key?` returns whether `Map` has a key equivalent to `Key`.
Precondition
`Key` must be in the domain of the equivalence relation of keys.
Example
:FLAT_MAP.require_from('kink/container/')
:Map <- FLAT_MAP.of('one' 1 'two' 2 'three' 3 'four' 4)
stdout.print_line(Map.have_key?('one').repr) # => true
stdout.print_line(Map.have_key?('five').repr) # => false
6.32.1.5. Map.size¶
`size` returns the number of key-value pairs in `Map`, as an integer `num`.
6.32.1.6. Map.any?¶
`any?` returns whether `Map` contains one or more entries.
6.32.1.7. Map.set(Key Val)¶
`set` associates `Key` as the key, to `Val` as the value.
If `Map` does not have a key equivalent to `Key`, `set` makes a new association with `Key` and `Val`.
If `Map` already has a key equivalent to `Key`, `set` overwrites the association with `Val`. In that case, `set` might overwrite the association with `Key`, or might keep the old key.
Precondition
`Key` must be in the domain of the equivalence relation of keys.
Postconditions
Map.have_key?(Key) will be true.
Map.get(Key) will be `Val`.
Example
:FLAT_MAP.require_from('kink/container/')
:Map <- FLAT_MAP.of('one' 1 'two' 2 'three' 3)
Map.set('four' 4)
Map.set('one' 'ONE')
stdout.print_line(Map.repr) # => (flat_map "four"=>4 "one"=>"ONE" "three"=>3 "two"=>2)
6.32.1.8. Map.pop_at(Key)¶
`pop_at` removes the key-value pair whose key is equivalent to `Key`, and returns the associated value.
Precondition
`Key` must be in the domain of the equivalence relation of keys.
Postcondition
Map.have_key?(Key) will be false.
Example
:FLAT_MAP.require_from('kink/container/')
:Map <- FLAT_MAP.of('one' 1 'two' 2 'three' 3 'four' 4)
stdout.print_line(Map.pop_at('four').repr) # => 4
stdout.print_line(Map.repr) # => (flat_map "one"=>1 "three"=>3 "two"=>2)
6.32.1.9. Map.clear¶
`clear` removes all the key-value pairs from `Map`.
6.32.1.10. Map.key_iter¶
`key_iter` returns an `iter` of the keys.
Example
:FLAT_MAP.require_from('kink/container/')
:Map <- FLAT_MAP.of('one' 1 'two' 2 'three' 3 'four' 4)
Map.key_iter.each{(:K)
stdout.print_line(K.repr)
}
# Output:
# "four"
# "one"
# "three"
# "two"
6.32.1.11. Map.pair_iter¶
`pair_iter` returns an `iter` of a `vec` [Key Value] for all the key-value pairs.
Example
:FLAT_MAP.require_from('kink/container/')
:Map <- FLAT_MAP.of('one' 1 'two' 2 'three' 3 'four' 4)
Map.pair_iter.each{([:K :V])
stdout.print_line('{} => {}'.format(K.repr V.repr))
}
# Output:
# "four" => 4
# "one" => 1
# "three" => 3
# "two" => 2
6.32.1.12. X == Y¶
`==` operator, or `op_eq` method, returns whether two maps `X` and Y` are equivalent.
The two maps are equivalent when the following conditions are met:
• `X` and `Y` has the equivalent set of keys.
• For each key `K` of `X`, X.get(K) == Y.get(K) returns true.
Preconditions
`Y` must be a `map`.
The equivalence relations of keys of `X` and `Y` must be same.
Values of `X` and `Y` must be comparable to each other using `==` operator.
6.32.2. MAP.is?(Val)¶
`is?` returns whether `Val` is a `map`.
6.32.3. MAP.mixin¶
`mixin` returns a mixin trait which provides default implementations of the following `map` methods.
• get
• have_key?
• any?
• key_iter
• op_eq / `==` operator