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 
37 namespace 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 
189 class Unit {
190  public:
191 //# Constructors
192 // Default empty string constructor
193  Unit();
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();
208 
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 
230 private:
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.
const UnitVal & getValue() const
Get the unit value.
Bool operator!=(const Unit &other) const
Unit & operator=(const Unit &other)
const String & getName() const
Get the unit name.
UnitVal uVal
Definition: Unit.h:233
Unit(Char other)
String uName
Definition: Unit.h:232
void setValue(const UnitVal &in)
Set the unit value.
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