src/TCollection/TCollection_DoubleMap.cdl

   1 -- File:        TCollection_DoubleMap.cdl
   2 -- Created:     Fri Jan  8 17:15:50 1993
   3 -- Author:      Remi LEQUETTE
   4 --              <rle@phylox>
   5 ---Copyright:    Matra Datavision 1993
   6
   7
   8 generic class DoubleMap from TCollection (TheKey1    as any;
   9                                           TheKey2    as any;
  10                                           Hasher1 as any; -- as MapHasher(TheKey1)
  11                                           Hasher2 as any) -- as MapHasher(TheKey2)
  12 inherits BasicMap from TCollection
  13
  14         ---Purpose:
  15         -- A map used to bind pairs of keys (Key1,Key2) and
  16         -- retrieve them in linear time. Key1 is referenced as the
  17         -- first key of the DoubleMap and Key2 as the second key.
  18         -- An entry of a DoubleMap is composed of a pair of two
  19         -- keys: the first key and the second key.
  20         -- DoubleMap is a generic class which depends on four parameters:
  21         -- -   Key1 is the type of the first key for an entry in the map,
  22         -- -   Key2 is the type of the second key for an entry in the   map,
  23         -- -   Hasher1 is the type of hasher on first keys,
  24         -- -   Hasher2 is the type of hasher on second keys.
  25         --   Use a DoubleMapIterator to explore a DoubleMap map.
  26         -- Notes:
  27         -- -   An iterator class is automatically instantiated from the
  28         --   TCollection_DoubleMapIterator class at the time of
  29         --   instantiation of a DoubleMap map.
  30         -- -   TCollection_MapHasher class describes the
  31         --   functions required for a Hasher1 or a Hasher2 object.
  32
  33 raises
  34     DomainError     from Standard,
  35     MultiplyDefined from Standard,
  36     NoSuchObject    from Standard
  37
  38     class DoubleMapNode from TCollection
  39     inherits MapNode from TCollection
  40     uses MapNodePtr from TCollection
  41     is
  42       Create(K1 : TheKey1; K2 : TheKey2; n1,n2 : MapNodePtr from TCollection) returns DoubleMapNode from TCollection;
  43       ---C++: inline
  44
  45       Key1(me) returns TheKey1;
  46       ---C++: return &
  47       ---C++: inline
  48
  49       Key2(me) returns TheKey2;
  50       ---C++: return &
  51       ---C++: inline
  52
  53       Next2(me) returns MapNodePtr from TCollection;
  54       ---C++: return &
  55       ---C++: inline
  56
  57     fields
  58         myKey1 : TheKey1;
  59         myKey2 : TheKey2;
  60         myNext2 : MapNodePtr from TCollection;
  61     end;
  62
  63     class DoubleMapIterator inherits BasicMapIterator from TCollection
  64
  65         ---Purpose: Functions used for iterating the contents of a DoubleMap map.
  66         -- Note: an iterator class is automatically instantiated from
  67         -- this generic class at the time of instantiation of a DoubleMap map.
  68         -- Warning
  69         -- -   A map is a non-ordered data structure. The order in
  70         --   which entries of a map are explored by the iterator
  71         --   depends on its contents, and changes when the map is edited.
  72         -- -   It is not recommended to modify the contents of a map
  73         --   during iteration: the result is unpredictable.
  74
  75     raises NoSuchObject from Standard
  76     is
  77         Create returns DoubleMapIterator from TCollection;
  78             ---Purpose: Creates an undefined Iterator (empty) use the
  79             --- function Initialize to define the map to explore.
  80
  81         Create (aMap : DoubleMap from TCollection)
  82         returns DoubleMapIterator from TCollection;
  83             ---Purpose: Creates an Iterator on the map <aMap>.
  84
  85         Initialize(me : in out; aMap : DoubleMap from TCollection)
  86             ---Level: Public
  87             ---Purpose: Sets or resets the Iterator in the map <aMap>.
  88         is static;
  89
  90         Key1(me) returns any TheKey1
  91             ---Purpose: Returns the first key,  of the current
  92             --  entry in the map for this iterator.
  93             -- Note: Key1 and Key2 are the types of the first and second
  94             -- keys for an entry in the explored DoubleMap map.
  95             -- Exceptions
  96             -- Standard_NoSuchObject if this iterator is empty (i.e.
  97             -- when the function More returns false).
  98             ---C++: return const &
  99         raises
 100             NoSuchObject from Standard
 101         is static;
 102
 103         Key2(me) returns any TheKey2
 104             ---Purpose: Returns the second key, of the current
 105             --  entry in the map for this iterator.
 106             -- Note: Key1 and Key2 are the types of the first and second
 107             -- keys for an entry in the explored DoubleMap map.
 108             -- Exceptions
 109             -- Standard_NoSuchObject if this iterator is empty (i.e.
 110             -- when the function More returns false).
 111             ---C++: return const &
 112         raises
 113             NoSuchObject from Standard
 114         is static;
 115
 116     end DoubleMapIterator from TCollection;
 117
 118 is
 119
 120     Create(NbBuckets : Integer = 1) returns DoubleMap from TCollection;
 121         ---Purpose: Creates   a DoubleMap with  <NbBuckets> buckets. Without
 122         -- arguments the map is automatically dimensioned.
 123
 124
 125     Create(Other : DoubleMap from TCollection)
 126     returns DoubleMap from TCollection
 127         ---Purpose: As  copying  Map  is an expensive  operation it is
 128         -- incorrect  to  do  it implicitly. This constructor is private and
 129         -- will raise an  error if the Map  is not  empty. To copy the
 130         -- content of a  Map use the  Assign  method (operator =).
 131     raises DomainError from Standard
 132     is private;
 133
 134     Assign(me : in out; Other : DoubleMap from TCollection)
 135     returns DoubleMap from TCollection
 136         ---Purpose: Copies the contents of the map Other into this map.
 137         -- Note that this method is an alias of operator =.
 138         ---C++: alias operator =
 139         ---C++: return &
 140     is static;
 141
 142     ReSize(me : in out; NbBuckets : Integer)
 143         ---Purpose: Changes the number of buckets of this map to N.
 144         -- The entries (Key1 + Key2) already stored in this map are maintained.
 145     is static;
 146
 147     Clear(me : in out)
 148         ---Level: Public
 149         ---Purpose: Removes all keys from the map.
 150         ---C++: alias ~
 151     is static;
 152
 153     Bind(me : in out; K1 : TheKey1; K2 : TheKey2)
 154         ---Level: Public
 155         ---Purpose: Adds the pair <K1>,<K2> to the map.
 156         --  Trigger: An exception is raised if K1 or K2 are already bound.
 157     raises MultiplyDefined from Standard
 158     is static;
 159
 160     AreBound(me; K1 : TheKey1; K2 : TheKey2) returns Boolean
 161         ---Level: Public
 162         ---Purpose: Returns True if <K1>  and  <K2>  are bound to each other in the map <me>.
 163     is static;
 164
 165     IsBound1(me; K : TheKey1) returns Boolean
 166         ---Level: Public
 167         ---Purpose: Returns  True if the  TheKey <K> is  bound in the map <me>.
 168     is static;
 169
 170     IsBound2(me; K : TheKey2) returns Boolean
 171         ---Level: Public
 172         ---Purpose: Returns True if  the key <K> is bound in the map <me>.
 173     is static;
 174
 175     Find1(me; K : TheKey1) returns any TheKey2
 176         ---Level: Public
 177         ---Purpose: Returns the Key2 bound to <K> in the map.
 178         ---C++: return const &
 179     raises NoSuchObject
 180     is static;
 181
 182     Find2(me; K : TheKey2) returns any TheKey1
 183         ---Level: Public
 184         ---Purpose: Returns the Key1 bound to <K> in the map.
 185         ---C++: return const &
 186     raises NoSuchObject
 187     is static;
 188
 189     UnBind1(me : in out; K : TheKey1) returns Boolean
 190         ---Level: Public
 191         ---Purpose: Unbind the Key <K>  from the map.  Returns True if
 192         -- the Key was bound in the Map.
 193     is static;
 194
 195     UnBind2(me : in out; K : TheKey2) returns Boolean
 196         ---Level: Public
 197         ---Purpose: Unbind the Key <K>  from the map.  Returns True if
 198         -- the Key was bound in the Map.
 199     is static;
 200
 201 end DoubleMap;