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