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