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