casacore
Loading...
Searching...
No Matches
UnitVal.h
Go to the documentation of this file.
1//# UnitVal.h: defines the class describing a unit as a value and a dimension
2//# Copyright (C) 1994-1999,2000,2001,2004
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: casa-feedback@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#ifndef CASA_UNITVAL_H
27#define CASA_UNITVAL_H
28
29
30//# Includes
31#include <casacore/casa/aips.h>
32#include <casacore/casa/Quanta/UnitDim.h>
33#include <casacore/casa/iosfwd.h>
34
35namespace casacore { //# NAMESPACE CASACORE - BEGIN
36
37//# Forward Declarations
38class String;
39class MUString;
40class UnitMap;
41class UMaps;
42
43//
44// <summary>
45// describes any valid unit as a factor and a dimenion of SI units
46// </summary>
47
48// <use visibility=export>
49
50// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tUnit">
51//
52// <prerequisite>
53// You should have at least a preliminary understanding of these classes:
54// <li> <linkto class=Unit>Unit</linkto>
55// </prerequisite>
56//
57// <etymology>
58// The class name derives from Units and gives a Value for a unit string
59// </etymology>
60//
61// <synopsis>
62// Physical units are strings consisting of one or more names of known
63// basic units, separated by '.' or ' ' (for multiplication) or '/' (for
64// division). Each name can optionally be preceded by a standard decimal
65// prefix, and/or followed by an (optionally signed) exponent.
66// Example:
67// km/s/(Mpc.s)2 is identical to km.s-1.Mpc-2.s-2
68//
69// See the <linkto class="Unit">Unit</linkto> class for more details.
70//
71// The UnitVal class maps a Unit string to a factor and a dimension of SI
72// defining units. E.g 'km/s' will be 1000 m.s-1 .
73// This class is only of interest if the manipulation of units is of
74// direct interest. Normally units will be used as Quantities and Quantums
75// (see the <linkto class=Quantum>Quantum</linkto> class) only,
76// i.e. as a physical quantity having a value and unit.
77// The class can also be used to check the validity of a unit string.
78//
79// <h3> Constructing UnitVal values </h3>
80//
81// UnitVal has the following constructors:
82// <ul>
83// <li> UnitVal() creates an (non-dimensioned) value 1.
84// <li> UnitVal(Double f) creates an (non-dimensioned) value f.
85// <li> UnitVal(Double f, String s) creates value f with unit s
86// <li> UnitVal(Double f, Int i) (private) creates value f with unit
87// at position i in dimension vector
88// </ul>
89//
90//
91// <h3> Manipulating unit values </h3>
92//
93// The UnitVal can be manipulated by the following operators and functions:
94// <ul>
95// <li> *, / generates combined UnitVal (e.g. 1 yd * 1 m = 0.9 m2)
96// <li> pow(Int) UnitVal(2,"km")->pow(2) = 4000000 m2
97// <li> root(Int) UnitVal(4000000,"m2")->root(2) = 2 km
98// <li> ==, != compares dimensions only: 1 yd == 5 ly: True
99// <li> getFac() will return the factor (Double)
100// <li> getDim() will return the dimensions (as UnitDim)
101// <li> << will output formatted unit (factor and dimension)
102// </ul>
103// To aid in checking the dimensionality of units, the following constants
104// are available:
105// <ul>
106// <li> UnitVal::NODIM
107// <li> UnitVal::UNDIM
108// <li> UnitVal::LENGTH
109// <li> UnitVal::MASS
110// <li> UnitVal::ANGLE
111// <li> UnitVal::SOLIDANGLE
112// <li> UnitVal::MOLAR
113// <li> UnitVal::CURRENT
114// <li> UnitVal::TIME
115// <li> UnitVal::TEMPERATURE
116// <li> UnitVal::INTENSITY
117// </ul>
118// <note role=tip>
119// Any other dimension can be checked by a combination. To check e.g. if
120// a unit is an acceleration, use: UnitVal::LENGTH/UnitVal::TIME/UnitVal::TIME
121// </note>
122//
123// <h3> Checking for valid unit strings </h3>
124//
125// The validity of a unit string can be checked by:
126// <srcblock>
127// // Check if the given String is a valid unit representation. The String
128// // will be cached in the unit maps for later reference if True
129// if ( UnitVal::check( "km/s/Mpc") ) {...}
130// </srcblock>
131//
132// </synopsis>
133//
134// <example>
135// An observation contains values in Janskys and in Westerbork Units. The
136// data can be combined by the following code:
137// <srcblock>
138// // The Fits tape gave JY, we check if defined, else we define them
139// if ( !UnitVal::check( "JY")) {
140// UnitMap::putUser("JY", UnitVal(1.,"Jy"), "FITS way to write Jy");
141// }
142// // The Fits tape gave WU (which are defined):
143// // We check if JY and WU are of the same dimension:
144// if (UnitVal(1.,"JY") != UnitVal(1.,"WU")) {
145// cerr << "Wrong dimension for either JY ( " <<
146// UnitVal(1.,"JY")->getDim() <<
147// ") or WU ( " <<
148// UnitVal(1.,"WU")->getDim() << ")" << endl;
149// }
150// // And output the relation between WU and JY, and the WU value:
151// cout << "1 WU = " << ( UnitVal(1.,"WU")/UnitVal(1.,"Jy") )->getVal() <<
152// " JY with 1 WU = " << UnitVal(1.,"WU") << endl;
153// </srcblock>
154// </example>
155
156// <motivation>
157// To separate the actual manipulation of unit values from the related
158// quantity
159// </motivation>
160//
161// <todo asof="941110">
162// <li> Some inlining (did not work first go)
163// </todo>
164
165class UnitVal {
166 //# Friends
167 // Multiply
168 friend UnitVal operator*(const UnitVal &in, const UnitVal &other);
169 // Divide
170 friend UnitVal operator/(const UnitVal &in, const UnitVal &other);
171 // Output a unit as a value and a string of SI defining units
172 friend ostream& operator<<(ostream &os, const UnitVal &ku);
173 // ensure that statics are initialized
175
176 public:
177 //# Constructors
178 // Construct an non-dimensioned value of 1
180 // Copy constructor
181 UnitVal(const UnitVal &other);
182
183 // Construct an non-dimensioned value
184 UnitVal(Double factor) { init(factor); }
185
186 // Construct a fully dimensioned value
187 // <thrown>
188 // <li> AipsError
189 // </thrown>
190 UnitVal(Double factor, const String &s, UMaps* = 0);
191
192 // Construct a value with a single unit at position specified
193 UnitVal(Double factor, Int pos) { init(factor, pos); }
194
195 // Destructor
197
198 //# Operators
199 // Assignment (copy semantics)
200 UnitVal &operator=(const UnitVal &other);
201
202 // Manipulate units
203 // <group name="manipulate">
204 // Multiply different units
205 UnitVal &operator*=(const UnitVal &other);
207 // Divide different units
208 UnitVal &operator/=(const UnitVal &other);
209
210 // Compare the dimensionality of different units
211 Bool operator==(const UnitVal &other) const;
212 Bool operator!=(const UnitVal &other) const;
213 // </group>
214
215 //# General member functions
216
217 // Raise a unit to an integer power
219
220 // Take integer root
221 // <thrown>
222 // <li> AipsError if power equals zero
223 // <li> AipsError if unit dimensions not multiple of power
224 // </thrown>
225 // <group>
226 UnitVal root(Int p) const;
227 UnitVal sqrt() const;
228 // </group>
229
230 // Get the data parts of the unit value definition
231 // <group name="get data">
232 // Get the dimensions in the defining SI units
233 const UnitDim &getDim() const;
235 // Get the factor of the unit (as compared to pure SI units)
236 Double getFac() const;
237 // </group>
238
239 //# Helper functions
240 // Convert a unit string to a proper unit value and cache the result. The
241 // function will return False if invalid string specified
242 static Bool check(const String &s);
243
244 // Convert a unit string to a proper unit value, cache the result and compare
245 // the dimension with the specified unit value. False if any of the steps fails
246 static Bool check(const String &s, UnitVal &loc);
247
248
249 //# Data members
250 // Some constants to check type of units
251 // <group name="unit kinds">
252 static UnitVal NODIM;
255 static UnitVal MASS;
256 static UnitVal TIME;
263 // </group>
264
265 protected:
266 // alternate initialization
267 void init(Double factor);
268 void init(Double factor, Int pos);
269
270 private:
271 //# Data members
272 // The factor necessary to express the specified unit in the defining SI units
274
275 // The dimensions of the unit in the defining SI units
277
278 // Convert (and check) a unit string to an SI value representation
279 // <group>
280 static Bool create(const String &s, UnitVal &res, UMaps* = 0);
281 static Bool create(MUString &str, UnitVal &res, UMaps* = 0);
282 // </group>
283
284 // Determine sign of unit power (i.e. if '.' or '/')
285 static Int psign(MUString &str);
286
287 // Determine exponent of unit symbol
288 static Int power(MUString &str);
289
290 // Determine symbol name in unit string
291 static Bool field(MUString &str, UnitVal &res, UMaps*);
292
293};
294
295//# Inline Implementations
296
297//# Global functions
298// <summary> Global output function </summary>
299// <group name=output>
300// Output
301ostream& operator<<(ostream &os, const UnitVal &ku);
302// </group>
304// <summary> Static initialisation of UnitVal constants </summary>
305static class UnitVal_static_initializer {
306 public:
328} //# NAMESPACE CASACORE - END
329
330#endif
331
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:48
Static initialisation of UnitVal constants
Definition UnitVal.h:307
friend UnitVal operator/(const UnitVal &in, const UnitVal &other)
Divide.
UnitVal sqrt() const
void init(Double factor, Int pos)
static UnitVal ANGLE
Definition UnitVal.h:262
static UnitVal TEMPERATURE
Definition UnitVal.h:259
static UnitVal UNDIM
Definition UnitVal.h:254
void init(Double factor)
alternate initialization
static UnitVal TIME
Definition UnitVal.h:257
const UnitDim & getDim() const
Get the data parts of the unit value definition
UnitDim kindDim
The dimensions of the unit in the defining SI units.
Definition UnitVal.h:276
UnitVal(Double factor)
Construct an non-dimensioned value.
Definition UnitVal.h:184
static UnitVal NODIM
Some constants to check type of units
Definition UnitVal.h:253
UnitVal(Double factor, const String &s, UMaps *=0)
Construct a fully dimensioned value.
friend UnitVal operator*(const UnitVal &in, const UnitVal &other)
Multiply.
friend ostream & operator<<(ostream &os, const UnitVal &ku)
Output a unit as a value and a string of SI defining units.
static UnitVal CURRENT
Definition UnitVal.h:258
UnitVal pow(Int p)
Raise a unit to an integer power.
static UnitVal MASS
Definition UnitVal.h:256
static Int power(MUString &str)
Determine exponent of unit symbol.
UnitVal()
Construct an non-dimensioned value of 1.
static UnitVal INTENSITY
Definition UnitVal.h:260
static UnitVal SOLIDANGLE
Definition UnitVal.h:263
Double getFac() const
Get the factor of the unit (as compared to pure SI units)
static Int psign(MUString &str)
Determine sign of unit power (i.e.
~UnitVal()
Destructor.
UnitVal & operator=(const UnitVal &other)
Assignment (copy semantics)
Double kindFactor
The factor necessary to express the specified unit in the defining SI units.
Definition UnitVal.h:273
Bool operator==(const UnitVal &other) const
Compare the dimensionality of different units.
static UnitVal MOLAR
Definition UnitVal.h:261
UnitVal & operator*=(const UnitVal &other)
Manipulate units
static Bool create(MUString &str, UnitVal &res, UMaps *=0)
UnitVal(const UnitVal &other)
Copy constructor.
static Bool check(const String &s)
Convert a unit string to a proper unit value and cache the result.
Bool operator!=(const UnitVal &other) const
UnitVal & operator/=(const UnitVal &other)
Divide different units.
static Bool check(const String &s, UnitVal &loc)
Convert a unit string to a proper unit value, cache the result and compare the dimension with the spe...
UnitVal root(Int p) const
Take integer root.
UnitVal(Double factor, Int pos)
Construct a value with a single unit at position specified.
Definition UnitVal.h:193
static UnitVal LENGTH
Definition UnitVal.h:255
static Bool create(const String &s, UnitVal &res, UMaps *=0)
Convert (and check) a unit string to an SI value representation.
static Bool field(MUString &str, UnitVal &res, UMaps *)
Determine symbol name in unit string.
static class casacore::UnitVal_static_initializer unitval_static_initializer
this file contains all the compiler specific defines
Definition mainpage.dox:28
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
int Int
Definition aipstype.h:48
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
double Double
Definition aipstype.h:53
ostream & operator<<(ostream &os, const UnitVal &ku)
Output.