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