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}; ]