casacore
HashMapIter.h
Go to the documentation of this file.
1 //# <HashMap.h>: this defines HashMap, which is a hashed associative array
2 //# Copyright (C) 1995,1996,1998,1999,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 #ifndef CASA_HASHMAPITER_H
28 #define CASA_HASHMAPITER_H
29 
30 
31 #include <casacore/casa/aips.h>
32 #include <casacore/casa/Containers/HashMap.h>
33 
34 // <summary>
35 // Step through a const HashMap
36 // </summary>
37 // <use visibility=export>
38 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
39 //
40 // <synopsis>
41 // This class is an iterator, and it used to step through const
42 // <linkto class=HashMap><src>HashMap</src></linkto>s. This is useful
43 // when one wishes to find each of the user defined mappings in a
44 // particular map.
45 // </synopsis>
46 //
47 // <example>
48 // <srcblock>
49 // #include <casacore/casa/Containers/HashMap.h>
50 // #include <casacore/casa/BasicSL/String.h>
51 // #include <casacore/casa/iostream.h>
52 //
53 // main() {
54 // HashMap<String,Int> hash;
55 //
56 // hash.define("one",1);
57 // hash.define("two",2);
58 // hash.define("three",3);
59 // hash.define("four",4);
60 // hash.define("five",5);
61 // hash.define("six",6);
62 //
63 // ConstHashMapIter<String,Int> iter(hash);
64 // for ( iter.toStart(); ! iter.atEnd(); iter++ )
65 // cout << iter.getVal() << ": " << iter.getKey() << endl;
66 // }
67 // </srcblock>
68 // </example>
69 //
70 // <motivation>
71 // Sometimes one needs to step through the defined elements of an
72 // associative array. The user should be told when iterator does
73 // not modify the underlying data structure. The standard C++
74 // <em>const</em> is not sufficient because while the internal
75 // state of the iterator changes, the underlying data structure
76 // is not modified. For this reason, both const and non-const
77 // versions of the iterator are useful.
78 // </motivation>
79 //
80 namespace casacore { //#Begin casa namespace
81 
82 template<class key, class val> class ConstHashMapIter {
83 public:
84 
85  //
86  // Move the iterator to the start of the Map.
87  //
88  void toStart();
89 
90  //
91  // Advance to the next element of the Map.
92  //
93  // <group>
94  void operator++() { step(); }
95  void operator++(int) { step(); }
96  // </group>
97 
98  //
99  // Get the key or value for the current position in
100  // the Map.
101  //
102  // <group>
103  const key &getKey() const;
104  const val &getVal() const;
105  // </group>
106 
107  //
108  // Check to see if the iterator position is at the
109  // end or beginning of the Map.
110  //
111  // <group>
112  Bool atEnd() const { return atEnd_; }
113  Bool atStart() const;
114  // </group>
115 
116  //
117  // Check to see if the iterator is in a valid state.
118  //
119  Bool isValid() const { return Container != 0 ? True : False; }
120 
121  //
122  // Constructs a Map iterator from a Map (with reference semantics).
123  //
125 
126  //
127  // Assign one map iterator to a map (with reference semantics).
128  //
130 
131  //
132  // Constructs a Map iterator from another iterator (with reference semantics).
133  //
135 
136  //
137  // Assign one map iterator to another iterator (with reference semantics).
138  //
140 
141  //
142  // Default constructor creates an invalid Map iterator.
143  //
145 
146 
147  //
148  // Returns the default value for the Map on which this
149  // iterator is operating if it is a valid iterator, otherwise
150  // it throws an exception.
151  //
152  const val &defaultVal() const {
153  if ( ! isValid() )
155  return Container->defaultVal();
156  }
157 
158  //
159  // Allows mapping functions to be performed with the
160  // map on which this iterator operates. If this iterator
161  // is invalid, then an exception will be thrown.
162  //
163  const val &operator()(const key &ky) const {
164  if ( ! isValid() )
166  return Container->operator()(ky);
167  }
168 
169  //
170  // Allows one to check to see if a given key is defined
171  // in the map which this iterator tracks. If this iterator
172  // is invalid, then an exception will be thrown.
173  //
174  Bool isDefined(const key &ky) const {
175  if (! isValid() )
177  return Container->isDefined(ky);
178  }
179 
180  //
181  // Returns the number of user defined mappings
182  //
183  uInt ndefined() const {
184  if (! isValid() )
186  return Container->ndefined();
187  }
188 
189  //
190  // Returns the container on which this iterator is
191  // operating.
192  //
193  const HashMap<key,val> &container() const {
194  if ( !isValid() )
196  return *Container;
197  }
198 
199  // dtor
200  virtual ~ConstHashMapIter();
201 
202 protected:
203 
204  void step();
205 
210 };
211 
212 
213 // <summary>
214 // Step through a non-const HashMap
215 // </summary>
216 // <use visibility=export>
217 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
218 //
219 // <synopsis>
220 // This class is an iterator, and it used to step through non-const
221 // <linkto class=HashMap><src>HashMap</src></linkto>s. This is useful
222 // when one wishes to find each of the user defined mappings in a
223 // particular map.
224 // </synopsis>
225 //
226 // <example>
227 // <srcblock>
228 // #include <aips/Containers/HashMap.h>
229 // #include <casacore/casa/BasicSL/String.h>
230 // #include <iostream>
231 //
232 // main() {
233 // HashMap<String,Int> hash;
234 //
235 // hash.define("one",1);
236 // hash.define("two",2);
237 // hash.define("three",3);
238 // hash.define("four",4);
239 // hash.define("five",5);
240 // hash.define("six",6);
241 //
242 // HashMapIter<String,Int> iter(hash);
243 // for ( iter.toStart(); ! iter.atEnd(); iter++ )
244 // cout << iter.getVal() << ": " << iter.getKey() << endl;
245 // }
246 // </srcblock>
247 // </example>
248 //
249 // <motivation>
250 // Same as <linkto class=ConstHashMapIter><src>ConstHashMapIter</src></linkto>,
251 // but allows for modification of the underlying structure.
252 // </motivation>
253 //
254 template<class key, class val> class HashMapIter : public ConstHashMapIter<key,val> {
255 public:
256  //
257  // Get the key or value for the current position in
258  // the Map.
259  //
260  // <group>
261  val &getVal();
262 
263  virtual const val &getVal() const;
264  // </group>
265 
266  //
267  // These functions allow for the definition and removal of key/value
268  // relations. The "define(key &, value &)" function defines a key/value
269  // relation, and "remove(key &)" function removes a relation if it has
270  // been previously defined.
271  //
272  // <group>
273  val &define(const key &k, const val &v) {
274  if (!this->isValid())
276  return(this->Container->define(k,v));
277  }
278  void remove(const key &k) {
279  if (!this->isValid())
281  this->Container->remove(k);
282  }
283  // </group>
284 
285  //
286  // This returns the default value for the map that this iterator
287  // is tracking. With a non-const iterator the default value can
288  // be changed.
289  //
290  // <group>
291  const val &defaultVal() const {
293  }
294 
295  val &defaultVal() {
296  if (!this->isValid())
298  return this->Container->defaultVal();
299  }
300  // </group>
301 
302  //
303  // Clear all of the mappings.
304  //
305  void clear() {
306  if (!this->isValid())
308  this->Container->clear();
309  }
310 
311  //
312  // Allows mapping functions to be performed with the
313  // map on which this iterator operates. If this iterator
314  // is invalid, then an exception will be thrown. With
315  // a non-const operator, the value can be changed.
316  //
317  // <group>
318  const val &operator()(const key &ky) const {
320  }
321 
322  val &operator()(const key &ky) {
323  if (!this->isValid())
325  return(this->Container->operator()(ky));
326  }
327  // </group>
328 
329  //
330  // This allows a MapIter to be constructed from a Map. When
331  // created the new MapIter maintains a reference to the original
332  // Map. If the Map to which this MapIter points is deleted, then
333  // the MapIter is marked as invalid.
334  //
336 
337  //
338  // This allows a MapIter to be constructed from another MapIter.
339  // When created the new MapIter maintains a reference to the Map
340  // which the MapIter parameter tracked. If this Map is deleted, then
341  // this MapIter is marked as invalid.
342  //
343  HashMapIter(const HashMapIter<key,val> &other) : ConstHashMapIter<key,val>(other) {}
344 
345  //
346  // Default constructor creates an invalid Map iterator.
347  //
348  HashMapIter() : ConstHashMapIter<key,val>() {}
349 
350 
351  //
352  // This assignment operator allows the Map which this MapIter tracks
353  // to be changed. After a call to this operator, the MapIter will track
354  // the Map parameter.
355  //
357 
358  //
359  // This assignment operator allows the Map which this MapIter tracks
360  // to be changed. After a call to this operator, this MapIter will track
361  // the Map which the MapIter parameter tracks, i.e. it will contain a
362  // reference to this new Map.
363  //
364  virtual HashMapIter<key,val> &operator=(const HashMapIter<key,val> &other);
365 
366  //
367  // Returns the container on which this iterator is
368  // operating.
369  //
370  // <group>
372  if (!this->isValid())
374  return(*this->Container);
375  }
376  const HashMap<key,val> &container() const {
377  if (!this->isValid())
379  return(*this->Container);
380  }
381  // </group>
382 
383  // dtor
384  ~HashMapIter();
385 
386 protected:
387  //*display 4
388  //
389  // These assignment operators are private and ONLY throw an
390  // exception to prevent incorrect assignments to a non-const
391  // iterator.
392  //
393  // <group>
396  return *this;}
399  return *this;}
400  // </group>
401 
402 };
403 
404 } //#End casa namespace
405 
406 #ifndef CASACORE_NO_AUTO_TEMPLATES
407 #include <casacore/casa/Containers/HashMapIter.tcc>
408 #endif //# CASACORE_NO_AUTO_TEMPLATES
409 #endif
ConstHashMapIter< key, val > & operator=(const HashMap< key, val > &)
Assign one map iterator to a map (with reference semantics).
Definition: HashMapIter.h:394
uInt ndefined() const
Returns the number of user defined mappings.
Definition: HashMapIter.h:183
const val & operator()(const key &ky) const
Allows mapping functions to be performed with the map on which this iterator operates.
Definition: HashMapIter.h:318
const val & getVal() const
void toStart()
Move the iterator to the start of the Map.
void throw_hashmapiter_init_error()
HashMap< key, val > & container()
Returns the container on which this iterator is operating.
Definition: HashMapIter.h:371
HashMapIter()
Default constructor creates an invalid Map iterator.
Definition: HashMapIter.h:348
void operator++()
Advance to the next element of the Map.
Definition: HashMapIter.h:94
HashMapIter(HashMap< key, val > &st)
This allows a MapIter to be constructed from a Map.
Definition: HashMapIter.h:335
const val & defaultVal() const
Returns the default value for the Map on which this iterator is operating if it is a valid iterator...
Definition: HashMapIter.h:152
virtual ConstHashMapIter< key, val > & operator=(const HashMap< key, val > &other)
Assign one map iterator to a map (with reference semantics).
Bool atEnd() const
Check to see if the iterator position is at the end or beginning of the Map.
Definition: HashMapIter.h:112
ConstHashMapIter< key, val > & operator=(const ConstHashMapIter< key, val > &)
Assign one map iterator to another iterator (with reference semantics).
Definition: HashMapIter.h:397
HashMapIter(const HashMapIter< key, val > &other)
This allows a MapIter to be constructed from another MapIter.
Definition: HashMapIter.h:343
val & operator()(const key &ky)
Definition: HashMapIter.h:322
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
const HashMap< key, val > & container() const
Definition: HashMapIter.h:376
const val & defaultVal() const
This returns the default value for the map that this iterator is tracking.
Definition: HashMapIter.h:291
Bool isValid() const
Check to see if the iterator is in a valid state.
Definition: HashMapIter.h:119
const Bool False
Definition: aipstype.h:41
void clear()
Clear all of the mappings.
Definition: HashMapIter.h:305
virtual ~ConstHashMapIter()
dtor
void throw_invalid_hashmapiter_error()
ConstHashMapIter()
Default constructor creates an invalid Map iterator.
Definition: HashMapIter.h:144
ListIter< OrderedPair< key, val > > iter
Definition: HashMapIter.h:206
Doubly linked non-constant list iterator The List class above only provides for the list framework...
Definition: List.h:50
Bool isDefined(const key &ky) const
Allows one to check to see if a given key is defined in the map which this iterator tracks...
Definition: HashMapIter.h:174
const val & operator()(const key &ky) const
Allows mapping functions to be performed with the map on which this iterator operates.
Definition: HashMapIter.h:163
const HashMap< key, val > & container() const
Returns the container on which this iterator is operating.
Definition: HashMapIter.h:193
val & define(const key &k, const val &v)
These functions allow for the definition and removal of key/value relations.
Definition: HashMapIter.h:273
const Bool True
Definition: aipstype.h:40
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const key & getKey() const
Get the key or value for the current position in the Map.
HashMap< key, val > * Container
Definition: HashMapIter.h:207
Step through a non-const HashMap.
Definition: HashMapIter.h:254
unsigned int uInt
Definition: aipstype.h:48
Associative Array with a hash table implementation.
Definition: HashMap.h:297