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 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class Measure;
41 class MDirection;
42 class MDoppler;
43 class MEpoch;
44 class MFrequency;
45 class MPosition;
46 class MRadialVelocity;
47 class Muvw;
48 class MBaseline;
49 class MEarthMagnetic;
50 class 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 
121 public:
122 
123 //# Friends
124 
125 //# Enumerations
126 
127 //# Constructors
128  // Creates an empty holder
130  // Create from a Measure (copy made)
131  MeasureHolder(const Measure &in);
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;
146  Bool isMeasure() const;
148  Bool isMDoppler() const;
149  Bool isMEpoch() const;
151  Bool isMPosition() const;
153  Bool isMBaseline() 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;
220  Bool fromType(String &error, const RecordInterface &in);
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 
235 private:
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)
virtual const String & ident() const
Get identification of record.
Bool getType(String &error, const RecordInterface &in)
Bool isMDirection() const
Bool toType(String &error, RecordInterface &out) const
Create a default Measure or a record with only a type from a Measure.
Bool isMBaseline() const
MeasValue * getMV(uInt pos) const
Get a pointer to a MeasValue (or 0)
const MBaseline & asMBaseline() const
const MDirection & asMDirection() const
virtual Bool toRecord(String &error, RecordInterface &out) const
Create a record from a Measure.
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.
const Measure & asMeasure() const
Get a specific Measure from the holder (with lifetime as long as holder exists).
virtual void toRecord(RecordInterface &outRecord) const
This version throws an exception if the conversion cannot occur.
const MPosition & asMPosition() const
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.
const Muvw & asMuvw() const
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.
const MEarthMagnetic & asMEarthMagnetic() const
Bool isMPosition() const
uInt nelements() const
Get number of MeasValue pointers in block.
const MFrequency & asMFrequency() const
Bool setMV(uInt pos, const MeasValue &in)
Set a measvalue at position pos (False if illegal pos)
const MEpoch & asMEpoch() const
Bool isMRadialVelocity() const
MeasureHolder & operator=(const MeasureHolder &other)
Assignment (copy semantics)
Bool writeMV() const
Do we write MeasValues to record?
const MRadialVelocity & asMRadialVelocity() const
Bool isMEarthMagnetic() const
virtual Bool fromRecord(String &error, const RecordInterface &in)
Create a Measure from a record.
const MDoppler & asMDoppler() const
Bool putType(String &error, RecordInterface &out) const
Aid for to/from Record, String and Type.
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