casacore
VirtualTaQLColumn.h
Go to the documentation of this file.
1//# VirtualTaQLColumn.h: Virtual column engine based on TaQL
2//# Copyright (C) 2005
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 TABLES_VIRTUALTAQLCOLUMN_H
29#define TABLES_VIRTUALTAQLCOLUMN_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/tables/DataMan/VirtColEng.h>
34#include <casacore/tables/DataMan/DataManager.h>
35#include <casacore/casa/Arrays/IPosition.h>
36
37namespace casacore {
38//# Forward Declarations
39class TableExprNode;
40
41
42// <category lib=aips module="Tables" sect="Virtual Columns">
43// <summary> Virtual scalar column using TaQL</summary>
44// <reviewed reviewer="GvD" date="2004/07/09" tests="">
45//
46// <prerequisite>
47//# Classes you should understand before using this one.
48// <li> VirtualScalarColumn
49// </prerequisite>
50//
51// <synopsis>
52// VirtualTaQLColumn is a virtual column engine to define the contents of a
53// column as a TaQL CALC expression in which possibly other columns are used.
54// It is (of course) only possible to get data from the column; puts cannot
55// be done. See note 199 for a description of TaQL.
56// The TaQL style can be specified (such as 0- or 1-based indexing).
57// <br>
58// The expression result can be a scalar or array of the basic TaQL data types.
59// The column data type has to be conformant with that TaQL type, thus a
60// column of any integer type has to be used for an integer TaQL result.
61// <br>
62// Constant expressions are precalculated and cached making the retrieval of
63// e.g. the full column much faster (factor 4).
64// <br>
65// A possible use for a virtual TaQL column is a column in a MeasurementSet
66// containing a constant value. It could also be used for on-the-fly calculation
67// of J2000 UVW-values or HADEC using an expression such as "derivedmscal.newuvw()"
68// <note role=caution> One has to be careful with deleting columns. If in an
69// existing table a TaQL expression uses a deleted column, the expression
70// cannot be parsed anymore and the table cannot be opened anymore.
71// In the future the Table System will be made more forgiving.
72// </note>
73// </synopsis>
74//
75// <example>
76// The following example creates a table with a few columns.
77// One column is virtual and has a random value if Col3 is true.
78// Otherwise it has value 0.
79// <srcblock>
80// // Create the table description.
81// TableDesc td;
82// td.addColumn (ScalarColumnDesc<DComplex>("Col1"));
83// td.addColumn (ScalarColumnDesc<Int>("Col2"));
84// td.addColumn (ScalarColumnDesc<Bool>("Col3"));
85// td.addColumn (ScalarColumnDesc<Double>("ColVirt"));
86//
87// // Now create a new table from the description.
88// SetupNewTable newTab("tmtest", td, Table::New);
89// // Define the expression of the virtual column and bind the column to it.
90// // The other columns are by default bound to StandardStMan.
91// VirtualTaQLColumn engine("iif(Col3,rand(),0)");
92// newTab.bindColumn("ColVirt", engine);
93// Table tab(newTab);
94// </srcblock>
95// </example>
96
98{
99public:
100
101 // Construct it with the given TaQL expression.
102 VirtualTaQLColumn (const String& expr, const String& style=String());
103
104 // Construct it with the given specification.
106
107 // Destructor is mandatory.
109
110 // Clone the engine object.
111 virtual DataManager* clone() const;
112
113 // Get the data manager specification.
114 virtual Record dataManagerSpec() const;
115
116 // Return the type name of the engine.
117 // (i.e. its class name VirtualTaQLColumn).
118 virtual String dataManagerType() const;
119
120 // Return the name of the class.
122
123 // Register the class name and the static makeObject "constructor".
124 // This will make the engine known to the table system.
125 static void registerClass();
126
127 // Define the "constructor" to construct this engine when a
128 // table is read back.
129 // This "constructor" has to be registered by the user of the engine.
130 // If the engine is commonly used, its registration can be added
131 // into the registerAllCtor function in DataManReg.cc.
132 // This function gets automatically invoked by the table system.
134 const Record& spec);
135
136 // Return the TaQL expression used.
137 const String& expression() const
138 { return itsExpr; }
139
140 // Set the shape of an array in the column.
141 // It is only called (right after the constructor) if the array has
142 // a fixed shape.
143 virtual void setShapeColumn (const IPosition& aShape);
144
145 // Set the maximum length of a 'fixed length' string.
146 // It is only called (right after the constructor) if the string has
147 // a fixed length.
148 virtual void setMaxLength (uInt maxLength);
149
150 // Functions to return column info.
151 // <group>
152 virtual int dataType() const;
153 virtual Bool isWritable() const;
154 virtual uInt ndim (rownr_t rownr);
155 virtual IPosition shape (rownr_t rownr);
156 virtual Bool isShapeDefined (rownr_t rownr);
157 // </group>
158
159private:
160 // Copy is not needed and therefore forbidden (so it is made private).
162
163 // Assignment is not needed and therefore forbidden (so it is made private).
165
166 // Create the column object for the scalar column in this engine.
168 int dataType, const String&);
169
170 // Create the column object for the indirect array column in this engine.
172 int dataType,
173 const String& dataTypeId);
174
175 // Let the engine initialize the object for a new table.
176 // It defines a column keyword holding the expression.
177 virtual void create64 (rownr_t);
178
179 // Prepare compiles the expression.
180 virtual void prepare();
181
182 // Get the scalar value in the given row.
183 // <group>
184 virtual void getBool (rownr_t rownr, Bool* dataPtr);
185 virtual void getuChar (rownr_t rownr, uChar* dataPtr);
186 virtual void getShort (rownr_t rownr, Short* dataPtr);
187 virtual void getuShort (rownr_t rownr, uShort* dataPtr);
188 virtual void getInt (rownr_t rownr, Int* dataPtr);
189 virtual void getuInt (rownr_t rownr, uInt* dataPtr);
190 virtual void getInt64 (rownr_t rownr, Int64* dataPtr);
191 virtual void getfloat (rownr_t rownr, float* dataPtr);
192 virtual void getdouble (rownr_t rownr, double* dataPtr);
193 virtual void getComplex (rownr_t rownr, Complex* dataPtr);
194 virtual void getDComplex (rownr_t rownr, DComplex* dataPtr);
195 virtual void getString (rownr_t rownr, String* dataPtr);
196 // </group>
197
198 // Get the array value in the given row.
199 // The array given by <src>arr</src> has to have the correct shape
200 // (which is guaranteed by the ArrayColumn get function).
201 virtual void getArrayV (rownr_t rownr, ArrayBase& arr);
202
203 // Get the array result into itsCurArray.
204 void getResult (rownr_t rownr);
205
206 // Make the result cache.
208
209 // Get functions implemented by means of their DataManagerColumn::getXXBase
210 // counterparts, but optimized for constant expressions.
211 // <group>
212 virtual void getScalarColumnV (ArrayBase& arr);
213 virtual void getScalarColumnCellsV (const RefRows& rownrs,
214 ArrayBase& arr);
215 // </group>
216
217 // Fill the ColumnCache object with a constant scalar value.
219
220 // Fill an array with a constant scalar value.
221 void fillArray (ArrayBase& data);
222
223 //# Now define the data members.
226 Bool itsIsConst; //# Constant expression?
229 String itsExpr; //# TaQL expression
230 String itsStyle; //# TaQL style
231 TableExprNode* itsNode; //# compiled TaQL expression
232 IPosition itsShape; //# The shape of the column.
233 uInt itsMaxLen; //# The maximum length of a 'fixed length' string.
234 union {
235 Bool itsBool; //# Constant scalar values
244 };
248 ArrayBase* itsCurArray; //# array value (constant or in itsCurRow)
249 rownr_t itsCurRow; //# row of current array value
250};
251
252
253} //end namespace casacore
254
255#endif
Non-templated base class for templated Array class.
Definition: ArrayBase.h:73
const String & columnName() const
Get rhe column name.
virtual String dataTypeId() const
Get the data type id of the column for dataType==TpOther.
Abstract base class for a data manager.
Definition: DataManager.h:221
virtual String dataManagerName() const
Return the name of the data manager.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual void getuInt(rownr_t rownr, uInt *dataPtr)
virtual void getScalarColumnV(ArrayBase &arr)
Get functions implemented by means of their DataManagerColumn::getXXBase counterparts,...
virtual void getInt64(rownr_t rownr, Int64 *dataPtr)
virtual void getuChar(rownr_t rownr, uChar *dataPtr)
void makeCurArray()
Make the result cache.
static DataManager * makeObject(const String &dataManagerName, const Record &spec)
Define the "constructor" to construct this engine when a table is read back.
virtual Bool isShapeDefined(rownr_t rownr)
Is the value shape defined in the given row? By default it returns True.
virtual ~VirtualTaQLColumn()
Destructor is mandatory.
virtual DataManager * clone() const
Clone the engine object.
virtual void getBool(rownr_t rownr, Bool *dataPtr)
Get the scalar value in the given row.
virtual void getfloat(rownr_t rownr, float *dataPtr)
virtual void getShort(rownr_t rownr, Short *dataPtr)
virtual void create64(rownr_t)
Let the engine initialize the object for a new table.
VirtualTaQLColumn(const VirtualTaQLColumn &)
Copy is not needed and therefore forbidden (so it is made private).
virtual void getString(rownr_t rownr, String *dataPtr)
virtual uInt ndim(rownr_t rownr)
Get the dimensionality of the item in the given row.
static void registerClass()
Register the class name and the static makeObject "constructor".
void getResult(rownr_t rownr)
Get the array result into itsCurArray.
virtual IPosition shape(rownr_t rownr)
Get the shape of the item in the given row.
virtual void getInt(rownr_t rownr, Int *dataPtr)
void fillArray(ArrayBase &data)
Fill an array with a constant scalar value.
VirtualTaQLColumn(const Record &spec)
Construct it with the given specification.
virtual void getdouble(rownr_t rownr, double *dataPtr)
virtual void prepare()
Prepare compiles the expression.
VirtualTaQLColumn & operator=(const VirtualTaQLColumn &)
Assignment is not needed and therefore forbidden (so it is made private).
virtual void getuShort(rownr_t rownr, uShort *dataPtr)
static String className()
Return the name of the class.
void fillColumnCache()
Fill the ColumnCache object with a constant scalar value.
const String & expression() const
Return the TaQL expression used.
virtual String dataManagerType() const
Return the type name of the engine.
virtual void getDComplex(rownr_t rownr, DComplex *dataPtr)
virtual Bool isWritable() const
Test if data can be put into this column.
virtual void getComplex(rownr_t rownr, Complex *dataPtr)
virtual DataManagerColumn * makeIndArrColumn(const String &columnName, int dataType, const String &dataTypeId)
Create the column object for the indirect array column in this engine.
VirtualTaQLColumn(const String &expr, const String &style=String())
Construct it with the given TaQL expression.
virtual void setMaxLength(uInt maxLength)
Set the maximum length of a 'fixed length' string.
virtual void getScalarColumnCellsV(const RefRows &rownrs, ArrayBase &arr)
Get some scalar values in the column.
virtual void setShapeColumn(const IPosition &aShape)
Set the shape of an array in the column.
virtual Record dataManagerSpec() const
Get the data manager specification.
virtual void getArrayV(rownr_t rownr, ArrayBase &arr)
Get the array value in the given row.
virtual int dataType() const
Functions to return column info.
virtual DataManagerColumn * makeScalarColumn(const String &columnName, int dataType, const String &)
Create the column object for the scalar column in this engine.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned char uChar
Definition: aipstype.h:47
short Short
Definition: aipstype.h:48
unsigned int uInt
Definition: aipstype.h:51
unsigned short uShort
Definition: aipstype.h:49
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
float Float
Definition: aipstype.h:54
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
double Double
Definition: aipstype.h:55
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46