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