casacore
MeasureHolder.h
Go to the documentation of this file.
1//# MeasureHolder.h: A holder for Measures 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 MEASURES_MEASUREHOLDER_H
29#define MEASURES_MEASUREHOLDER_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/Containers/Block.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40class Measure;
41class MDirection;
42class MDoppler;
43class MEpoch;
44class MFrequency;
45class MPosition;
46class MRadialVelocity;
47class Muvw;
48class MBaseline;
49class MEarthMagnetic;
50class MeasValue;
51
52// <summary> A holder for Measures to enable record conversions </summary>
53
54// <use visibility=export>
55
56// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasureHolder" demos="">
57// </reviewed>
58
59// <prerequisite>
60// <li> <linkto class=RecordInterface>RecordInterface</linkto> class
61// <li> <linkto class=Measure>Measure</linkto> class
62// </prerequisite>
63//
64// <etymology>
65// A Holder of general Measures
66// </etymology>
67//
68// <synopsis>
69// This class can be used to handle heterogeneous collections of Measures, e.g.
70// as a <src>Vector<MeasureHolder></src>. With the aid of the
71// toRecord() and fromRecord() functions it can be used
72// to convert a Measure object into or from a record.
73// A MeasureHolder is created from a Measure, or can be empty.
74//
75// Checks on the contents can be made with functions like
76// <src>isMDirection</src> and the contents can be obtained with
77// functions like <src>asMDirection</src>. It is an error to try and
78// retrieve a measure of the wrong type and doing so will generate an
79// exception (AipsError).
80//
81// The MeasureHolder can, in addition to the Measure it is holding, also hold
82// a block of MeasValues. This is especially useful for intertask
83// communication (e.g. with Glish), for reasons of speed. In general the
84// additional values will be created when the record used to create
85// a Holder contains a <src>Quantity<Vector></src> rather than a quantity in
86// the m0, m1 and/or m2 fields. The <src>getMV()</src> method can be used to
87// access the <src>nelements()</src> additional information. They can be
88// (re-)set with the <src>setMV()</src> method (after a possible creation
89// of the extra block if not already there, or of the wrong length,
90// with <src>makeMV()</src>. If any value is set they will be used in
91// creating records, with the first value always overwriting the actual
92// Measure value.
93//
94// </synopsis>
95//
96// <example>
97// <srcblock>
98// TableRecord rec;
99// MDirection dir(MVDirection(Quantity(12.5, 'deg'), Quantity(-2, 'deg')),
100// MDirection::J2000);
101// String error; // error message
102// if (!MeasureHolder(dir).toRecord(error, rec)) {
103// cout << error << endl;
104// }
105// Record grec; // a Record
106// if (!MeasureHolder(dir).toRecord(error, grec)) { // make record
107// cout << error << endl;
108// }
109// // Note that for GlishRecords use can be made of the
110// // GlishRecord::to/fromrecord() methods.
111// </srcblock>
112// </example>
113//
114// <motivation>
115// To make general conversions between Measures and records, without knowing
116// the actual Measure being converted.
117// </motivation>
118
120
121public:
122
123//# Friends
124
125//# Enumerations
126
127//# Constructors
128 // Creates an empty holder
130 // Create from a Measure (copy made)
132 // Copy a holder (copy semantics)
134//# Destructor
136
137//# Operators
138 // Assignment (copy semantics)
140
141//# Member Functions
142 // Check the the MeasureHolder holds the specified Measure type. Return
143 // True if if does and False otherwise.
144 // <group>
145 Bool isEmpty() const;
149 Bool isMEpoch() const;
154 Bool isMuvw() const;
156 // </group>
157
158 // Get a specific Measure from the holder (with lifetime as long
159 // as holder exists).
160 // <thrown>
161 // <li> AipsError if holder empty
162 // <li> AipsError if holder contains wrong Measure
163 // </thrown>
164 // <group>
165 const Measure &asMeasure() const;
166 const MDirection &asMDirection() const;
167 const MDoppler &asMDoppler() const;
168 const MEpoch &asMEpoch() const;
169 const MFrequency &asMFrequency() const;
170 const MPosition &asMPosition() const;
172 const MBaseline &asMBaseline() const;
173 const Muvw &asMuvw() const;
175 // </group>
176 // Create a Measure from a record. An error message is generated, and False
177 // returned if an invalid record is given. A valid record will return True.
178 // A valid record contains the following fields (any additional fields are
179 // ignored):
180 // <ul>
181 // <li> type = TpString: type of Measure (direction, epoch, etc; case
182 // insensitive)
183 // <li> refer = TpString: reference type of Measure (case insensitive;
184 // enough characters to be unique (e.g. J20, j200, utc, b1950, J2000);
185 // unknown reference type will log an error message and translate into
186 // the default type for the Measure.
187 // <li> m0, m1, ... = TpRecord(Quantity): one or more Quantities giving
188 // the value(s) for this Measure (e.g. longitude and latitude for a
189 // direction). Each quantity can either be a scalar quantity or a
190 // Quantum<Vector<Double> >.
191 // <li> offset = TpRecord(Measure)--optional: an optional offset as a
192 // Measure of the same type as the main Measure (e.g. an MEpoch for an
193 // MEpoch)
194 // </ul>
195 // A Measure can be created from a string. In that case the string
196 // will only indicate the type of measure (like direction), and will
197 // create a default measure of that given type. In essence identical
198 // to the fromType() method.
199 // Error messages are postfixed to error.
200 // <group>
201 virtual Bool fromRecord(String &error, const RecordInterface &in);
202 virtual Bool fromString(String &error, const String &in);
203 // </group>
204 // Create a record from a Measure. The return will be False and an error
205 // message generated only if the MeasureHolder does not contain a Measure.
206 // Error messages are postfixed to error.
207 virtual Bool toRecord(String &error, RecordInterface &out) const;
208
209 // This version throws an exception if the conversion cannot
210 // occur. It is meant for more allow more compact calling code for callers
211 // that are content with just letting the exception proceed up the call stack
212 // so they do not have to check a return status. This is, among other things, what
213 // exceptions are for after all.
214 virtual void toRecord(RecordInterface& outRecord) const;
215
216
217 // Create a default Measure or a record with only a type from a Measure
218 // <group>
219 Bool toType(String &error, RecordInterface &out) const;
221 // </group>
222 // Get identification of record
223 virtual const String &ident() const;
224 // Do we write MeasValues to record?
225 Bool writeMV() const { return convertmv_p; }
226 // Make a block of n MeasValues
227 void makeMV(uInt n) { createMV(n); }
228 // Get number of MeasValue pointers in block
229 uInt nelements() const { return mvhold_p.nelements(); }
230 // Set a measvalue at position pos (False if illegal pos)
231 Bool setMV(uInt pos, const MeasValue &in);
232 // Get a pointer to a MeasValue (or 0)
233 MeasValue *getMV(uInt pos) const;
234
235private:
236
237 //# Data Members
238 // Pointer to a Measure
240 // Block of pointers to measure values to make a faster interface
242 // Should the mvhold_p be converted into record?
244 //# Member functions
245 // Aid for to/from Record, String and Type
246 // <group>
247 Bool putType(String &error, RecordInterface &out) const;
248 Bool getType(String &error, const RecordInterface &in);
249 Bool getType(String &error, const String &in);
250 // </group>
251 // Make a MeasValue block of pointers of length n
252 void createMV(uInt n);
253};
254
255
256} //# NAMESPACE CASACORE - END
257
258#endif
simple 1-D array
Definition: Block.h:200
Block< MeasValue * > mvhold_p
Block of pointers to measure values to make a faster interface.
Bool fromType(String &error, const RecordInterface &in)
Bool isMFrequency() const
MeasureHolder(const MeasureHolder &other)
Copy a holder (copy semantics)
const Muvw & asMuvw() const
const MEpoch & asMEpoch() const
Bool getType(String &error, const RecordInterface &in)
MeasValue * getMV(uInt pos) const
Get a pointer to a MeasValue (or 0)
Bool isMDirection() const
Bool toType(String &error, RecordInterface &out) const
Create a default Measure or a record with only a type from a Measure.
const MDoppler & asMDoppler() const
const MRadialVelocity & asMRadialVelocity() const
Bool isMBaseline() const
virtual Bool toRecord(String &error, RecordInterface &out) const
Create a record from a Measure.
const MFrequency & asMFrequency() const
virtual Bool fromString(String &error, const String &in)
Initialise the class from a String representation.
Bool getType(String &error, const String &in)
void makeMV(uInt n)
Make a block of n MeasValues.
virtual void toRecord(RecordInterface &outRecord) const
This version throws an exception if the conversion cannot occur.
MeasureHolder()
Creates an empty holder.
MeasureHolder(const Measure &in)
Create from a Measure (copy made)
Bool isEmpty() const
Check the the MeasureHolder holds the specified Measure type.
void createMV(uInt n)
Make a MeasValue block of pointers of length n.
Bool convertmv_p
Should the mvhold_p be converted into record?
PtrHolder< Measure > hold_p
Pointer to a Measure.
Bool isMPosition() const
uInt nelements() const
Get number of MeasValue pointers in block.
const MBaseline & asMBaseline() const
Bool setMV(uInt pos, const MeasValue &in)
Set a measvalue at position pos (False if illegal pos)
const Measure & asMeasure() const
Get a specific Measure from the holder (with lifetime as long as holder exists).
const MDirection & asMDirection() const
MeasureHolder & operator=(const MeasureHolder &other)
Assignment (copy semantics)
Bool isMRadialVelocity() const
Bool writeMV() const
Do we write MeasValues to record?
Bool isMEarthMagnetic() const
const MEarthMagnetic & asMEarthMagnetic() const
virtual Bool fromRecord(String &error, const RecordInterface &in)
Create a Measure from a record.
virtual const String & ident() const
Get identification of record.
Bool putType(String &error, RecordInterface &out) const
Aid for to/from Record, String and Type.
const MPosition & asMPosition() 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
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42