casacore
Map.h
Go to the documentation of this file.
1 //# Map.h: Associative array classes
2 //# Copyright (C) 1994,1995,1999,2000
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 
28 #ifndef CASA_MAP_H
29 #define CASA_MAP_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Exceptions/Error.h>
35 
36 //
37 // Work around bugs in SUN\'s stupid compiler
38 //
39 #define AIPS_STUPID_SUN 1
40 
41 namespace casacore { //#Begin casa namespace
42 
43 //# Forward Declarations
44 class AipsIO;
45 
46 extern void throw_mapiter_init_error();
47 extern void throw_map_init_error();
48 extern void throw_invalid_mapiter_error();
49 extern void throw_map_constop_error();
50 
51 template<class key, class value> class MapIterRep;
52 template<class key, class value> class ConstMapIter;
53 template<class key, class value> class Map;
54 
55 // <summary>Map representation class </summary>
56 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
57 // </reviewed>
58 
59 template<class key, class value> class MapRep {
60 public:
61 
62  //
63  // This is the only MapRep constructor. It takes as a parameter the
64  // default value for the map.
65  //
66  MapRep(const value &dflt) : DefaultVal(dflt) { }
67 
68  //
69  // This is the mapping function which maps keys to values. If the
70  // map from the key to a value is not defined, a mapping will be
71  // defined from the key to the default value (which is set from
72  // the constructor. The "isDefined()" member function can be used
73  // to check to see if a mapping is defined before using the
74  // "operator()()".
75  //
76  // <note> With a constant map in the case where the key is not
77  // defined, the mapping between key and default value is
78  // not created, but rather an exception is thrown.
79  // </note>
80  //+grp
81  value &operator()(const key &ky);
82  const value &operator()(const key &ky) const;
83  //-grp
84 
85  //
86  // Returns the default value for the Map.
87  //
88  //+grp
90  const value &defaultVal() const {return DefaultVal;}
91  //-grp
92 
93  //
94  // Returns a non-zero value if a mapping is defined for
95  // the key parameter.
96  //
97  //+grp
98  virtual const value *isDefined(const key &) const = 0;
99  virtual value *isDefined(const key &) = 0;
100  //-grp
101 
102  //
103  // Returns the number of user defined mappings
104  //
105  virtual uInt ndefined() const = 0;
106 
107  //
108  // These functions allow for the definition and removal of key/value
109  // relations. The "define(key &, value &)" call defines a key/value
110  // relation, and "remove(key &)" removes a relation if it has
111  // been previously defined.
112  //
113  //+grp
114  virtual value &define(const key &, const value &) = 0;
115  virtual void remove(const key &) = 0;
116  //-grp
117 
118  //
119  // Clear all of the mappings.
120  //
121  virtual void clear() = 0;
122 
123  virtual MapIterRep<key,value> *getRep(Map<key,value>*) const = 0;
124 
125  virtual MapRep<key,value> *Clone() const = 0;
126 
127  //
128  // Does nothing.
129  //
130  virtual ~MapRep();
131 
132  enum {MapRepVersion = 1};
133 
134 protected:
135 
136  // This is the default value which is return when no match is found.
137  // This prevents this class from being a PartialMap.
139 
140 };
141 
142 
143 //
144 // <category lib=aips sect="Containers">
145 // <summary>Abstract base class for associative arrays</summary>
146 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
147 // </reviewed>
148 //
149 // This is the abstract class for all "Map" classes which implement the
150 // equivalent of an associative array.
151 //
152 template<class key, class value> class Map
153 {
154 public:
155 
156  //
157  // This is the mapping function which maps keys to values. If the
158  // map from the key to a value is not defined, a mapping will be
159  // defined from the key to the default value (which is set from
160  // the constructor. The "isDefined()" member function can be used
161  // to check to see if a mapping is defined before using the
162  // "operator()()".
163  //
164  // <note> With a constant map in the case where the key is not
165  // defined, the mapping between key and default value is
166  // not created, but rather an exception is thrown.
167  // </note>
168  //+grp
169  value &operator()(const key &ky);
170  const value &operator()(const key &ky) const;
171  //-grp
172 
173 
174  //
175  // Returns the default value for the Map.
176  //
177  //+grp
178  value &defaultVal();
179  const value &defaultVal() const;
180  //-grp
181 
182  //
183  // Returns a non-zero value if a mapping is defined for
184  // the key parameter.
185  //
186  //+grp
187  const value *isDefined(const key &k) const;
188  value *isDefined(const key &k);
189  //-grp
190 
191  //
192  // Returns the number of user defined mappings
193  //
194  uInt ndefined() const;
195 
196  //
197  // These functions allow for the definition and removal of key/value
198  // relations. The "define(key &, value &)" call defines a key/value
199  // relation, and "remove(key &)" removes a relation if it has
200  // been previously defined.
201  //
202  //+grp
203  value &define(const key &k, const value &v);
204  void remove(const key &k);
205  //-grp
206 
207  //
208  // Clear all of the mappings.
209  //
210  void clear();
211 
212  //
213  // Returns the iterator rep appropriate for this particular Map
214  //
215  MapIterRep<key,value> *getRep() const;
216 
217  //
218  // This copy constructor will, for the moment, be the only
219  // way to create a map.
220  //
221  //+grp
222  Map(const Map<key,value> &m);
223  Map(const Map<key,value> *m);
224  //-grp
225 
228 
229  //*display 2
230  //
231  // Does nothing.
232  //
233  virtual ~Map();
234 
235  enum {MapVersion = 1};
236 
237 #if defined(AIPS_STUPID_SUN)
238  ConstMapIter<key,value> *getIter() const;
239 #endif
240 
241 protected:
242 
244 
245  //
246  // Used by derived classes
247  //
248  Map(MapRep<key,value> *nRep);
249 
250  //
251  // Used the set the representation.
252  // Always DELETES Rep if necessary.
253  //
255  if (Rep)
256  delete Rep;
257  Rep = st;
258  }
259 
260 };
261 
262 //
263 // <category lib=aips sect="Containers">
264 // <summary>Abstract base class for associative array iterators</summary>
265 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
266 // </reviewed>
267 //
268 // This is the abstract base class for all (Const)MapIter
269 // "letters". That is all Map specializations must provide
270 // a "IterRep" for the particular specialization which
271 // will allow the (Const)MapIter envelope to traverse the
272 // new type of map.
273 //
274 template<class key, class value> class MapIterRep {
275 public:
276 
277  //
278  // Check to see if the iterator is in a valid state.
279  //
280  virtual Bool isValid() const = 0;
281 
282  //
283  // Check to see if the iterator position is at the
284  // end or beginning of the Map.
285  //
286  //+grp
287  virtual Bool atEnd() const = 0;
288  virtual Bool atStart() const = 0;
289  //-grp
290 
291  //
292  // Move the iterator to the start of the Map.
293  //
294  virtual void toStart() = 0;
295 
296  //
297  // Advance to the next element of the Map.
298  //
299  //+grp
300  virtual void operator++() = 0;
301  virtual void operator++(int) = 0;
302  //-grp
303 
304  //
305  // Get the key for the current position in
306  // the Map.
307  //
308  virtual const key &getKey() const = 0;
309 
310  //
311  // Return the value at the current location of the map iterator.
312  // Should throw an exception if the iterator is "past the end of
313  // the Map" or if the iterator is invalid.
314  //
315  //+grp
316  virtual value &getVal() = 0;
317  virtual const value &getVal() const = 0;
318  //-grp
319 
320  //
321  // This returns the default value for the map that this iterator
322  // is tracking. With a non-const iterator the default value can
323  // be changed.
324  //
325  //+grp
326  const value &defaultVal() const;
327  value &defaultVal();
328  //-grp
329 
330  //
331  // These functions allow for the definition and removal of key/value
332  // relations. The "define(key &, value &)" function defines a key/value
333  // relation, and "remove(key &)" function removes a relation if it has
334  // been previously defined.
335  //
336  //+grp
337  value &define(const key &ky, const value &val);
338  void remove(const key &ky);
339  //-grp
340 
341  //
342  // Clear all of the mappings.
343  //
344  void clear();
345 
346 
347  //
348  // Allows mapping functions to be performed with the
349  // map on which this iterator operates. If this iterator
350  // is invalid, then an exception will be thrown. With
351  // a non-const operator, the value can be changed.
352  //
353  //+grp
354  const value &operator()(const key &ky) const;
355  value &operator()(const key &ky);
356  //-grp
357 
358  //
359  // Allows one to check to see if a given key is defined
360  // in the map which this iterator tracks. If this iterator
361  // is invalid, then an exception will be thrown. With
362  // a non-const iterator the returned pointer can be used
363  // to change the value in the map.
364  //
365  //+grp
366  const value *isDefined(const key &ky) const;
367  value *isDefined(const key &ky);
368  //-grp
369 
370  //
371  // Returns the number of user defined mappings
372  //
373  uInt ndefined() const;
374 
375  //
376  // Returns the container on which this iterator is
377  // operating.
378  //
379  //+grp
380  Map<key,value> &container();
381  const Map<key,value> &container() const;
382  //-grp
383 
384  //
385  // Duplicate a map iterator
386  //
387  //+grp
388  virtual MapIterRep<key,value> *Clone() = 0;
389  //-grp
390 
391  //
392  // This allows a MapIter to be constructed from a Map. When
393  // created the new MapIter maintains a reference to the original
394  // Map. If the Map to which this MapIter points is deleted, then
395  // the MapIter is marked as invalid.
396  //
397  //+grp
400  //-grp
401 
402  virtual ~MapIterRep();
403 
404  enum {MapIterRepVersion = 1};
405 
406 protected:
407 
409 
410 };
411 
412 //
413 // <category lib=aips sect="Containers">
414 // <summary>Const associative array iterator</summary>
415 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
416 // </reviewed>
417 //
418 // This class implements the mechanism for traversing constant
419 // associative arrays, i.e. "Map"s. This allows one to move
420 // the cursor to the beginning of the map and serially traverse
421 // the map. The key and value elements can be extracted at
422 // each position in the Map. For example:
423 // <code>
424 // template<class key,class value> void print(const Map<key,value> &xx){
425 // ConstMapIter<key,value> x(xx);
426 // x.toStart();
427 // while (!x.atEnd()) {
428 // cout << "(" << x.getKey() << "," << x.getVal() << ")" << " ";
429 // x++;
430 // }
431 // cout << endl;
432 // }
433 // </code>
434 // This example declares a templated function which accepts a const
435 // Map as a parameter, and iterates through the map displaying the
436 // key/value pairs at each positon.
437 //
438 template<class key, class value> class ConstMapIter
439 {
440 public:
441 
442  //
443  // Move the iterator to the start of the Map.
444  //
445  virtual void toStart();
446 
447  //
448  // Advance to the next element of the Map.
449  //
450  //+grp
451  virtual void operator++();
452  virtual void operator++(int);
453  //-grp
454 
455  //
456  // Get the key or value for the current position in
457  // the Map.
458  //
459  //+grp
460  virtual const key &getKey() const;
461  virtual const value &getVal() const;
462  //-grp
463 
464  //
465  // Check to see if the iterator position is at the
466  // end or beginning of the Map.
467  //
468  //+grp
469  virtual Bool atEnd() const;
470  virtual Bool atStart() const;
471  //-grp
472 
473  //
474  // Check to see if the iterator is in a valid state.
475  //
476  virtual Bool isValid() const;
477 
478  //
479  // Constructs a Map iterator from a Map (with reference semantics).
480  //
481  //+grp
482  ConstMapIter(const Map<key,value> *st);
483  ConstMapIter(const Map<key,value> &st);
484  //-grp
485 
486  //
487  // Assign one map iterator to a map (with reference semantics).
488  //
489  //+grp
490  virtual ConstMapIter<key,value> &operator=(const Map<key,value> &other);
491  virtual ConstMapIter<key,value> &operator=(const Map<key,value> *other);
492  //-grp
493 
494  //
495  // Constructs a Map iterator from another iterator (with reference semantics).
496  //
497  //+grp
500 
501  //-grp
502 
503  //
504  // Assign one map iterator to another iterator (with reference semantics).
505  //
506  //+grp
509  //-grp
510 
511  //
512  // Default constructor creates an invalid Map iterator.
513  //
514  ConstMapIter() : Rep(0) {}
515 
516 
517  //
518  // Returns the default value for the Map on which this
519  // iterator is operating if it is a valid iterator, otherwise
520  // it throws an exception.
521  //
522  const value &defaultVal() const;
523 
524  //
525  // Allows mapping functions to be performed with the
526  // map on which this iterator operates. If this iterator
527  // is invalid, then an exception will be thrown.
528  //
529  const value &operator()(const key &ky) const;
530 
531  //
532  // Allows one to check to see if a given key is defined
533  // in the map which this iterator tracks. If this iterator
534  // is invalid, then an exception will be thrown.
535  //
536  const value *isDefined(const key &ky) const;
537 
538  //
539  // Returns the number of user defined mappings
540  //
541  uInt ndefined() const;
542 
543  //
544  // Returns the container on which this iterator is
545  // operating.
546  //
547  const Map<key,value> &container() const;
548 
549  virtual ~ConstMapIter();
550 
551  enum {ConstMapIterVersion = 1};
552 
553 protected:
555 
556  //
557  // Dummy used to initialization by derived classes.
558  //
560 
561  //
562  // Always DELETES Rep if necessary
563  //
565  if (Rep)
566  delete Rep;
567  Rep = st;
568  }
569 
570 };
571 
572 
573 //#
574 //
575 // <category lib=aips sect="Containers">
576 // <summary>Associative array iterator</summary>
577 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
578 // </reviewed>
579 //
580 // This class implements the mechanism for traversing associative
581 // arrays, i.e. "Map"s. It provides the traversal mechanisms of the
582 // ConstMapIter, but adds the mechansims to modify the values, and
583 // perform other modification functions which the Maps provide, e.g.
584 // define().
585 //
586 template<class key, class value> class MapIter : virtual public ConstMapIter<key,value> {
587 public:
588 
589  //
590  // Return the value at the current location of the map iterator.
591  // Should throw an exception if the iterator is "past the end of
592  // the Map" or if the iterator is invalid.
593  //
594  //+grp
595  virtual value &getVal();
596 
597  virtual const value &getVal() const;
598  //-grp
599 
600  //
601  // These functions allow for the definition and removal of key/value
602  // relations. The "define(key &, value &)" function defines a key/value
603  // relation, and "remove(key &)" function removes a relation if it has
604  // been previously defined.
605  //
606  //+grp
607  value &define(const key &ky, const value &val) {
608  if (!this->isValid())
610  return(this->Rep->define(ky,val));
611  }
612  void remove(const key &ky) {
613  if (!this->isValid())
615  this->Rep->remove(ky);
616  }
617  //-grp
618 
619  //
620  // This returns the default value for the map that this iterator
621  // is tracking. With a non-const iterator the default value can
622  // be changed.
623  //
624  //+grp
625  const value &defaultVal() const {
627  }
628 
630  if (!this->isValid())
632  return this->Rep->defaultVal();
633  }
634  //-grp
635 
636  //
637  // Clear all of the mappings.
638  //
639  void clear() {
640  if (!this->isValid())
642  this->Rep->clear();
643  }
644 
645  //
646  // Allows mapping functions to be performed with the
647  // map on which this iterator operates. If this iterator
648  // is invalid, then an exception will be thrown. With
649  // a non-const operator, the value can be changed.
650  //
651  //+grp
652  const value &operator()(const key &ky) const {
654  }
655 
656  value &operator()(const key &ky) {
657  if (!this->isValid())
659  return(this->Rep->operator()(ky));
660  }
661  //-grp
662 
663  //
664  // Allows one to check to see if a given key is defined
665  // in the map which this iterator tracks. If this iterator
666  // is invalid, then an exception will be thrown. With
667  // a non-const iterator the returned pointer can be used
668  // to change the value in the map.
669  //
670  //+grp
671  const value *isDefined(const key &ky) const {
673  }
674 
675  value *isDefined(const key &ky) {
676  if (!this->isValid())
678  return(this->Rep->isDefined(ky));
679  }
680  //-grp
681 
682  //
683  // This allows a MapIter to be constructed from a Map. When
684  // created the new MapIter maintains a reference to the original
685  // Map. If the Map to which this MapIter points is deleted, then
686  // the MapIter is marked as invalid.
687  //
688  //+grp
690  ConstMapIter<key,value>(other ? other->getRep() : 0) {}
692  //-grp
693 
694  //
695  // This allows a MapIter to be constructed from another MapIter.
696  // When created the new MapIter maintains a reference to the Map
697  // which the MapIter parameter tracked. If this Map is deleted, then
698  // this MapIter is marked as invalid.
699  //
700  //+grp
701  MapIter(const MapIter<key,value> &other) :
702  ConstMapIter<key,value>(other.isValid() ? other.Rep->Clone() : 0) {}
703 
704  MapIter(const MapIter<key,value> *other) :
705  ConstMapIter<key,value>(other && (*other).isValid() ? other->Rep->Clone() : 0) {}
706  //-grp
707 
708  //
709  // Default constructor creates an invalid Map iterator.
710  //
711  MapIter() : ConstMapIter<key,value>() {}
712 
713 
714  //
715  // This assignment operator allows the Map which this MapIter tracks
716  // to be changed. After a call to this operator, the MapIter will track
717  // the Map parameter.
718  //
719  //+grp
721 
723  //-grp
724 
725  //
726  // This assignment operator allows the Map which this MapIter tracks
727  // to be changed. After a call to this operator, this MapIter will track
728  // the Map which the MapIter parameter trackes, i.e. it will contain a
729  // reference to this new Map.
730  //
731  //+grp
732  virtual MapIter<key,value> &operator=(const MapIter<key,value> &other);
733 
734  virtual MapIter<key,value> &operator=(const MapIter<key,value> *other);
735  //-grp
736 
737  //
738  // Returns the container on which this iterator is
739  // operating.
740  //
741  //+grp
743  return(this->Rep->container());}
744  const Map<key,value> &container() const {
746  //-grp
747 
748  ~MapIter() {}
749 
750  enum {MapIterVersion = 1};
751 
752 protected:
753  //*display 4
754  //
755  // These assignment operators are private and ONLY throw an
756  // exception to prevent incorrect assignments to a non-const
757  // iterator.
758  //
759  //+grp
762  return *this;}
765  return *this;}
768  return *this;}
771  return *this;}
772  //-grp
773 
774 };
775 
776 } //#End casa namespace
777 #ifndef CASACORE_NO_AUTO_TEMPLATES
778 #include <casacore/casa/Containers/Map.tcc>
779 #endif //# CASACORE_NO_AUTO_TEMPLATES
780 #endif
ConstMapIter(MapIterRep< key, value > *st)
Dummy used to initialization by derived classes.
Definition: Map.h:559
Abstract base class for associative array iterators.
Definition: Map.h:51
const value & operator()(const key &ky) const
Allows mapping functions to be performed with the map on which this iterator operates.
const Map< key, value > & container() const
Definition: Map.h:744
void throw_map_init_error()
virtual const value * isDefined(const key &) const =0
Returns a non-zero value if a mapping is defined for the key parameter.
MapRep(const value &dflt)
This is the only MapRep constructor.
Definition: Map.h:66
PtrHolder< T > & operator=(const PtrHolder< T > &other)
value & define(const key &ky, const value &val)
These functions allow for the definition and removal of key/value relations.
Definition: Map.h:607
void SetRep(MapRep< key, value > *st)
Used the set the representation.
Definition: Map.h:254
ConstMapIter< key, value > & operator=(const ConstMapIter< key, value > &)
Assign one map iterator to another iterator (with reference semantics).
Definition: Map.h:766
MapIter()
Default constructor creates an invalid Map iterator.
Definition: Map.h:711
value & defaultVal()
Returns the default value for the Map.
Definition: Map.h:89
ConstMapIter< key, value > & operator=(const Map< key, value > &)
Assign one map iterator to a map (with reference semantics).
Definition: Map.h:760
ConstMapIter()
Default constructor creates an invalid Map iterator.
Definition: Map.h:514
virtual uInt ndefined() const =0
Returns the number of user defined mappings.
const value * isDefined(const key &ky) const
Allows one to check to see if a given key is defined in the map which this iterator tracks...
MapIter(const MapIter< key, value > &other)
This allows a MapIter to be constructed from another MapIter.
Definition: Map.h:701
void throw_map_constop_error()
virtual MapRep< key, value > * Clone() const =0
void throw_invalid_mapiter_error()
value & operator()(const key &ky)
Definition: Map.h:656
value & defaultVal()
Definition: Map.h:629
value DefaultVal
This is the default value which is return when no match is found.
Definition: Map.h:138
MapIter(Map< key, value > *other)
This allows a MapIter to be constructed from a Map.
Definition: Map.h:689
virtual ~MapRep()
Does nothing.
value & operator()(const key &ky)
This is the mapping function which maps keys to values.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
MapIter(Map< key, value > &st)
Definition: Map.h:691
virtual value & define(const key &, const value &)=0
These functions allow for the definition and removal of key/value relations.
ConstMapIter< key, value > & operator=(const Map< key, value > *)
Definition: Map.h:763
Map< key, value > * Container
Definition: Map.h:408
MapIter(const MapIter< key, value > *other)
Definition: Map.h:704
Associative array iterator.
Definition: Map.h:586
ConstMapIter< key, value > & operator=(const ConstMapIter< key, value > *)
Definition: Map.h:769
Map< key, value > & container()
Returns the container on which this iterator is operating.
Definition: Map.h:742
MapRep< key, value > * Rep
Definition: Map.h:243
void clear()
Clear all of the mappings.
Definition: Map.h:639
const value & defaultVal() const
Returns the default value for the Map on which this iterator is operating if it is a valid iterator...
Map representation class.
Definition: Map.h:59
Abstract base class for associative arrays.
Definition: Map.h:53
void throw_mapiter_init_error()
Const associative array iterator.
Definition: Map.h:52
const value & operator()(const key &ky) const
Allows mapping functions to be performed with the map on which this iterator operates.
Definition: Map.h:652
MapIterRep< key, value > * Rep
Definition: Map.h:554
virtual MapIterRep< key, value > * getRep(Map< key, value > *) const =0
const value & defaultVal() const
This returns the default value for the map that this iterator is tracking.
Definition: Map.h:625
void SetRep(MapIterRep< key, value > *st)
Always DELETES Rep if necessary.
Definition: Map.h:564
value * isDefined(const key &ky)
Definition: Map.h:675
const value & defaultVal() const
Definition: Map.h:90
const value * 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: Map.h:671
this file contains all the compiler specific defines
Definition: mainpage.dox:28
virtual void clear()=0
Clear all of the mappings.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
unsigned int uInt
Definition: aipstype.h:48