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 
37 namespace casacore {
38 //# Forward Declarations
39 class 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 {
99 public:
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.
105  VirtualTaQLColumn (const Record& spec);
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.
121  static String className();
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 
159 private:
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.
207  void makeCurArray();
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)
static DataManager * makeObject(const String &dataManagerName, const Record &spec)
Define the "constructor" to construct this engine when a table is read back.
virtual void getuChar(rownr_t rownr, uChar *dataPtr)
void makeCurArray()
Make the result cache.
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 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 DataManager * clone() const
Clone the engine object.
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.
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.
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)
const String & expression() const
Return the TaQL expression used.
VirtualTaQLColumn(const String &expr, const String &style=String())
Construct it with the given TaQL expression.
VirtualTaQLColumn & operator=(const VirtualTaQLColumn &)
Assignment is not needed and therefore forbidden (so it is made private).
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 * makeIndArrColumn(const String &columnName, int dataType, const String &dataTypeId)
Create the column object for the indirect array column in this engine.
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