casacore
UnitMap.h
Go to the documentation of this file.
1 //# UnitMap.h: defines the UnitMap class containing standard unit definitions
2 //# Copyright (C) 1994-2002,2007
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_UNITMAP_H
29 #define CASA_UNITMAP_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/BasicSL/Constants.h>
35 #include <casacore/casa/stdmap.h>
36 #include <casacore/casa/BasicSL/String.h>
37 #include <casacore/casa/Quanta/UnitDim.h>
38 #include <casacore/casa/Quanta/UnitVal.h>
39 #include <casacore/casa/Quanta/UnitName.h>
40 
41 namespace casacore { //# NAMESPACE CASACORE - BEGIN
42 
43 //# Forward Declarations
44 
45 //* Constants
46 // <note role=warning>
47 // SUN compiler does not accept non-simple default arguments
48 // </note>
49 // IAU definition of Gaussian grav. constant for calculating IAU units
50 const Double IAU_k=0.01720209895;
51 // Number of FITS units recognised (change the FITSstring and FITSunit lists
52 // in the UnitMap.cc when changing this number.
53 const uInt N_FITS = 19;
54 
55 // <summary>
56 // contains all simple known physical units
57 // </summary>
58 
59 // <use visibility=export>
60 
61 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tUnit">
62 //
63 // <prerequisite>
64 // You should have at least a preliminary understanding of these classes:
65 // <li> <linkto class=Unit>Unit</linkto>
66 // </prerequisite>
67 //
68 // <etymology>
69 // Based on Units and the Casacore container classes called 'Map'
70 // </etymology>
71 //
72 // <synopsis>
73 // Physical units are strings consisting of one or more names of known
74 // basic units, separated by '.' or ' ' (for multiplication) or '/' (for
75 // division). Each name can optionally be preceded by a standard decimal
76 // prefix, and/or followed by an (optionally signed) exponent.
77 // Example:
78 // km/s/(Mpc.s)2 is identical to km.s-1.Mpc-2.s-2
79 //
80 // See the <linkto class="Unit">Unit</linkto> class for more details.
81 //
82 // The UnitMap class contains the known standard basic units, and any
83 // other basic unit defined by the user of the Unit related classes.
84 // The known units are divided into 5 different groups:
85 // <ol>
86 // <li> Defining units: m, kg, s, A, K, cd, mol, rad, sr, _
87 // <li> SI units: including a.o. Jy, AU etc)
88 // <li> Customary units: e.g. lb, hp, ly etc
89 // <li> User defined units: defined by user (e.g. Beam, KPH, KM)
90 // <li> Cached units: cached unit strings for speed in operations
91 // </ol>
92 // The full list of known units can be viewed by running the tUnit test
93 // program.
94 // <note role=caution>
95 // There is a difference between units without a dimension (non-dimensioned
96 // I will call them), and undimensioned units. Non-dimensioned examples are
97 // "", "%"; undimensioned examples: "beam", "pixel".
98 // </note>
99 //
100 // Information about the contents of the unit maps can be obtained by
101 // the Bool functions (False if not present):
102 // <ul>
103 // <li> UnitMap::getPref("string", UnitName &) prefix
104 // <li> UnitMap::getUnit("string", UnitName &) search user,
105 // customary, SI (in that order)
106 // <li> UnitMap::getCache("string", UnitVal &) search cache
107 // </ul>
108 //
109 // The standard units can be viewed by the following commands, which
110 // output to cout:
111 // <ul>
112 // <li> UnitMap::list() all prefixes and SI, Cust and User units
113 // <li> UnitMap::listCache() current cache contents
114 // <li> UnitMap::listPref() all prefixes
115 // <li> UnitMap::listDef() all defining units
116 // <li> UnitMap::listSI() all SI Units
117 // <li> UnitMap::listCust() all customary units
118 // <li> UnitMap::listUser() all user defined units
119 // </ul>
120 //
121 // Units can be defined in the user list by:
122 // <note role=tip> The cache will be cleared if a user defined unit is overwritten,
123 // to make sure no old value will be used. </note>
124 // <srcblock>
125 // UnitMap::putUser("tag", UnitVal(factor,"unit"), "full name (optional)");
126 // or:
127 // UnitMap::putUser(UnitName);
128 // </srcblock>
129 // <note role=caution>
130 // If using an explicit Unit variable (e.g. <src>Unit a("5Bolton/beam")</src>),
131 // the check on the legality of the given string, and the conversion to the
132 // cached canonical value in the variable 'a', is only done at creation time. This
133 // means that if the user changes the value of a unit involved by the
134 // <linkto class=UnitMap>putUser()</linkto> method, the unit using it should be
135 // re-created (<src> a = Unit("5Bolton/beam");</src>).
136 // </note>
137 // A special set of 'units' used in FITS datasets can be added by the command
138 // <srcblock>
139 // UnitMap::addFITS();
140 // </srcblock>
141 // This set can be cleared from the user table by:
142 // <srcblock>
143 // UnitMap::clearFITS();
144 // </srcblock>
145 // Note that Unitmap keeps track of the inclusion of the FITS inclusion,
146 // making multiple calls inexpensive. The list of current FITS units can
147 // be viewed by running the tUnit program, or looking at the FITSunit
148 // table.
149 //
150 // Once the UnitMap::addFITS() has been run, the FITS units can be used as
151 // any other unit. In addition, a FITS unit can be translated to standard
152 // SI units by a call to <em>Unit UnitMap::fromFITS(const Unit)</em>. Any
153 // unit that is defined as a standard FITS unit will be translated. Unknown
154 // ones will not be translated, making the way clear for having standard
155 // units in a FITS units string. A comparable <em>toFITS()</em> translates in
156 // the same way in the reversed direction.
157 //
158 // The cache can be cleared by:
159 // <srcblock>
160 // UnitMap::clearCache();
161 // </srcblock>
162 // </synopsis>
163 //
164 // <example>
165 // Check for legal prefix:
166 // <srcblock>
167 // UnitName myUnit;
168 // if (UnitMap::getPref("k", myUnit)) { cout << "k has value " << myUnit;}
169 // </srcblock>
170 // Define a value for the unit 'beam':
171 // <srcblock>
172 // UnitMap::putUser("beam",UnitVal(C::pi * 0.1, "\"_2"),"telescope beam");
173 // </srcblock>
174 // List current cache:
175 // <srcblock>
176 // UnitMap::listCache();
177 // </srcblock>
178 // </example>
179 //
180 // <motivation>
181 // Standard list available to try to enhance use of SI and related units
182 // </motivation>
183 //
184 // <todo asof="941110">
185 // <li> Some inlining (did not work first go)
186 // </todo>
187 
188 class UnitMap {
189 public:
190 
191 //# Constructors
192 // Default constructor of maps
193  UnitMap();
194 
195 // Destructor
196  ~UnitMap();
197 
198 //# General member functions
199  // Remove all maps (just to get no memory leaks at end of program)
200  static void releaseUM();
201  // Check if a unit name is known, and return its value if True
202  // <group name="find">
203  // Get a prefix definition from key
204  static Bool getPref(const String &s, UnitName &name);
205 
206  // Get a cached definition
207  static Bool getCache(const String &s, UnitVal &val);
208 
209  // Get a standard unit definition (search order: User, Customary, SI)
210  static Bool getUnit(const String &s, UnitName &name);
211  // </group>
212  // Save a definition of a full unit name in the cache (the cache will be
213  // cleared if getting too large (200 entries)
214  static void putCache(const String &s, const UnitVal &val);
215 
216  // Define a user defined standard unit. If the unit is being redefined, and it
217  // has already been used in a user's <src>Unit</src> variable, the value
218  // cached in that variable will not change.
219  // <group name="define">
220  static void putUser(const String &s, const UnitVal &val);
221  static void putUser(const String &s, const UnitVal &val,
222  const String &name);
223  static void putUser(const UnitName &name);
224  // </group>
225 // Remove a user unit
226 // <group>
227  static void removeUser(const String &name);
228  static void removeUser(const UnitName &name);
229 // </group>
230 
231 // Clear out the cache
232  static void clearCache();
233 
234 // Define FITS related unit names
235  static void addFITS();
236 
237 // Clear FITS related units from user list
238  static void clearFITS();
239 
240 // Translate a FITS unit to the proper units. Note that this is a translation
241 // of the string only, no conversion. Unknown FITS units are not translated.
242 // Hence any new definition of the FITS units will work ok
243  static Unit fromFITS(const Unit &un);
244 
245 // Translate to a FITS unit
246  static Unit toFITS(const Unit &un);
247 
248 // List some part of the standard unit lists on cout or stream
249 // <group name="list">
250 // List all known unit symbols
251 // <group>
252  static void list(ostream &os);
253  static void list();
254  // </group>
255 
256 // List all units in cache
257  // <group>
258  static void listCache(ostream &os);
259  static void listCache();
260  // </group>
261 
262 // List all prefixes
263  // <group>
264  static void listPref(ostream &os);
265  static void listPref();
266  // </group>
267 
268 // List all defining units
269  // <group>
270  static void listDef(ostream &os);
271  static void listDef();
272  // </group>
273 
274 // List all SI units
275  // <group>
276  static void listSI(ostream &os);
277  static void listSI();
278  // </group>
279 
280 // List all customary units
281  // <group>
282  static void listCust(ostream &os);
283  static void listCust();
284  // </group>
285 
286 // List all user defined units
287  // <group>
288  static void listUser(ostream &os);
289  static void listUser();
290  // </group>
291 // </group>
292 
293  // Return the different maps
294  // <group>
295  static const map<String, UnitName> &givePref();
296  static const map<String, UnitName> &giveDef();
297  static const map<String, UnitName> &giveSI();
298  static const map<String, UnitName> &giveCust();
299  static const map<String, UnitName> &giveUser();
300  static const map<String, UnitVal> &giveCache();
301  // </group>
302 
303  private:
304  //# Constructors
305  // Copy constructor (not implemented)
306  UnitMap(const UnitMap &other);
307 
308  //# Operators
309  // Copy assignment (not implemented)
310  UnitMap &operator=(const UnitMap &other);
311 
312  //# Data members
313 
314  // Decimal prefix list
315  static map<String, UnitName> *mapPref;
316 
317  // Defining SI unit list
318  static map<String, UnitName> *mapDef;
319 
320  // SI unit list
321  static map<String, UnitName> *mapSI;
322 
323  // Customary list
324  static map<String, UnitName> *mapCust;
325 
326  // User defined unit list
327  static map<String, UnitName> *mapUser;
328 
329  // Cached list
330  static map<String, UnitVal> *mapCache;
331  // FITS unit list inclusion
332  static Bool doneFITS;
333 
334  //# member functions
335  // Get the name of a FITS unit
336  static Bool getNameFITS(UnitName *&name, uInt which);
337  // Get the belonging unit to a FITS unit
338  static const String &getStringFITS(uInt which);
339  // Initialise the static map
340  static void initUM();
341  // Bits and pieces of initUM() to get compilation speed improved
342  // <group>
343  static void initUMPrefix();
344  static void initUMSI1();
345  static void initUMSI2();
346  static void initUMCust1();
347  static void initUMCust2();
348  static void initUMCust3();
349  // </group>
350 
351 };
352 
353 //# Inline Implementations
354 
355 
356 } //# NAMESPACE CASACORE - END
357 
358 #endif
const uInt N_FITS
Number of FITS units recognised (change the FITSstring and FITSunit lists in the UnitMap.cc when changing this number.
Definition: UnitMap.h:53
static void listSI()
static void initUMPrefix()
Bits and pieces of initUM() to get compilation speed improved.
static void putCache(const String &s, const UnitVal &val)
Save a definition of a full unit name in the cache (the cache will be cleared if getting too large (2...
static void addFITS()
Define FITS related unit names.
static void listUser()
static const map< String, UnitName > & giveDef()
static void listCache()
static Unit fromFITS(const Unit &un)
Translate a FITS unit to the proper units.
static map< String, UnitName > * mapDef
Defining SI unit list.
Definition: UnitMap.h:318
static const String & getStringFITS(uInt which)
Get the belonging unit to a FITS unit.
static void initUMSI2()
static const map< String, UnitName > & givePref()
Return the different maps.
describes any valid unit as a factor and a dimenion of SI units
Definition: UnitVal.h:166
static void clearCache()
Clear out the cache.
const Double IAU_k
Definition: UnitMap.h:50
static map< String, UnitName > * mapSI
SI unit list.
Definition: UnitMap.h:321
static map< String, UnitName > * mapUser
User defined unit list.
Definition: UnitMap.h:327
static void putUser(const String &s, const UnitVal &val)
Define a user defined standard unit.
static map< String, UnitName > * mapCust
Customary list.
Definition: UnitMap.h:324
static void initUMCust3()
handles physical units
Definition: UnitName.h:129
UnitMap & operator=(const UnitMap &other)
Copy assignment (not implemented)
contains all simple known physical units
Definition: UnitMap.h:188
static void initUMCust2()
defines physical units
Definition: Unit.h:189
static void listPref()
static void initUM()
Initialise the static map.
static void initUMSI1()
static void releaseUM()
Remove all maps (just to get no memory leaks at end of program)
static const map< String, UnitVal > & giveCache()
double Double
Definition: aipstype.h:52
static void initUMCust1()
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
static const map< String, UnitName > & giveUser()
static const map< String, UnitName > & giveCust()
static void removeUser(const String &name)
Remove a user unit.
static Bool getPref(const String &s, UnitName &name)
Check if a unit name is known, and return its value if True.
static Bool getNameFITS(UnitName *&name, uInt which)
Get the name of a FITS unit.
static Bool getUnit(const String &s, UnitName &name)
Get a standard unit definition (search order: User, Customary, SI)
static void listDef()
static void listCust()
static void list()
String: the storage and methods of handling collections of characters.
Definition: String.h:223
~UnitMap()
Destructor.
static map< String, UnitName > * mapPref
Decimal prefix list.
Definition: UnitMap.h:315
static map< String, UnitVal > * mapCache
Cached list.
Definition: UnitMap.h:330
static Bool getCache(const String &s, UnitVal &val)
Get a cached definition.
static Unit toFITS(const Unit &un)
Translate to a FITS unit.
static Bool doneFITS
FITS unit list inclusion.
Definition: UnitMap.h:332
static const map< String, UnitName > & giveSI()
static void clearFITS()
Clear FITS related units from user list.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:48
UnitMap()
Default constructor of maps.