/src/lib/storage/dictionary.e

  1-- This file is part of a Liberty Eiffel library.
  2-- See the full copyright at the end.
  3--
  4deferred class DICTIONARY[V_, K_]
  5   --
  6   -- Associative memory. Values of type `V_' are stored using Keys of type `K_'.
  7   -- To make a comparison with the well known ARRAY class, with a DICTIONARY, index used are not only
  8   -- INTEGER, you can use for example a STRING to access to your information.
  9   --
 10   -- Well known implementations, see HASHED_DICTIONARY, AVL_DICTIONARY and ARRAY_DICTIONARY.
 11   --
 12   -- See also BIJECTIVE_DICTIONARY class.
 13   --
 14
 15inherit
 16   MAP[V_, K_]
 17
 18feature {ANY} -- Adding:
 19   put (v: V_; k: K_) assign at
 20         -- Change some existing entry or `add' the new one. If there is as yet no key `k' in the dictionary,
 21         -- enter it with item `v'. Otherwise overwrite the item associated with key `k'.
 22         -- As the `put' procedure actually uses `is_equal', you may consider to use `fast_put' for expanded
 23         -- objects as well while trying to get the very best performances.
 24         --
 25         -- See also `fast_put', `add'.
 26      require
 27         k /= Void
 28      deferred
 29      ensure
 30         v = at(k)
 31      end
 32
 33   fast_put (v: V_; k: K_) assign fast_at
 34         -- Same job as `put', but uses basic `=' for comparison.
 35         -- If you are sure that `k' is not an existing entry, please consider using `add'
 36         -- to get very best performances.
 37         --
 38         -- See also `put', `add'.
 39      require
 40         k /= Void
 41      deferred
 42      ensure
 43         v = at(k)
 44      end
 45
 46   add (v: V_; k: K_)
 47         -- To add a new entry `k' with its associated value `v'.
 48         -- Actually, this is equivalent to call `put', but it may run a little bit faster.
 49         --
 50         -- See also `put', `fast_put'.
 51      require
 52         not has(k)
 53      deferred
 54      ensure
 55         count = 1 + old count
 56         v = at(k)
 57      end
 58
 59   set_item (v: V_; index: INTEGER)
 60      require
 61         valid_index(index)
 62      deferred
 63      ensure
 64         count = old count
 65         v = item(index)
 66      end
 67
 68feature {ANY} -- Removing:
 69   remove (k: K_)
 70         -- Remove entry `k' (which may exist or not before this call).
 71         -- As the `remove' procedure actually uses `is_equal', you may consider to use `fast_remove' for expanded
 72         -- objects as well while trying to get the very best performances.
 73         --
 74         -- See also `fast_remove', `clear_count'.
 75      require
 76         k /= Void
 77      deferred
 78      ensure
 79         not has(k)
 80      end
 81
 82   fast_remove (k: K_)
 83         -- Same job as `remove', but uses basic `=' for comparison.
 84         --
 85         -- See also `remove', `clear_count'.
 86      require
 87         k /= Void
 88      deferred
 89      ensure
 90         not fast_has(k)
 91      end
 92
 93   clear_count
 94         -- Discard all items (`is_empty' is True after that call). The internal `capacity' is not changed
 95         -- by this call.
 96         --
 97         -- See also `clear_count_and_capacity', `remove'.
 98      deferred
 99      ensure
100         is_empty: count = 0
101         capacity = old capacity
102      end
103
104   clear_count_and_capacity
105         -- Discard all items (`is_empty' is True after that call). The internal `capacity' may also be
106         -- reduced after this call.
107         --
108         -- See also `clear_count', `remove'.
109      deferred
110      ensure
111         is_empty: count = 0
112         capacity <= old capacity
113      end
114
115   capacity: INTEGER
116         -- Approximation of the actual internal storage `capacity'. The `capacity' will grow automatically
117         -- when needed (i.e. `capacity' is not a limit for the number of values stored). Also note that
118         -- the `capacity' value may not be always accurate depending of the implementation (anyway, this
119         -- `capacity' value is at least equals to `count').
120      deferred
121      end
122
123feature {ANY}
124   copy (other: like Current)
125         -- Reinitialize by copying all associations of `other'.
126      local
127         i: INTEGER
128      do
129         clear_count
130         from
131            i := 1
132         until
133            i > other.count
134         loop
135            put(other.item(i), other.key(i))
136            i := i + 1
137         end
138      end
139
140   new_iterator_on_items: ITERATOR[V_]
141      do
142         create {ITERATOR_ON_DICTIONARY_ITEMS[V_, K_]} Result.make(Current)
143      ensure then
144         Result /= Void
145      end
146
147feature {}
148   make
149         -- Creates an empty dictionary.
150      deferred
151      ensure
152         is_empty
153      end
154
155feature {} -- Implement manifest generic creation:
156   manifest_make (needed_capacity: INTEGER)
157         -- Manifest creation of a dictionary.
158      do
159         make
160      end
161
162   manifest_put (index: INTEGER; v: V_; k: K_)
163      require
164         not has(k)
165      do
166         add(v, k)
167      end
168
169   manifest_semicolon_check: INTEGER 2
170         -- Put semicolons between successive value-key pairs.
171
172feature {}
173   key_safe_equal (k1, k2: K_): BOOLEAN
174         -- Because keys are never Void, we do not rely on the SAFE_EQUAL class.
175      require
176         k1 /= Void
177         k2 /= Void
178      do
179         if k1 = k2 then
180            Result := True
181         elseif k1.same_dynamic_type(k2) then
182            Result := k1.is_equal(k2)
183         end
184      end
185
186end -- class DICTIONARY
187--
188-- Copyright (C) 2009-2017: by all the people cited in the AUTHORS file.
189--
190-- Permission is hereby granted, free of charge, to any person obtaining a copy
191-- of this software and associated documentation files (the "Software"), to deal
192-- in the Software without restriction, including without limitation the rights
193-- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
194-- copies of the Software, and to permit persons to whom the Software is
195-- furnished to do so, subject to the following conditions:
196--
197-- The above copyright notice and this permission notice shall be included in
198-- all copies or substantial portions of the Software.
199--
200-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
201-- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
202-- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
203-- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
204-- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
205-- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
206-- THE SOFTWARE.