casacore
QuantumHolder.h
Go to the documentation of this file.
1//# QuantumHolder.h: A holder for Quantities to enable record conversions
2//# Copyright (C) 1998,1999,2000,2003
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_QUANTUMHOLDER_H
29#define CASA_QUANTUMHOLDER_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Arrays/ArrayFwd.h>
34#include <casacore/casa/Utilities/PtrHolder.h>
35#include <casacore/casa/Utilities/RecordTransformable.h>
36#include <casacore/casa/BasicSL/Complexfwd.h>
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward Declarations
41class QBase;
42class String;
43class RecordInterface;
44class Record;
45template <class Qtype> class Quantum;
46
47// <summary> A holder for Quantums to enable record conversions </summary>
48
49// <use visibility=export>
50
51// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tQuantumHolder" demos="">
52// </reviewed>
53
54// <prerequisite>
55// <li> <linkto class=RecordInterface>RecordInterface</linkto> class
56// <li> <linkto class=Quantum>Quantity</linkto> class
57// </prerequisite>
58//
59// <etymology>
60// A Holder of general Quantums
61// </etymology>
62//
63// <synopsis>
64// This class can be used to handle a heterogeneous list of Quantums, and
65// can handle toRecord() and fromRecord() conversions.
66// A QuantumHolder
67// is created empty, from a Quantum (e.g. a <src>Quantum<Double></src>) or a
68// <src>Quantum<Vector<Float> ></src>).
69//
70// The accepted range of Quantums is:
71// <ul>
72// <li> <src>Quantum<Int>, Quantum<Float>, Quantum<Double> == Quantity</src>
73// <li> <src>Quantum<Complex>, Quantum<DComplex></src>
74// <li> <src>Quantum<Vector<Int> >, Quantum<Vector<Float> ></src>,
75// <src>Quantum<Vector<Double> ></src>
76// <li> <src>Quantum<Vector<Complex> >, Quantum<Vector<DComplex> ></src>
77// <li> <src>Quantum<Array<Int> >, Quantum<Array<Float> ></src>,
78// <src>Quantum<Array<Double> ></src>
79// <li> <src>Quantum<Array<Complex> >, Quantum<Array<DComplex> ></src>
80// </ul>
81// Scalars in the same group can be converted to any in the same group (e.g.
82// Int to Double); Vectors of length 1 can be converted to scalars in the
83// corresponding group; Scalars can always be converted to Vectors in the
84// corresponding group. Real scalar values can be converted to Complex values.
85// Vectors cannot be converted to other type vectors.
86//
87// Checks on the contents can be made with functions like
88// <src>isQuantity</src> and the contents can be obtained with
89// functions like <src>asQuantity</src>. It is an error to try and
90// retrieve a Quantum of the wrong type and doing so will generate an
91// exception (AipsError).
92// </synopsis>
93//
94// <example>
95// <srcblock>
96// TableRecord rec; // an empty record
97// Quantity x(12.5, "km/s"); // a Quantity
98// String error; // an error message
99// if (!QuantumHolder(x).toRecord(error, rec)) { // make record
100// cout << error << endl;
101// };
102// Record grec; // a Record
103// if (!QuantumHolder(x).toRecord(error, grec)) { // make record
104// cout << error << endl;
105// };
106// // Note that for GlishRecords use can be made of the
107// // GlishRecord::to/fromrecord() methods.
108// </srcblock>
109// </example>
110//
111// <motivation>
112// To make general conversions between Quantums and records, without knowing
113// the actual Quantum being converted.
114// </motivation>
115
117
118public:
119
120//# Friends
121
122//# Enumerations
123
124//# Constructors
125 // Creates an empty holder
127 // Create from a Quantum (copy semantics)
129 // Copy a holder (copy semantics)
131//# Destructor
133
134//# Operators
135 // Assignment (copy semantics)
137
138//# Member Functions
139 // Check if it holds a Quantity. Note that a Vector of length 1 will give
140 // True to scalar questions.
141 // <group>
142 Bool isEmpty() const;
144 Bool isScalar() const;
145 Bool isVector() const;
146 Bool isArray() const;
147 Bool isReal() const;
165 // </group>
166 // Get number of numeric elements (1 if scalar, else
167 // vector length) or dimensions (0 if scalar)
168 // <thrown>
169 // <li> AipsError if holder empty
170 // </thrown>
171 // <group>
172 Int nelements() const;
173 Int ndim() const;
174 // </group>
175
176 // Get a Quantum from the holder (with lifetime as long
177 // as holder exists). Conversions done if necessary and as described in
178 // introduction.
179 // <thrown>
180 // <li> AipsError if holder empty or no conversion possible
181 // </thrown>
182 // <group>
183 const QBase &asQuantum() const;
200 // </group>
201
202 // Create a Quantum from a record or a string.
203 // A valid record will contain the following fields:
204 // <ul>
205 // <li> value: contains a numeric value of Int, Float, Double, Complex,
206 // DComplex or a vector thereof
207 // <li> unit: a string with a valid unit string.
208 // </ul>
209 // A valid string will be one of the special time/angle formats or a
210 // value with a valid unit string.
211 // Illegal values or units will return False and write an error message.
212 // <group>
213 virtual Bool fromRecord(String &error, const RecordInterface &in);
214 virtual Bool fromString(String &error, const String &in);
215 // </group>
216 // Create a record from a Quantum. A False return and an error message is
217 // only generated if there is no valid Quantum in the holder.
218 virtual Bool toRecord(String &error, RecordInterface &out) const;
219 // this version throws an exception rather than returning false
220 virtual void toRecord(RecordInterface &out) const;
221 // this version throws an exception or returns the result Record.
222 virtual Record toRecord() const;
223
224
225 // Return identification
226 virtual const String &ident() const;
227
228private:
229
230//# Data Members
231 // Pointer to a Quantity
233
234//# General member functions
235 // Convert to a different real scalar quantum
236 void toReal(const uInt &tp);
237 // Convert to a different complex scalar quantum
238 void toComplex(const uInt &tp);
239 // Convert scalar to Vector
240 void toVector();
241 // Convert scalar to Array
242 void toArray();
243};
244
245
246} //# NAMESPACE CASACORE - END
247
248#endif
const Quantum< Double > & asQuantity()
Bool isQuantumDouble() const
Bool isQuantumDComplex() const
const QBase & asQuantum() const
Get a Quantum from the holder (with lifetime as long as holder exists).
Bool isQuantumVectorComplex() const
Bool isQuantumArrayDComplex() const
Bool isQuantumArrayFloat() const
void toComplex(const uInt &tp)
Convert to a different complex scalar quantum.
Bool isEmpty() const
Check if it holds a Quantity.
const Quantum< Array< Float > > & asQuantumArrayFloat()
const Quantum< Array< Double > > & asQuantumArrayDouble()
QuantumHolder(const QuantumHolder &other)
Copy a holder (copy semantics)
Bool isQuantumVectorDouble() const
Bool isQuantumComplex() const
void toArray()
Convert scalar to Array.
Int nelements() const
Get number of numeric elements (1 if scalar, else vector length) or dimensions (0 if scalar)
QuantumHolder(const QBase &in)
Create from a Quantum (copy semantics)
Bool isQuantumArrayInt() const
const Quantum< Array< DComplex > > & asQuantumArrayDComplex()
void toReal(const uInt &tp)
Convert to a different real scalar quantum.
const Quantum< Double > & asQuantumDouble()
QuantumHolder()
Creates an empty holder.
QuantumHolder & operator=(const QuantumHolder &other)
Assignment (copy semantics)
Bool isQuantumVectorDComplex() const
virtual Bool toRecord(String &error, RecordInterface &out) const
Create a record from a Quantum.
virtual Bool fromString(String &error, const String &in)
Initialise the class from a String representation.
const Quantum< DComplex > & asQuantumDComplex()
PtrHolder< QBase > hold_p
Pointer to a Quantity.
const Quantum< Vector< Double > > & asQuantumVectorDouble()
virtual Record toRecord() const
this version throws an exception or returns the result Record.
const Quantum< Float > & asQuantumFloat()
const Quantum< Array< Complex > > & asQuantumArrayComplex()
const Quantum< Vector< Complex > > & asQuantumVectorComplex()
virtual Bool fromRecord(String &error, const RecordInterface &in)
Create a Quantum from a record or a string.
Bool isQuantumFloat() const
void toVector()
Convert scalar to Vector.
const Quantum< Int > & asQuantumInt()
Bool isQuantumVectorInt() const
Bool isQuantumArrayDouble() const
Bool isQuantumInt() const
Bool isQuantumVectorFloat() const
const Quantum< Vector< DComplex > > & asQuantumVectorDComplex()
const Quantum< Complex > & asQuantumComplex()
const Quantum< Array< Int > > & asQuantumArrayInt()
virtual const String & ident() const
Return identification.
virtual void toRecord(RecordInterface &out) const
this version throws an exception rather than returning false
const Quantum< Vector< Float > > & asQuantumVectorFloat()
const Quantum< Vector< Int > > & asQuantumVectorInt()
Bool isQuantumArrayComplex() const
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42