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