MAP¶

6.32.1. type map¶

`map` is an abstract type of key-value containers. Keys must be unique in a `map`, in the equivalence relation defined by the implementation.

`ordered_map` is a subtype of `map` which supports total ordering of keys. See kink/container/ORDERED_MAP.

6.32.1.1. 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.2. 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.3. 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.4. Map.size¶

`size` returns the number of key-value pairs in `Map`, as an integer `num`.

6.32.1.5. Map.any?¶

`any?` returns whether `Map` contains one or more entries.

6.32.1.6. 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.7. 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.8. Map.clear¶

`clear` removes all the key-value pairs from `Map`.

6.32.1.9. 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.10. 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.11. 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`.