src/TCollection/TCollection_IndexedMap.cdl

   1 -- File:        TCollection_IndexedMap.cdl
   2 -- Created:     Fri Jan  8 17:35:39 1993
   3 -- Author:      Remi LEQUETTE
   4 --              <rle@phylox>
   5 ---Copyright:    Matra Datavision 1993
   6
   7
   8 generic class IndexedMap from TCollection (TheKey as any;
   9                                            Hasher as any) -- as MapHasher(TheKey)
  10 inherits BasicMap from TCollection
  11
  12         ---Purpose: An indexed map is used to  store  keys and to bind
  13         -- an index to them. An index is assigned to each new key stored in the map.
  14         -- Indexes incremented as keys are stored in the map. A key
  15         -- can be found by the index, and an index by the key. No key
  16         -- except for the last can be removed, so the indexes are in
  17         -- the range 1..Upper where Upper is the number of
  18         -- keys stored in the map.
  19         -- An entry of an IndexedMap is composed of both the key
  20         -- and the index. An IndexedMap is an ordered map, which
  21         -- allows a linear iteration on its contents. But no data is
  22         -- attached to the key. An IndexedMap is typically used by
  23         -- an algorithm to know if some action is still performed on
  24         -- components of a complex data structure.
  25         -- IndexedMap is a generic class which depends on two parameters:
  26         -- -   Key is the type of key for an entry in the map,
  27         -- -   Hasher is the type of hasher on keys.
  28         -- Notes:
  29         -- -   It is not recommended to explore an IndexedMap map
  30         --   with an iterator: you just use indexes.
  31         -- -   TCollection_MapHasher class describes the
  32         --   functions required for a Hasher object.
  33         -- -   TCollection_IndexedDataMap is a similar map with
  34         --   an item as a new feature.
  35
  36 raises
  37     DomainError from Standard,
  38     OutOfRange  from Standard
  39
  40     class IndexedMapNode from TCollection
  41     inherits MapNode from TCollection
  42     uses MapNodePtr from TCollection
  43     is
  44       Create(K1 : TheKey; K2 : Integer; n1,n2 : MapNodePtr from TCollection) returns IndexedMapNode from TCollection;
  45       ---C++: inline
  46
  47       Key1(me) returns TheKey;
  48       ---C++: return &
  49       ---C++: inline
  50
  51       Key2(me) returns Integer;
  52       ---C++: return &
  53       ---C++: inline
  54
  55       Next2(me) returns MapNodePtr from TCollection;
  56       ---C++: return &
  57       ---C++: inline
  58
  59     fields
  60         myKey1 : TheKey;
  61         myKey2 : Integer from Standard;
  62         myNext2 : MapNodePtr from TCollection;
  63     end;
  64
  65 is
  66
  67     Create(NbBuckets : Integer = 1) returns IndexedMap from TCollection;
  68         ---Purpose: Constructs an IndexedMap with NbBuckets (defaulted to 1) buckets.
  69         -- Note that the map will be automatically redimensioned
  70         -- during its use if the number of entries becomes too large.
  71         -- Use:
  72         -- -   the function Add to add a new entry (key, index) to the map,
  73         -- -   operator() to read a key from an index,
  74         -- -   the function FindIndex to read an index from a key,
  75         -- -   the function RemoveLast to remove the last entry from the map.
  76
  77     Create(Other : IndexedMap from TCollection)
  78     returns IndexedMap from TCollection
  79         ---Purpose: As  copying  Map  is an expensive  operation it is
  80         -- incorrect  to  do  it implicitly. This constructor
  81         -- will raise an  error if the Map  is not  empty. To
  82         -- copy the content of a  Map use the  Assign  method (operator =).
  83     raises DomainError from Standard
  84     is private;
  85
  86
  87     Assign(me : in out; Other : IndexedMap from TCollection)
  88     returns IndexedMap from TCollection
  89         ---Purpose: Replace the content of this map by  the content of
  90         -- the map <Other>.
  91         ---C++: alias operator =
  92         ---C++: return &
  93     is static;
  94
  95     ReSize(me : in out; NbBuckets : Integer)
  96         ---Purpose: Changes the  number    of  buckets of  <me>  to be
  97         -- <NbBuckets>. The keys  already  stored in  the map are kept.
  98     is static;
  99
 100     Clear(me : in out)
 101         ---Purpose: Removes all keys in the map.
 102         ---C++: alias ~
 103     is static;
 104
 105     Add(me : in out; K : TheKey) returns Integer
 106         ---Purpose: Adds  the Key <K> to   the Map <me>.  Returns  the
 107         -- index  of the Key.  The key is new  in the map  if Extent
 108         -- has been incremented.
 109     is static;
 110
 111     Substitute(me : in out; I : Integer; K : TheKey)
 112         ---Purpose: Substitutes the Key  at index  <I>  with <K>.
 113         -- <I> must be a valid index, <K> must be a new key.
 114         -- Trigger: Raises OutOfRange if I < 1 or I > Extent
 115         -- Raises DomainError if Contains(K)
 116     raises
 117         OutOfRange  from Standard,
 118         DomainError from Standard
 119     is static;
 120
 121     RemoveLast(me : in out)
 122         ---Purpose: Removes  the last key entered  in the map, i.e the
 123         -- key of index Extent().
 124         -- Trigger: Raises OutOfRange if Extent() == 0
 125     raises
 126         OutOfRange  from Standard
 127     is static;
 128
 129     Contains(me; K : TheKey) returns Boolean
 130         ---Level: Public
 131         ---Purpose: Returns True if the key <K>  is stored  in the map <me>.
 132     is static;
 133
 134     FindKey(me; I : Integer) returns any TheKey
 135         ---Purpose: Returns the Key of index <I>.
 136         -- Trigger: Raises OutOfRange if I < 1 or I > Extent
 137         ---C++: alias operator ()
 138         ---C++: return const &
 139     raises OutOfRange from Standard
 140     is static;
 141
 142     FindIndex(me; K : TheKey) returns Integer
 143         ---Purpose: Returns the index of the key <K> Returns 0 if K is
 144         -- not in the map.
 145     is static;
 146
 147 end IndexedMap;