src/TCollection/TCollection_IndexedDataMap.cdl

   1 -- File:        TCollection_IndexedDataMap.cdl
   2 -- Created:     Fri Jan  8 17:49:04 1993
   3 -- Author:      Remi LEQUETTE
   4 --              <rle@phylox>
   5 ---Copyright:    Matra Datavision 1993
   6
   7
   8 generic class IndexedDataMap from TCollection
   9     (TheKey    as any;
  10      TheItem   as any;
  11      Hasher as any) -- as MapHasher(TheKey)
  12 inherits BasicMap from TCollection
  13
  14         ---Purpose: An indexed map is used to store keys and to  bind
  15         -- an index to them.  Each  new key stored in the map
  16         -- gets an index.  Index are  incremented as keys are
  17         -- stored in the map. A key can be found by the index
  18         -- and an index by the key.  No  key but the last can
  19         -- be  removed so the  indices   are in the range 1..
  20         -- Extent.  An Item is stored with each key.
  21         --
  22         -- This   class is   similar  to  IndexedMap     from
  23         -- TCollection  with the Item as  a new feature. Note
  24         -- the important difference on  the operator  ().  In
  25         -- the IndexedMap this operator returns  the Key.  In
  26         -- the IndexedDataMap this operator returns the Item.
  27         -- An IndexedDataMap is an ordered
  28         -- map, which allows a linear iteration on its contents. It
  29         -- combines the behavior of:
  30         -- -   an array because data may be accessed with an index,
  31         -- -   and a map because data may also be accessed with a key.
  32         -- IndexedDataMap is a generic class which depends on three parameters:
  33         -- -   Key is the type of key for an entry in the map,
  34         -- -   Item is the type of element associated with a key in the map,
  35         -- -   Hasher is the type of hasher on keys.
  36         --   Notes:
  37         -- -   IndexedDataMap is similar to
  38         --   TCollection_IndexedMap with the item as a new
  39         --   feature. Note, however, the important difference with operator ():
  40         --   -   for an IndexedMap this operator returns the key, but
  41         --   -   for an IndexedDataMap it returns the item.
  42         -- -   It is recommended not to explore an IndexedDataMap
  43         --   map with an iterator: you just use indexes.
  44         -- -   TCollection_MapHasher class describes the
  45         --   functions required for a Hasher object.
  46
  47 raises
  48     DomainError  from Standard,
  49     OutOfRange   from Standard,
  50     NoSuchObject from Standard
  51
  52     class IndexedDataMapNode from TCollection
  53     inherits MapNode from TCollection
  54     uses MapNodePtr from TCollection
  55     is
  56       Create(K1 : TheKey; K2 : Integer; I : TheItem; n1,n2 : MapNodePtr from TCollection) returns IndexedDataMapNode from TCollection;
  57       ---C++: inline
  58             Key1(me) returns TheKey;
  59       ---C++: return &
  60       ---C++: inline
  61
  62       Key2(me) returns Integer;
  63       ---C++: return &
  64       ---C++: inline
  65
  66       Next2(me) returns MapNodePtr from TCollection;
  67       ---C++: return &
  68       ---C++: inline
  69
  70       Value(me) returns TheItem;
  71       ---C++: return &
  72       ---C++: inline
  73
  74     fields
  75         myKey1 : TheKey;
  76         myKey2 : Integer from Standard;
  77         myValue : TheItem;
  78         myNext2 : MapNodePtr from TCollection;
  79     end;
  80
  81 is
  82
  83     Create(NbBuckets : Integer = 1) returns IndexedDataMap from TCollection;
  84         ---Purpose: Constructs an IndexedDataMap with NbBuckets
  85         -- (defaulted to 1) buckets.
  86         -- Note that the map will be automatically redimensioned
  87         -- during its use if the number of entries becomes too large.
  88         -- Use:
  89         -- -   the function Add to add an entry (key, item, index) in the map,
  90         -- -   operator() to read an item from an index, or to
  91         --   assign a new value to this item,
  92         -- -   the function FindFromKey or ChangeFromKey to
  93         --   read an item from a key, or to assign a new value to this item,
  94         -- -   the function RemoveLast to remove the last entry from the map,
  95         -- -   and other available edition and querying functions.
  96
  97
  98     Create(Other : IndexedDataMap from TCollection)
  99     returns IndexedDataMap from TCollection
 100         ---Purpose: As  copying  Map  is an expensive  operation it is
 101         -- incorrect  to  do  it implicitly. This constructor
 102         -- will raise an  error if the Map  is not  empty. To copy the
 103         -- content of a  Map use the  Assign  method (operator =).
 104     raises DomainError from Standard
 105     is private;
 106
 107     Assign(me : in out; Other : IndexedDataMap from TCollection)
 108     returns IndexedDataMap from TCollection
 109         ---Purpose: Replace the content of this map by  the content of
 110         -- the map <Other>.
 111         ---C++: alias operator =
 112         ---C++: return &
 113     is static;
 114
 115     ReSize(me : in out; NbBuckets : Integer)
 116         ---Purpose: Changes the  number    of  buckets of  <me>  to be
 117         -- <NbBuckets>. The entries (key + item + index) already
 118         -- stored in this map are maintained.
 119     is static;
 120
 121     Clear(me : in out)
 122         ---Purpose: Removes all keys in the map.
 123         ---C++: alias ~
 124     is static;
 125
 126     Add(me : in out; K : TheKey; I : TheItem) returns Integer
 127         ---Purpose: Adds  the Key  <K> to the  Map <me>.   Returns the
 128         -- index of  the  Key.  The key is new  in the map if
 129         -- Extent  has  been  incremented.  The Item  <I>  is
 130         -- stored with the key. If the key was already in the
 131         -- map the previous item is not replaced by <I>.
 132     is static;
 133
 134     Substitute(me : in out; I : Integer; K : TheKey; T : TheItem)
 135         ---Purpose: Substitutes the Key at  index <I>  with  <K>.  <I>
 136         -- must be a valid index, <K> must  be a new key. <T>
 137         -- becomes the Item stored with <K>.
 138         -- Trigger: Raises OutOfRange if I < 1 or I > Extent.
 139         -- Raises DomainError if Contains(K).
 140     raises
 141         OutOfRange  from Standard,
 142         DomainError from Standard
 143     is static;
 144
 145     RemoveLast(me : in out)
 146         ---Purpose: Removes  the last key entered  in the map, i.e the
 147         -- key of index Extent().
 148         --        I must be a valid index and K must be a new key.
 149         -- Exceptions
 150         -- -   Standard_OutOfRange if the index I is less than 1 or
 151         --   greater than the number of entries in this map.
 152         -- -   Standard_DomainError if the key K is already in this map.
 153     raises
 154         OutOfRange  from Standard
 155     is static;
 156
 157     Contains(me; K : TheKey) returns Boolean
 158         ---Purpose: Returns True if the key <K>  is stored  in the map <me>.
 159     is static;
 160
 161     FindKey(me; I : Integer) returns any TheKey
 162         ---Purpose: Returns the Key of index <I>.
 163         --       Exceptions
 164         -- Standard_OutOfRange if I is less than 1 or greater than
 165         -- the number of entries in this map.
 166         ---C++: return const &
 167     raises OutOfRange from Standard
 168     is static;
 169
 170     FindFromIndex(me; I : Integer) returns any TheItem
 171         ---Level: Public
 172         ---Purpose: Returns the Item of index <I>.
 173         ---Trigger: Raises OutOfRange if I < 1 or I > Extent
 174         ---C++: alias operator ()
 175         ---C++: return const &
 176     raises OutOfRange from Standard
 177     is static;
 178
 179     ChangeFromIndex(me : in out; I : Integer) returns any TheItem
 180         ---Level: Public
 181         ---Purpose: Returns  the  Item of index <I>.  The Item  can be
 182         -- modified with the syntax aMap(Index) = newItem.
 183         ---Trigger: Raises OutOfRange if I < 1 or I > Extent
 184         ---C++: alias operator ()
 185         ---C++: return &
 186     raises OutOfRange from Standard
 187     is static;
 188
 189     FindIndex(me; K : TheKey) returns Integer
 190         ---Purpose: Returns the index of the key <K>.
 191         -- Returns 0 if K is not in the map.
 192     is static;
 193
 194     FindFromKey(me; K : TheKey) returns any TheItem
 195         ---Purpose: Returns the Item of the key <K>
 196         -- Trigger: Raises NoSuchObject if K is not in the map.
 197     raises NoSuchObject from Standard
 198     ---C++: return const &
 199     is static;
 200
 201     ChangeFromKey(me : in out; K : TheKey) returns any TheItem
 202         ---Purpose: Returns the Item of the key <K>
 203         -- Trigger: Raises NoSuchObject if K is not in the map.
 204     raises NoSuchObject from Standard
 205     ---C++: return &
 206     is static;
 207
 208 end IndexedDataMap;