casacore
SimOrdMap.h
Go to the documentation of this file.
1 //# SimOrdMap.h: Simple map with ordered keys
2 //# Copyright (C) 1993,1994,1995,1996,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_SIMORDMAP_H
29 #define CASA_SIMORDMAP_H
30 
31 #ifndef AIPS_USE_DEPRECATED
32 #error "SimOrdMap.h is deprecated; use -DBUILD_DEPRECATED=ON to use it"
33 #endif
34 
35 #include <casacore/casa/aips.h>
36 #include <casacore/casa/Containers/OrderedPair.h>
37 #include <casacore/casa/Containers/Block.h>
38 #include <casacore/casa/BasicSL/String.h>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Define a macro to cast kvblk[i] to OrderedPair<K,V>*.
43 //# This is needed because the compiler outlines the inline functions pair.
44 #define KVBLKpair(INX) ((OrderedPair<K,V>*)(kvblk[INX]))
45 
46 // <category lib=aips sect="Containers">
47 // <summary>Simple map with keys ordered</summary>
48 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
49 // </reviewed>
50 
51 // SimpleOrderedMap<key,value> is a template class.
52 // It is similar to OrderedMap<key,value>, but lacks its
53 // sophisticated iterator capability. Instead iteration can be
54 // done using the getKey and getVal function with a simple index.
55 // The function ndefined() gives the number of key,value pairs in the map.
56 //
57 // It uses a Block to store an array of pointers to the keys and
58 // the associated values.
59 // The keys and values themselves are stored on the heap.
60 // The keys are kept in order to allow a binary search through
61 // the keys for rapid access.
62 //
63 // This is one (simple) implementation of an ordered map.
64 // It is not suitable for large arrays of keys, since the overhead
65 // of keeping the keys in order would get too big.
66 //
67 // Exceptions are raised when new[] is failing or when the next()
68 // getKey() or getValue() function is failing.
69 //
70 // The AipsIO >> and << operators are defined in <aips/SimOrdMapIO.h>.
71 
72 
73 template<class K, class V> class SimpleOrderedMap
74 {
75 public:
76 
77  // Creates a map with the specified default value, "value", and the
78  // internal block size.
79  SimpleOrderedMap (const V& defaultValue, uInt size);
80 
81  // Creates a map with the specified default value, "value".
82  explicit SimpleOrderedMap (const V& defaultValue);
83 
84  // Creates a map from another one; use copy semantics.
86 
87  // Removes a map.
89 
90  // Assigns this SimpleOrderedMap to another with copy semantics.
92 
93  // Defines a mapping (ie. create a key value mapping)
94  // The value is replaced if the key already exists.
95  V &define (const K&, const V&);
96 
97  // This is the mapping function which maps keys to values. If the
98  // map from the key to a value is not defined, a mapping will be
99  // defined from the key to the default value (which is set from
100  // the constructor. The "isDefined()" member function can be used
101  // to check to see if a mapping is defined before using the
102  // "operator()()".
103  //
104  // <note> With a constant map in the case where the key is not
105  // defined, the mapping between key and default value is
106  // not created, but rather an exception is thrown.
107  // </note>
108  //+grp
109  V &operator()(const K &ky);
110  // <thrown>
111  // <li> indexError<K>
112  // </thrown>
113  const V &operator()(const K &ky) const;
114  //-grp
115 
116  // Returns the default value for the Map.
117  //+grp
118  V &defaultVal() {return DefaultVal;}
119  const V &defaultVal() const {return DefaultVal;}
120  //-grp
121 
122  // These functions check to see if a mapping is defined between
123  // the specified key and some value. If defined, a pointer to
124  // the value is returned, otherwise 0 is returned.
125  //+grp
126  V *isDefined(const K&);
127  const V *isDefined(const K& k) const
128  { return ((SimpleOrderedMap<K,V>*)this)->isDefined(k); }
129  //-grp
130 
131  // Get the number of elements in the map.
132  uInt ndefined() const { return nrused; }
133 
134  // Get the i-th key in the map.
135  // It can be used to iterate through the keys as:
136  // <code>
137  // for (uInt i=0; i<map.ndefined(); i++) {
138  // cout << map.getKey(i) << " " << map.getVal(i) << endl;
139  // }
140  // </code>
141  // Index checking is only done if Block is doing it.
142  const K& getKey (uInt inx) const
143  { return KVBLKpair(inx)->x(); }
144 
145  // Get the i-th value in the map.
146  // It can be used to iterate through the keys as:
147  // <code>
148  // for (uInt i=0; i<map.ndefined(); i++) {
149  // cout << map.getKey(i) << " " << map.getVal(i) << endl;
150  // }
151  // </code>
152  // Index checking is only done if Block is doing it.
153  //+grp
154  const V& getVal (uInt inx) const
155  { return KVBLKpair(inx)->y(); }
156  V& getVal (uInt inx)
157  { return KVBLKpair(inx)->y(); }
158  //-grp
159 
160 
161  // Rename a key.
162  // If the new key already exists, the existing key will be removed.
163  // <thrown>
164  // <li> indexError<K>
165  // </thrown>
166  void rename (const K& newkey, const K& oldkey);
167 
168  // Undefines a mapping (ie. remove a key value mapping).
169  // <thrown>
170  // <li> indexError<K>
171  // </thrown>
172  void remove (const K&);
173 
174  // Clear the entire map (ie. remove all mappings).
175  void clear ();
176 
177  // Get the total size of the block in use.
178  uInt ntot() const { return kvblk.nelements(); }
179 
180  // Get or set the Block allocation increment.
181  //+grp
182  uInt incr() const { return nrincr; }
183  uInt incr(uInt nri) { return (nrincr = nri); }
184  //-grp
185 
186  // Check the internal state.
187  // <thrown>
188  // <li> AipsError
189  // </thrown>
190  Bool ok() const;
191 
192  // Version for major change (used by SimOrdMapIO).
193  // enum did not work properly with cfront 3.0.1), so replaced
194  // by a static inline function. Users won't normally use this.
195  //*display 8
196  static uInt Version() {return 1;}
197 
198 protected:
199  // The blocks to hold the keys and values
200  // and the total, used and increment size of these blocks.
205 
206  // Binary search for the key.
207  uInt findKey (const K&, Bool&) const;
208 
209  // Copy from another Block of OrderedPair's.
211 };
212 
213 
214 } //# NAMESPACE CASACORE - END
215 
216 #ifndef CASACORE_NO_AUTO_TEMPLATES
217 #include <casacore/casa/Containers/SimOrdMap.tcc>
218 #endif //# CASACORE_NO_AUTO_TEMPLATES
219 #endif
#define KVBLKpair(INX)
Definition: SimOrdMap.h:44
size_t nelements() const
The number of elements contained in this Block<T>.
Definition: Block.h:611
void clear()
Clear the entire map (ie.
V * isDefined(const K &)
These functions check to see if a mapping is defined between the specified key and some value.
const V * isDefined(const K &k) const
Definition: SimOrdMap.h:127
V & operator()(const K &ky)
This is the mapping function which maps keys to values.
Block< void * > kvblk
The blocks to hold the keys and values and the total, used and increment size of these blocks.
Definition: SimOrdMap.h:201
const K & getKey(uInt inx) const
Get the i-th key in the map.
Definition: SimOrdMap.h:142
uInt ntot() const
Get the total size of the block in use.
Definition: SimOrdMap.h:178
const V & defaultVal() const
Definition: SimOrdMap.h:119
V & define(const K &, const V &)
Defines a mapping (ie.
const V & getVal(uInt inx) const
Get the i-th value in the map.
Definition: SimOrdMap.h:154
uInt findKey(const K &, Bool &) const
Binary search for the key.
~SimpleOrderedMap()
Removes a map.
V & defaultVal()
Returns the default value for the Map.
Definition: SimOrdMap.h:118
SimpleOrderedMap(const V &defaultValue)
Creates a map with the specified default value, "value".
Bool ok() const
Check the internal state.
SimpleOrderedMap< K, V > & operator=(const SimpleOrderedMap< K, V > &)
Assigns this SimpleOrderedMap to another with copy semantics.
void copyBlock(const SimpleOrderedMap< K, V > &)
Copy from another Block of OrderedPair's.
SimpleOrderedMap(const V &defaultValue, uInt size)
Creates a map with the specified default value, "value", and the internal block size.
void rename(const K &newkey, const K &oldkey)
Rename a key.
static uInt Version()
Version for major change (used by SimOrdMapIO).
Definition: SimOrdMap.h:196
const V & operator()(const K &ky) const
uInt incr() const
Get or set the Block allocation increment.
Definition: SimOrdMap.h:182
uInt ndefined() const
Get the number of elements in the map.
Definition: SimOrdMap.h:132
void remove(const K &)
Undefines a mapping (ie.
SimpleOrderedMap(const SimpleOrderedMap< K, V > &)
Creates a map from another one; use copy semantics.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42