casacore
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 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 class TableMeasDescBase;
42 class Table;
43 class TableDesc;
44 class 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 {
169 public:
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);
175  TableMeasRefDesc (uInt refCode, const TableMeasOffsetDesc&);
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.
194  TableMeasRefDesc (const TableRecord& measInfo,
195  const Table&,
196  const MeasureHolder& measHolder,
197  const TableMeasDescBase&);
198 
199  // Copy constructor (copy semantics)
200  TableMeasRefDesc (const TableMeasRefDesc& that);
201 
203 
204  // Assignment operator (copy semantics).
206 
207  // Return the reference code.
208  uInt getRefCode() const
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.
225  Bool hasRefTab() const
226  { return itsHasRefTab; }
227 
228  // Returns True if the reference has an offset.
229  Bool hasOffset() const
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.
248  const String& offsetColumnName() const
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 
294 private:
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>
316  void initTabRefMap();
317  void fillTabRefMap (const MeasureHolder& measHolder);
318  uInt fillMap (Block<Int>& f2t,
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
casacore::TableDesc
Define the structure of a Casacore table.
Definition: TableDesc.h:187
casacore::TableMeasRefDesc::fillMap
uInt fillMap(Block< Int > &f2t, const Vector< uInt > &codesf, const Vector< String > &typesf, Vector< uInt > &codest, Vector< String > &typest, Int maxnr)
casacore::MeasureHolder
A holder for Measures to enable record conversions.
Definition: MeasureHolder.h:119
casacore::TableMeasRefDesc::isOffsetArray
Bool isOffsetArray() const
Returns True is the offset is variable and it is an ArrayMeasColumn.
Definition: TableMeasRefDesc.h:237
casacore::TableMeasRefDesc
Definition of a Measure Reference in a Table.
Definition: TableMeasRefDesc.h:167
casacore::TableMeasRefDesc::getRefCode
uInt getRefCode() const
Return the reference code.
Definition: TableMeasRefDesc.h:208
casacore::String::empty
Bool empty() const
Test for empty.
Definition: String.h:375
casacore::Measure
Physical quantities within reference frame.
Definition: Measure.h:235
casacore::TableRecord
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:182
casacore::TableMeasRefDesc::isOffsetVariable
Bool isOffsetVariable() const
Returns True if the offset is variable.
Definition: TableMeasRefDesc.h:233
casacore::TableMeasRefDesc::getOffset
const Measure & getOffset() const
Return the fixed Measure offset.
Definition: TableMeasRefDesc.h:243
casacore::TableMeasRefDesc::itsHasRefTab
Bool itsHasRefTab
Do the keywords contain the reference codes and types?
Definition: TableMeasRefDesc.h:301
casacore::TableMeasRefDesc::resetOffset
void resetOffset(const Measure &offset)
casacore::TableMeasRefDesc::isRefCodeColumnInt
Bool isRefCodeColumnInt() const
Is the reference code variable and stored in an integer column?
Definition: TableMeasRefDesc.h:220
casacore::TableMeasRefDesc::checkColumn
void checkColumn(const TableDesc &td)
Throw an exception if the column doesn't exist or is of the wrong type.
casacore::TableMeasRefDesc::operator=
TableMeasRefDesc & operator=(const TableMeasRefDesc &that)
Assignment operator (copy semantics).
casacore::TableMeasDescBase
Definition of a Measure in a Table.
Definition: TableMeasDescBase.h:93
casacore::TableMeasRefDesc::fillTabRefMap
void fillTabRefMap(const MeasureHolder &measHolder)
casacore::TableMeasRefDesc::tab2cur
uInt tab2cur(uInt tabRefCode) const
Reference codes can be persistent in tables.
casacore::TableMeasRefDesc::itsColumn
String itsColumn
The name of column containing its variable references.
Definition: TableMeasRefDesc.h:297
casacore::TableMeasOffsetDesc::isArray
Bool isArray() const
Returns True if the offset varies per array element.
Definition: TableMeasOffsetDesc.h:180
casacore::TableMeasRefDesc::itsOffset
TableMeasOffsetDesc * itsOffset
Definition: TableMeasRefDesc.h:303
casacore::TableMeasRefDesc::defaultTypesFunc
static void defaultTypesFunc(Vector< String > &types, Vector< uInt > &codes, const MeasureHolder &)
casacore::Table
Main interface class to a read/write table.
Definition: Table.h:153
casacore::TableMeasRefDesc::write
void write(TableDesc &, TableRecord &measInfo, const TableMeasDescBase &)
Make the Measure value descriptor persistent.
casacore::TableMeasRefDesc::itsCur2Tab
Block< Int > itsCur2Tab
Definition: TableMeasRefDesc.h:312
casacore::TableMeasRefDesc::offsetColumnName
const String & offsetColumnName() const
Return the name of the Measure offset column.
Definition: TableMeasRefDesc.h:248
casacore::TableMeasRefDesc::initTabRefMap
void initTabRefMap()
Fill the reference code mappings for table<->current.
casacore::TableMeasOffsetDesc::isVariable
Bool isVariable() const
Returns True if the offset varies per row.
Definition: TableMeasOffsetDesc.h:176
casacore::TableMeasRefDesc::itsRefCodeColInt
Bool itsRefCodeColInt
Is the reference code column a string column?
Definition: TableMeasRefDesc.h:299
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::TableMeasRefDesc::theirTypesFunc
static TypesFunc * theirTypesFunc
Definition: TableMeasRefDesc.h:291
casacore::TableMeasRefDesc::initTabRef
void initTabRef(const MeasureHolder &measHolder)
Initialize the table reference codes and types and the maps (mapping a code onto itself).
casacore::TableMeasRefDesc::resetRefCode
void resetRefCode(uInt refCode)
Reset the refCode or offset.
casacore::TableMeasOffsetDesc::columnName
const String & columnName() const
Gets the name of the column which stores the variable offset.
Definition: TableMeasOffsetDesc.h:185
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::TableMeasOffsetDesc::getOffset
const Measure & getOffset() const
Get the (non-variable) measure offset for this column.
casacore::TableMeasRefDesc::isRefCodeVariable
Bool isRefCodeVariable() const
Is the reference variable?
Definition: TableMeasRefDesc.h:212
casacore::TableMeasRefDesc::columnName
const String & columnName() const
Return the name of its variable reference code column.
Definition: TableMeasRefDesc.h:216
casacore::TableMeasRefDesc::itsTab2Cur
Block< Int > itsTab2Cur
Definition: TableMeasRefDesc.h:311
casacore::TableMeasRefDesc::hasRefTab
Bool hasRefTab() const
Do the keywords contain the reference codes and types.
Definition: TableMeasRefDesc.h:225
casacore::TableMeasRefDesc::itsTabRefCodes
Vector< uInt > itsTabRefCodes
Definition: TableMeasRefDesc.h:308
casacore::TableMeasRefDesc::itsRefCode
uInt itsRefCode
Definition: TableMeasRefDesc.h:295
casacore::TableMeasRefDesc::writeKeys
void writeKeys(TableRecord &measInfo, const TableMeasDescBase &measDesc)
Write the actual keywords.
casacore::TableMeasRefDesc::cur2tab
uInt cur2tab(uInt curRefCode) const
casacore::TableMeasRefDesc::hasOffset
Bool hasOffset() const
Returns True if the reference has an offset.
Definition: TableMeasRefDesc.h:229
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::TableMeasRefDesc::setTypesFunc
static void setTypesFunc(TypesFunc *func)
Definition: TableMeasRefDesc.h:287
casacore::TableMeasRefDesc::TypesFunc
void TypesFunc(Vector< String > &types, Vector< uInt > &codes, const MeasureHolder &)
Set the function used to get all reference codes for a MeasureHolder.
Definition: TableMeasRefDesc.h:285
casacore::TableMeasRefDesc::~TableMeasRefDesc
~TableMeasRefDesc()
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::Block< Int >
casacore::TableMeasRefDesc::itsTabRefTypes
Vector< String > itsTabRefTypes
Definition: TableMeasRefDesc.h:307
casacore::TableMeasOffsetDesc
Definition of a Measure Offset in a Table.
Definition: TableMeasOffsetDesc.h:145
casacore::Vector
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
casacore::TableMeasRefDesc::TableMeasRefDesc
TableMeasRefDesc(uInt refCode=0)
Define a fixed MeasRef by supplying its reference code Optionally a Measure offset can be specified.