casacore
Unit.h
Go to the documentation of this file.
1//# Unit.h: defines the Unit class
2//# Copyright (C) 1994-1996,1998-2000,2008
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_UNIT_H
29#define CASA_UNIT_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/casa/BasicSL/String.h>
35#include <casacore/casa/Quanta/UnitVal.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40
41// <summary>
42// defines physical units
43// </summary>
44
45// <use visibility=export>
46
47// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tUnit">
48// </reviewed>
49//
50//# // <prerequisite>
51//# // </prerequisite>
52//
53//# // <etymology>
54//# // </etymology>
55//
56// <synopsis>
57// Physical units are basically used as quantities (see the
58// <linkto class=Quantum>Quantum</linkto> class), i.e.
59// a value and a dimension. The Unit class, or one of its subsidaries, will
60// in general not be called separately. The only reason to make use of these
61// classes is to generate additional 'tagged' units, i.e. units with a
62// special name, e.g. 'beam' for a telescope beam, or 'JY', a non-SI name
63// for Jy.
64// <h3> Units </h3>
65// A Unit is a String, and can be defined as either a Unit or a String
66// everywhere where a Unit is required.<br>
67// If defined as a Unit, the format of the string will be checked for a
68// legal definition and its value will be stored. If defined as a String,
69// the checking and determination of the value will be done each time
70// the string is encountered when a Unit is expected.<br>
71// <note role=tip> The use of a separate Unit variable will give a tremendous
72// speed increase, if compared to using the String representation in
73// e.g. <linkto class=Quantum>Quantity(5,"deg")</linkto> </note>
74// <note role=caution>
75// If using an explicit Unit variable (e.g. <src>Unit a("5Bolton/beam")</src>),
76// the check on the legality of the given string, and the conversion to the
77// cached canonical value in the variable 'a', is only done at creation time. This
78// means that if the user changes the value of a unit involved by the
79// <linkto class=UnitMap>putUser()</linkto> method, the unit using it should be
80// re-created (<src> a = Unit("5Bolton/beam");</src>).
81// </note>
82// A unit is a string of one or more fields separated
83// by 'space' or '.' or '*' (FITS option)
84// (to indicate multiply) or '/' (to indicate divide).
85// Multiple separators are acted upon (i.e. m//s == m.s).
86// Separators are acted upon left-to-right (i.e. m/s/A == (m/s)/A; use
87// () to indicate otherwise (e.g. m/(s/A))).
88//
89// A field is a name, or a unit enclosed in (), optionally followed by an,
90// optionally signed, decimal constant.
91// The decimal constant may be proceeded by '**' or '^' (FITS option)
92//
93// E.g. m.(m/s)-2 == m-1.s2)
94// <note role=tip>
95// A 'space' or '.' before an opening '(' can be omitted.
96// </note>
97// A name can consist of case-sensitive letters, '_', ''', ':', '"' and '0'
98// ('0' not as first character). Digits 1-9 are allowed if preceded with
99// an '_'.
100//
101// Possible legal names are e.g. <src>Jy, R0, R_1, "_2</src>.
102// <note role=tip>
103// <ul>
104// <li> <src>'</src> is used for arcmin
105// <li> <src>''</src> or <src>"</src> for arcsec
106// <li> : :: and ::: are used for h, min, s respectively
107// <li> _ is used for an undimensioned value (like beam or pixel)
108// </ul>
109// </note>
110// <note role=caution> The standard naming conventions for SI units are that they are
111// all in lowercase, unless derived from a person's name, when they start
112// with a capital letter. Notable exceptions are some of the astronomical
113// SI related units (e.g. AU).
114// </note>
115// A name can be preceded by a (standard) decimal prefix.
116//
117// A name must be defined in a Unit map before it can be used.
118//
119// All SI units and some customary units are part of the classes. User
120// defined names can be added by the UnitMap::putUser() function (see
121// the <linkto class=UnitMap>UnitMap</linkto> class).
122//
123// Example:
124// km/s/(Mpc.s)2 is identical to km.s-1.Mpc-2.s-2
125//
126// There are 5 name lists in the UnitMap, which are searched in reverse order:
127// <ol>
128// <li> Defining units: m, kg, s, A, K, cd, mol, rad, sr, _
129// <li> SI units: including a.o. g, Jy, AU
130// <li> Customary units: e.g. lb, hp, ly
131// <li> User defined units: defined by user (e.g. beam, KPH, KM)
132// <li> Cached units: for speed in operations
133// </ol>
134// All known names can be viewed by running the tUnit test program, or
135// using the MapUnit::list() routine.
136// They are also (at least the 1999/09/15 values) available in the
137// <linkto module="Quanta">Quanta module documentation</linkto>.
138// <note role=caution>
139// There is a difference between units without a dimension (non-dimensioned
140// I will call them), and undimensioned units. Non-dimensioned examples are
141// "", "%"; undimensioned examples: "beam", "pixel".
142// </note>
143//
144// <h3> Unit class </h3>
145// The Unit class is not directly based on the String class, but Strings and
146// Units are interchangeable in all Unit and Quantum related calls.
147// (But notice the earlier note on speed if using explicit Strings often.)
148//
149// To calculate with Units (or Strings representing units), use the
150// <linkto class=UnitVal>UnitVal</linkto> class. To use dimensioned values,
151// use the <linkto class=Quantum>Quantum</linkto> (cq Quantity) class.
152//
153// Using Unit i.s.o. String will give an immediate check of the legality
154// of the unit string.
155// In addition the UnitVal class contains a check facility to determine the
156// legality of a unit string:
157// <srcblock>
158// Bool UnitVal::check("string");
159// </srcblock>
160//
161// </synopsis>
162//
163// <example>
164// <srcblock>
165// #include <casacore/casa/Quanta.h>
166// // check if a string is a valid unit
167// if ( !UnitVal::check("Km") ) { cout << "Invalid unit string " << "Km" << endl; }
168// // define some units
169// String unit1="km/Mpc";
170// Unit unit2="uJy/Mpc";
171// // define your own unit name
172// UnitMap::putUser("my_univ", UnitVal( C::pi, unit2), "My universe param");
173// // use the units in model calculations
174// Quantity observed( 8.97, "Mmy_univ/a");
175// Quantity theory (3.8e-9, "mmy_univ/s");
176// if ( ( observed / theory) < 1.) { cout << "Eureka" << endl; }
177// </srcblock>
178// </example>
179//
180// <motivation>
181// Make basis for all dimensioned values the SI system of units
182// </motivation>
183//
184// <todo asof="941110">
185// <li> Some inlining (did not work first go)
186// <li> Look into possiblity of conversion routine from rad2 to sr
187// </todo>
188
189class Unit {
190 public:
191//# Constructors
192// Default empty string constructor
194// Copy constructor
195 Unit(const Unit &other);
196// String based constructors.
197// <thrown>
198// <li> AipsError if illegal unit string
199// </thrown>
200// <group name="constructor">
201 Unit(const std::string &other);
202 Unit(const Char *other);
203 explicit Unit(Char other);
204 Unit(const Char *other, Int len);
205// </group>
206// Destructor
207 ~Unit();
209//* Operators
210// Copy assignment
211 Unit& operator=(const Unit &other);
212// Comparisons. Comparisons are done on the basis of the inherent units. I.e.
213// <src>m/s</src> are identical to <src>AU/cy</src>.
214// <group>
215 Bool operator==(const Unit &other) const;
216 Bool operator!=(const Unit &other) const;
217// Fast check for "" units
218 Bool empty() const;
219// </group>
220//# Member functions
221// Get the unit value
222 const UnitVal &getValue() const;
223// Get the unit name
224 const String &getName() const;
225// Set the unit value
226 void setValue(const UnitVal &in);
227// Set the unit name
228 void setName(const String &in);
229
230private:
231//# Data
234
235//# Member functions
236// Check format of unit string
237// <thrown>
238// <li> AipsError
239// </thrown>
240 void check();
241};
242
243//# Inline Implementations
244
245
246} //# NAMESPACE CASACORE - END
247
248#endif
String: the storage and methods of handling collections of characters.
Definition: String.h:225
Unit()
Default empty string constructor.
void check()
Check format of unit string.
Unit(const Char *other)
Unit(const Unit &other)
Copy constructor.
Unit(const std::string &other)
String based constructors.
Bool empty() const
Fast check for "" units.
~Unit()
Destructor.
Bool operator==(const Unit &other) const
Comparisons.
void setName(const String &in)
Set the unit name.
Bool operator!=(const Unit &other) const
Unit(const Char *other, Int len)
const UnitVal & getValue() const
Get the unit value.
UnitVal uVal
Definition: Unit.h:233
Unit & operator=(const Unit &other)
Unit(Char other)
String uName
Definition: Unit.h:232
void setValue(const UnitVal &in)
Set the unit value.
const String & getName() const
Get the unit name.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
char Char
Definition: aipstype.h:46