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);
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)
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>
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
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.
Bool isArray() const
Returns True if the offset varies per array element.
Bool isVariable() const
Returns True if the offset varies per row.
const Measure & getOffset() const
Get the (non-variable) measure offset for this column.
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.
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)
const String & offsetColumnName() const
Return the name of the Measure offset column.
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
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)
TableMeasRefDesc & operator=(const TableMeasRefDesc &that)
Assignment operator (copy semantics).
TableMeasOffsetDesc * itsOffset
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)
Vector< String > itsTabRefTypes
const Measure & getOffset() const
Return the fixed Measure offset.
static void setTypesFunc(TypesFunc *func)
const String & columnName() const
Return the name of its variable reference code column.
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