Lisaac prototype interface

Section Header
+ name := DICTIONARY[V, K];
- comment := "Associative memory. Values of type `V' are stored using Keys of type `K'.";
To make a comparison with the well knowned ARRAY class, with a DICTIONARY,
index used are not only INTEGER, you can use for example a STRING to access
to your information.
Well knowned implementations, see HASHED_DICTIONARY and AVL_DICTIONARY.
See also BIJECTIVE_DICTIONARY class.
Section Inherit
+ parent_traversable:Expanded TRAVERSABLE[V];
Section Public
Counting:
- count:INTEGER <-
Actual `count' of stored elements.
- is_empty:BOOLEAN <-
Is it empty?
Basic access:
- has k:K :BOOLEAN <-
Is there a value currently associated with key `k'?
See also `fast_has', `at'.
- at k:K :V <-
Return the value associated to key `k'.
See also `fast_at', `reference_at', `has'.
- reference_at k:K :V <-
Return NULL or the value associated with key `k'. Actually, this
feature is useful when the type of values (the type V) is a
reference type, to avoid using `has' just followed by `at' to get
the corresponding value.
See also `fast_reference_at', `at', `has'.
- fast_has k:K :BOOLEAN <-
Is there a value currently associated with key `k'?
Using basic `=' for comparison.
See also `has', `at', `fast_at'.
- fast_at k:K :V <-
Return the value associated to key `k' using basic `=' for comparison.
See also `at', `reference_at', `fast_reference_at'.
- fast_reference_at k:K :V <-
Same work as `reference_at', but basic `=' is used for comparison.
See also `reference_at', `at', `has'.
Modification.
- put v:V to k:K <-
Change some existing entry or `add' the new one. If there is as yet
no key `k' in the dictionary, enter it with item `v'. Otherwise
overwrite the item associated with key `k'.
As the `put' procedure actually uses `is_equal', you may consider
to use `fast_put' for expanded objects as well while trying to get
the very best performances.
See also `fast_put', `add'.
- fast_put v:V to k:K <-
Same job as `put', but uses basic `=' for comparison.
See also `put', `add'.
- add v:V to k:K <-
To add a new entry `k' with its associated value `v'.
Actually, this is equivalent to call `put', but it may run a little bit faster.
See also `put', `fast_put'.
Looking and searching some value:
- occurrences v:V :INTEGER <-
Number of occurrences using `is_equal' for comparison.
See also `fast_occurrences', `fast_has', `has'.
- fast_occurrences v:V :INTEGER <-
Number of occurrences using basic `=' for comparison.
See also `occurrences', `fast_has', `has'.
- key_at v:V :K <-
Retrieve the key used for value `v' using `is_equal' for comparison.
See also `fast_key_at', `at'.
- fast_key_at v:V :K <-
Retrieve the key used for value `v' using `=' for comparison.
See also `key_at', `at'.
Removing:
- remove k:K <-
Remove entry `k' (which may exist or not before this call).
As the `remove' procedure actually uses `is_equal', you may
consider to use `fast_remove' for expanded objects as well
while trying to get the very best performances.
See also `fast_remove', `clear_count'.
- fast_remove k:K <-
Same job as `remove', but uses basic `=' for comparison.
See also `remove', `clear_count'.
- clear_count <-
Discard all items (`is_empty' is True after that call).
The internal `capacity' is not changed by this call.
See also `clear_count_and_capacity', `remove'.
- clear_count_and_capacity <-
Discard all items (`is_empty' is True after that call).
The internal `capacity' may also be reduced after this call.
See also `clear_count', `remove'.
- capacity:INTEGER <-
Approximation of the actual internal storage `capacity'.
The `capacity' will grow automatically when needed
(i.e. `capacity' is not a limit for the number of values stored).
Also note that the `capacity' value may not be always accurate
depending of the implementation (anyway, this `capacity' value
is at least equals to `count').
To provide iterating facilities:
- lower:INTEGER :=
- upper:INTEGER <-
- item i:INTEGER :V <-
- first:V <-
- last:V <-
- key index:INTEGER :K <-
- key_map_in buffer:COLLECTION[K] <-
Append in `buffer', all available keys (this may be useful to
speed up the traversal).
See also `item_map_in'.
- item_map_in buffer:COLLECTION[V] <-
Append in `buffer', all available items (this may be useful to
speed up the traversal).
See also `key_map_in'.
Comparaison.
- '==' other:SELF :BOOLEAN <-
Do both dictionaries have the same set of associations?
Keys are compared with `is_equal' and values are comnpared
with the basic = operator.
See also `is_equal_map'.
- is_equal_map other:SELF :BOOLEAN <-
Do both dictionaries have the same set of associations?
Both keys and values are compared with `is_equal'.
See also `is_equal'.
- copy other:SELF <-
Reinitialize by copying all associations of `other'.
Agents based features:
- do_all action:BLOCK <-
Apply `action' to every [V, K] associations of `Current'.
See also `for_all', `exist'.
- for_all test:BLOCK :BOOLEAN <-
Do all [V, K] associations satisfy `test'?
See also `do_all', `exist'.
- exists test:BLOCK :BOOLEAN <-
Does at least one [V, K] association satisfy `test'?
See also `for_all', `do_all'.
Other features:
- internal_key k:K :K <-
Retrieve the internal key object which correspond to the existing
entry `k' (the one memorized into the `Current' dictionary).
See also `has', `fast_has'.
Creation.
- create:SELF <-
- make <-
Creates an empty dictionary.
- key_safe_equal k1:K with k2:K :BOOLEAN <-
Because keys are never NULL, we do not rely on the SAFE_EQUAL class.
invariant
[ -? {capacity >= count}; ]