casacore
Loading...
Searching...
No Matches
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#include <mutex>
42
43namespace 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.
50class UMaps {
51public:
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
65private:
66 void init();
67};
68
69
70
71//* Constants
72// IAU definition of Gaussian grav. constant for calculating IAU units
73const 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.
76const 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
212class UnitMap {
213public:
214 friend class UMaps;
215
216 //# Constructors
217// Default constructor of maps
219
220// Destructor
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);
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
String: the storage and methods of handling collections of characters.
Definition String.h:225
Define a struct containing the static data members.
Definition UnitMap.h:50
map< String, UnitName > mapPref
Decimal prefix list.
Definition UnitMap.h:54
Bool doneFITS
FITS unit list inclusion.
Definition UnitMap.h:64
map< String, UnitName > mapDef
Defining SI unit list.
Definition UnitMap.h:56
map< String, UnitName > mapCust
Customary list.
Definition UnitMap.h:60
map< String, UnitName > mapUser
User defined unit list.
Definition UnitMap.h:62
map< String, UnitName > mapSI
SI unit list.
Definition UnitMap.h:58
~UnitMap()
Destructor.
static void initUMSI1(UMaps &)
static void initUMSI2(UMaps &)
static void listCache(ostream &os)
List all units in cache.
static const map< String, UnitVal > & giveCache()
static void list()
static const String & getStringFITS(uInt which)
Get the belonging unit to a FITS unit.
static void putUser(const String &s, const UnitVal &val)
Define a user defined standard unit.
UnitMap(const UnitMap &other)
Copy constructor (not implemented)
static const map< String, UnitName > & givePref()
Return the different maps.
static const map< String, UnitName > & giveCust()
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 void listPref(ostream &os)
List all prefixes.
static Unit toFITS(const Unit &un)
Translate to a FITS unit.
UnitMap & operator=(const UnitMap &other)
Copy assignment (not implemented)
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 void initUM()
static Unit fromFITS(const Unit &un)
Translate a FITS unit to the proper units.
static void listUser(ostream &os)
List all user defined units.
static UMaps & getMaps()
Get the static UMaps struct.
UnitMap()
Default constructor of maps.
static const map< String, UnitName > & giveDef()
static Bool getCache(const String &s, UnitVal &val)
Get a cached definition.
static void initUMCust1(UMaps &)
static void initUMCust2(UMaps &)
static void putUser(const String &s, const UnitVal &val, const String &name)
static void listPref()
static void listDef(ostream &os)
List all defining units.
static void listUser()
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 putUser(const UnitName &name)
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 const map< String, UnitName > & giveSI()
static void clearCache()
Clear out the cache.
static void addFITS()
Define FITS related unit names.
static map< String, UnitVal > & getMapCache()
Get the static mapCache object.
static std::mutex fitsMutex
Definition UnitMap.h:336
static void initUMCust3(UMaps &)
static const map< String, UnitName > & giveUser()
static void removeUser(const UnitName &name)
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:73
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:76
double Double
Definition aipstype.h:55