6.33. kink/container/ORDER_MAP

6.33.1. type order_map

`order_map` is a subtype of `map` type which supports total ordering of keys. Equivalence relation of keys is derived from the toal order.

Total order relation of keys

The total order relation of keys, `up-to`, must suffice the following conditions for all X, Y, and Z in the domain of keys.

• reflexive: X up-to X

• transitive: if X up-to Y && Y up-to Z then X up-to Z

• antisymmetric: if X up-to Y && Y up-to X then X equivalent-to Y

• strongly connected: X up-to Y || Y up-to X

The antisymmetry condition is the definition of `equivalent-to`, which is the equivalence relation of keys.

Methods

`order_map` values have all the methods of `map`.

Additionally, `order_map` values have the following methods.

6.33.1.1. Map.order

`order` returns the function of the total order relation of keys of `Map`.

The result function, $up_to?, is a function which takes two args `X` and `Y`. `up_to?(X Y)` returns the bool value of `X up-to Y`, where `up-to` is the total-order relation of keys.

6.33.1.2. Map.key_iter(...[Min_key])

`key_iter` returns an `iter` of keys following the order. If `Min_key` is passed, the iter will have the keys which are bigger than or equivalent to `Min_key`. If `Min_key` is not passed, the iter will have all the keys of `Map`.

`key_iter` method of `order_map` type extends the contract of `key_iter` of `map` type.

Precondition

`Min_key` must be in the domain of the total order of keys.

Example

:TREE_MAP.require_from('kink/container/')

:Map <- TREE_MAP.of(
  'foo' 'FOO'
  'bar' 'BAR'
  'baz' 'BAZ'
  'qux' 'QUX'
  'grault' 'GRAULT'
)
Map.key_iter.each{(:K)
  stdout.print_line(K.repr)
}
# Output:
#   "bar"
#   "baz"
#   "foo"
#   "grault"
#   "qux"

Map.key_iter('f').each{(:K)
  stdout.print_line(K.repr)
}
# Output:
#   "foo"
#   "grault"
#   "qux"

6.33.1.3. Map.pair_iter(...[Min_key])

`pair_iter` returns an `iter` of pairs [Key Val] following the order. If `Min_key` is passed, the iter will have pairs whose keys are bigger than or equivalent to `Min_key`. If `Min_key` is not passed, the iter will have all the key-value pairs of `Map`.

`pair_iter` method of `order_map` type extends the constraints of `pair_iter` of `map` type.

Precondition

`Min_key` must be in the domain of the total order of keys.

Example

:TREE_MAP.require_from('kink/container/')

:Map <- TREE_MAP.of(
  'foo' 'FOO'
  'bar' 'BAR'
  'baz' 'BAZ'
  'qux' 'QUX'
  'grault' 'GRAULT'
)

Map.pair_iter.each{(:Pair)
  stdout.print_line(Pair.repr)
}
# Output:
#   ["bar" "BAR"]
#   ["baz" "BAZ"]
#   ["foo" "FOO"]
#   ["grault" "GRAULT"]
#   ["qux" "QUX"]

Map.pair_iter('f').each{(:Pair)
  stdout.print_line(Pair.repr)
}
# Output:
#   ["foo" "FOO"]
#   ["grault" "GRAULT"]
#   ["qux" "QUX"]

6.33.1.4. Map.front_key

`front_key` returns the key which comes first in the order.

Precondition

`Map` must not be empty.

Example

:TREE_MAP.require_from('kink/container/')

:Map <- TREE_MAP.of(
  'foo' 'FOO'
  'bar' 'BAR'
  'baz' 'BAZ'
  'qux' 'QUX'
  'grault' 'GRAULT'
)
stdout.print_line(Map.front_key.repr) # => "bar"

6.33.1.5. Map.back_key

`back_key` returns the key which comes last in the order.

Precondition

`Map` must not be empty.

Example

:TREE_MAP.require_from('kink/container/')

:Map <- TREE_MAP.of(
  'foo' 'FOO'
  'bar' 'BAR'
  'baz' 'BAZ'
  'qux' 'QUX'
  'grault' 'GRAULT'
)
stdout.print_line(Map.back_key.repr) # => "qux"

6.33.2. ORDER_MAP.is?(Val)

`is?` returns whether `Val` is an `order_map`.

6.33.3. ORDER_MAP.mixin

`mixin` returns a mixin trait which provides default implementations of the following `order_map` methods.

• eq

• get

• have_key?

• any?

• key_iter

• op_eq / `==` operator