casacore
Loading...
Searching...
No Matches
TableMeasRefDesc.h
Go to the documentation of this file.
1//# TableMeasRefDesc.h: Definition of a Measure Reference in a Table.
2//# Copyright (C) 1997,1999,2000,2001
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_TABLEMEASREFDESC_H
29#define MEASURES_TABLEMEASREFDESC_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/measures/TableMeasures/TableMeasOffsetDesc.h>
34#include <casacore/casa/Quanta/Unit.h>
35#include <casacore/casa/Arrays/Vector.h>
36#include <casacore/casa/BasicSL/String.h>
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward Declarations
41class TableMeasDescBase;
42class Table;
43class TableDesc;
44class TableRecord;
45
46
47// <summary>
48// Definition of a Measure Reference in a Table.
49// </summary>
50
51// <use visibility=export>
52
53// <reviewed reviewer="Bob Garwood" date="1999/12/23" tests="tTableMeasures.cc">
54// </reviewed>
55
56// <prerequisite>
57//# Classes you should understand before using this one.
58// <li> <linkto module=Measures>Measures</linkto>
59// <li> <linkto module=Tables>Tables</linkto>
60// <li> <linkto class=TableMeasDesc>TableMeasDesc</linkto>
61// </prerequisite>
62
63// <synopsis>
64// TableMeasRefDesc is a class for setting up the MeasRef
65// component of a TableMeasDesc in the TableMeasures system. With the aid
66// of a
67// TableMeasRefDesc the following possibilities for defining a Measure
68// column's reference exist:
69// <ul>
70// <li> a fixed, non-variable, reference code, where all Measures in a
71// column are to have the same reference code.
72// <li> a unique (and probably different) reference code stored in each row.
73// <li> a unique reference code stored in each array element per
74// (Array)column row.
75// </ul>
76// For each of the above options an offset component can be specified
77// along with a reference code. When a Measure offset is required a
78// <linkto class="TableMeasOffsetDesc">TableMeasOffsetDesc</linkto> is
79// supplied as an argument to the TableMeasRefDesc constructor.
80// With references containing an offset component either component can be set
81// to be variable or fixed independently of the other.
82//
83// <note role=tip>
84// It is not necessary to specify a Reference when defining a
85// Measure column. In such cases the Measures retrieved from the column
86// will have the default reference for the type of Measure stored in the
87// column.
88// </note>
89//
90// A fixed reference code is trivially stored as part of the column
91// keywords in the Measure column but a variable reference code requires
92// its own column. A Scalar or Array column can be used dependent on your
93// needs but its type must always be either Int or String. Note that it is
94// legal to specify a Scalar
95// reference column for use with an ArrayMeasColumn. In such cases a single
96// reference code will be stored per array (row) of Measures. However,
97// attempting to associate an Array column for references with a
98// ScalarMeasColumn will generate an exception.
99// <note>
100// Because the reference codes stored are the enums defined in the Measures
101// classes, it is possible that they change over time. The type strings,
102// however, wille never change. Therefore the reference codes and types
103// valid at the time of the table creation, are stored in the column keywords
104// if the reference codes are kept in an integer column.
105// <br>
106// This has only been added in March 2007, but is fully backward compatible.
107// Older tables will get the codes and types stored when accessed for
108// read/write.
109// </note>
110//
111// <note role=caution>
112// When storing Measures into a Measure column with a fixed reference code
113// the reference code component of the Measures stored is
114// ignored.
115// </note>
116// </synopsis>
117
118// <example>
119//<ol>
120// <li>Simplest kind of TableMeasRefDesc (apart from not specifying one at
121// all) is a fixed reference code. All Measures subsequently
122// retrieved from the column will have the reference MEpoch::LAST.
123// <srcblock>
124// // measure reference column
125// TableMeasRefDesc reference(MEpoch::LAST);
126// </srcblock>
127// <li>A variable reference code requires its own Int column.
128// <srcblock>
129// // An int column for the variable references.
130// ScalarColumnDesc<Int> cdRefCol("refCol", "Measure reference column");
131// td.addColumn(cdRefCol);
132// ...
133// // create the Measure reference descriptor
134// TableMeasRefDesc varRef(td, "refCol");
135// </srcblock>
136// <li>A fix Measure reference code with a fixed Offset
137// <srcblock>
138// // Create the Offset descriptor
139// MEpoch offset(MVEpoch(MVTime(1996, 5, 17, (8+18./60.)/24.))
140// TableMeasOffsetDesc offsetDesc(offset);
141// // create the Measure reference descriptor
142// TableMeasRefDesc varRef(MEpoch::LAST, offsetDesc);
143// </srcblock>
144//</ol>
145// For an example of the use of a TableMeasRefDesc in the context of a full
146// TableMeasDesc declaration see class
147// <linkto class="TableMeasDesc">TableMeasDesc</linkto>.
148// </example>
149
150// <motivation>
151// Creating the required keyword for the definition of a Measure
152// in a Table is somewhat complicated. This class assists in that
153// process.
154// </motivation>
155//
156// <thrown>
157// <li>AipsError if the specified column doesn't exist or its type is
158// not Int or String.
159// </thrown>
160//
161
162//# <todo asof="$DATE:$">
163//# A List of bugs, limitations, extensions or planned refinements.
164//# </todo>
165
166
168{
169public:
170 // Define a fixed MeasRef by supplying its reference code
171 // Optionally a Measure offset can be specified.
172 // The reference code and offset should not need a reference frame.
173 // <group>
174 explicit TableMeasRefDesc (uInt refCode = 0);
176 // </group>
177
178 // Define a variable reference by supplying the name of the column
179 // in which the reference is to be stored. Either an <src>Int</src> or
180 // <src>String</src> column can be specified. This determines how
181 // references are stored. <src>Int</src> columns are likely to be
182 // faster but storing
183 // references as <src>Strings</src> may be useful if there is a need to
184 // browse tables manually. Optionally supply a Measure offset.
185 // The reference code and offset should not need a reference frame.
186 // <group>
187 TableMeasRefDesc (const TableDesc&, const String& column);
188 TableMeasRefDesc (const TableDesc&, const String& column,
189 const TableMeasOffsetDesc&);
190 // </group>
191
192 // Reconstruct the object from the MEASINFO record.
193 // Not useful for the public.
195 const Table&,
196 const MeasureHolder& measHolder,
197 const TableMeasDescBase&);
198
199 // Copy constructor (copy semantics)
201
203
204 // Assignment operator (copy semantics).
206
207 // Return the reference code.
209 { return itsRefCode; }
210
211 // Is the reference variable?
213 { return (! itsColumn.empty()); }
214
215 // Return the name of its variable reference code column.
216 const String& columnName() const
217 { return itsColumn; }
218
219 // Is the reference code variable and stored in an integer column?
221 { return itsRefCodeColInt; }
222
223 // Do the keywords contain the reference codes and types.
224 // For old tables this might not be the case.
226 { return itsHasRefTab; }
227
228 // Returns True if the reference has an offset.
230 { return (itsOffset != 0); }
231
232 // Returns True if the offset is variable.
234 { return (itsOffset != 0 ? itsOffset->isVariable() : False); }
235
236 // Returns True is the offset is variable and it is an ArrayMeasColumn.
238 { return (itsOffset != 0 ? itsOffset->isArray() : False); }
239
240 // Return the fixed Measure offset.
241 // It does not test if the offset is defined; hasOffset() should be used
242 // for that purpose.
243 const Measure& getOffset() const
244 { return itsOffset->getOffset(); }
245
246 // Return the name of the Measure offset column.
247 // An empty string is returned if no variable offset is used.
249 { return itsOffset->columnName(); }
250
251 // Reset the refCode or offset.
252 // It overwrites the value used when defining the TableMeasDesc.
253 // It is only possible if it was defined as fixed for the entire column.
254 // <group>
255 void resetRefCode (uInt refCode);
256 void resetOffset (const Measure& offset);
257 // </group>
258
259 // Make the Measure value descriptor persistent. Normally would not be
260 // called by the user directly.
261 // <group>
262 void write (TableDesc&, TableRecord& measInfo, const TableMeasDescBase&);
263 void write (Table&, TableRecord& measInfo, const TableMeasDescBase&);
264 // </group>
265
266 // Initialize the table reference codes and types and
267 // the maps (mapping a code onto itself).
268 void initTabRef (const MeasureHolder& measHolder);
269
270 // Reference codes can be persistent in tables.
271 // Because their enum values can change, a mapping of current table
272 // to table value is maintained. The mapping is created using their
273 // never-changing string representations.
274 // These functions convert current refcode to and from table refcode.
275 // <group>
276 uInt tab2cur (uInt tabRefCode) const;
277 uInt cur2tab (uInt curRefCode) const;
278 // </group>
279
280 // Set the function used to get all reference codes for a MeasureHolder.
281 // This is not really needed for normal practice, but makes it possible
282 // to add extra codes when testing.
283 // <br> The default function simply calls MeasureHolder.asMeasure.allTypes.
284 // <group>
285 typedef void TypesFunc (Vector<String>& types,
286 Vector<uInt>& codes, const MeasureHolder&);
287 static void setTypesFunc (TypesFunc* func)
288 { theirTypesFunc = func; }
289 static void defaultTypesFunc (Vector<String>& types,
290 Vector<uInt>& codes, const MeasureHolder&);
292 // </group>
293
294private:
296 // The name of column containing its variable references.
298 // Is the reference code column a string column?
300 // Do the keywords contain the reference codes and types?
302 //# Its reference offset.
304 //# Define the vectors holding the measref codes and types.
305 //# These are the codes as used in the table, which might be different
306 //# from the current values.
309 //# Define the mappings of table measref codes to current ones and back.
310 //# There are only filled in and used if a variable reference code is used.
313
314 // Fill the reference code mappings for table<->current.
315 // <group>
317 void fillTabRefMap (const MeasureHolder& measHolder);
319 const Vector<uInt>& codesf,
320 const Vector<String>& typesf,
321 Vector<uInt>& codest,
322 Vector<String>& typest,
323 Int maxnr);
324 // </group>
325
326 // Write the actual keywords.
327 void writeKeys (TableRecord& measInfo,
328 const TableMeasDescBase& measDesc);
329
330 // Throw an exception if the column doesn't exist or is of the
331 // wrong type.
332 void checkColumn (const TableDesc& td);
333};
334
335
336
337} //# NAMESPACE CASACORE - END
338
339#endif
simple 1-D array
Definition Block.h:200
String: the storage and methods of handling collections of characters.
Definition String.h:225
Bool empty() const
Test for empty.
Definition String.h:377
const String & columnName() const
Gets the name of the column which stores the variable offset.
const Measure & getOffset() const
Get the (non-variable) measure offset for this column.
Bool isArray() const
Returns True if the offset varies per array element.
Bool isVariable() const
Returns True if the offset varies per row.
String itsColumn
The name of column containing its variable references.
TableMeasRefDesc(const TableDesc &, const String &column)
Define a variable reference by supplying the name of the column in which the reference is to be store...
TableMeasRefDesc(const TableDesc &, const String &column, const TableMeasOffsetDesc &)
Bool isRefCodeVariable() const
Is the reference variable?
Bool hasRefTab() const
Do the keywords contain the reference codes and types.
TableMeasRefDesc & operator=(const TableMeasRefDesc &that)
Assignment operator (copy semantics).
const Measure & getOffset() const
Return the fixed Measure offset.
void write(TableDesc &, TableRecord &measInfo, const TableMeasDescBase &)
Make the Measure value descriptor persistent.
uInt getRefCode() const
Return the reference code.
void fillTabRefMap(const MeasureHolder &measHolder)
Bool isOffsetArray() const
Returns True is the offset is variable and it is an ArrayMeasColumn.
static void defaultTypesFunc(Vector< String > &types, Vector< uInt > &codes, const MeasureHolder &)
void initTabRef(const MeasureHolder &measHolder)
Initialize the table reference codes and types and the maps (mapping a code onto itself).
uInt cur2tab(uInt curRefCode) const
const String & columnName() const
Return the name of its variable reference code column.
Bool itsHasRefTab
Do the keywords contain the reference codes and types?
void write(Table &, TableRecord &measInfo, const TableMeasDescBase &)
Bool isOffsetVariable() const
Returns True if the offset is variable.
TableMeasRefDesc(uInt refCode=0)
Define a fixed MeasRef by supplying its reference code Optionally a Measure offset can be specified.
void checkColumn(const TableDesc &td)
Throw an exception if the column doesn't exist or is of the wrong type.
TableMeasRefDesc(const TableMeasRefDesc &that)
Copy constructor (copy semantics)
TableMeasOffsetDesc * itsOffset
const String & offsetColumnName() const
Return the name of the Measure offset column.
void writeKeys(TableRecord &measInfo, const TableMeasDescBase &measDesc)
Write the actual keywords.
void initTabRefMap()
Fill the reference code mappings for table<->current.
TableMeasRefDesc(uInt refCode, const TableMeasOffsetDesc &)
TableMeasRefDesc(const TableRecord &measInfo, const Table &, const MeasureHolder &measHolder, const TableMeasDescBase &)
Reconstruct the object from the MEASINFO record.
Bool hasOffset() const
Returns True if the reference has an offset.
void resetRefCode(uInt refCode)
Reset the refCode or offset.
uInt fillMap(Block< Int > &f2t, const Vector< uInt > &codesf, const Vector< String > &typesf, Vector< uInt > &codest, Vector< String > &typest, Int maxnr)
static void setTypesFunc(TypesFunc *func)
static TypesFunc * theirTypesFunc
uInt tab2cur(uInt tabRefCode) const
Reference codes can be persistent in tables.
void resetOffset(const Measure &offset)
Bool isRefCodeColumnInt() const
Is the reference code variable and stored in an integer column?
Bool itsRefCodeColInt
Is the reference code column a string column?
void TypesFunc(Vector< String > &types, Vector< uInt > &codes, const MeasureHolder &)
Set the function used to get all reference codes for a MeasureHolder.
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:44
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