casacore
TableExprData.h
Go to the documentation of this file.
1//# TableExprData.h: Abstract base class for data object in a TaQL expression
2//# Copyright (C) 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//#
27//# $Id$
28
29
30#ifndef TABLES_TABLEEXPRDATA_H
31#define TABLES_TABLEEXPRDATA_H
32
33//# Includes
34#include <casacore/casa/aips.h>
35#include <casacore/casa/Utilities/DataType.h>
36#include <casacore/casa/Arrays/ArrayFwd.h>
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward Declarations
41class String;
42class IPosition;
43template<class T> class Block;
44
45
46// <summary>
47// Abstract base class for data object in a TaQL expression.
48// </summary>
49
50// <use visibility=export>
51
52// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
53// </reviewed>
54
55// <prerequisite>
56// <li> <linkto class="TableExprNode">TableExprNode</linkto>.
57// </prerequisite>
58
59// <synopsis>
60// The Table Query Language (TaQL) is implemented by means of the
61// <src>TableExprNode</src> classes. It is primarily meant to do
62// selection on tables. However, it is also possible to use it for
63// selection on any other set of data resembling tabular data.
64// <br>An example of such a data set is a set of
65// <linkto class=Record>Record</linkto> objects. TaQL can be used
66// to select some of those records based on the contents of one or more
67// fields in the records. Note that this example is already directly
68// supported by TaQL.
69// <br>Another example is when a user has several equally long vectors
70// with data. The vectors can be seen as fields and TaQL can be used
71// to select entries from the vectors. This example requires that
72// this class TableExprData is used.
73// <p>
74// The <linkto class=TableExprNodeRecordField>TableExprNodeRecordField</linkto>
75// and <linkto class=TableExprId>TableExprId</linkto> classes form
76// the means by which TaQL can deal with any set of data.
77// <br>First the TaQL expression has to be setup. This is done by
78// constructing a <src>TableExprNodeRecordField</src> object for each
79// 'field' to be used in the expression. <src>TableExprNodeRecordField</src>
80// uses a <linkto class=RecordInterface>RecordInterface</linkto> object
81// to make the data type of a field in the data set known and to
82// map a field name to a field index (the index is the sequence number
83// of the field in the record description).
84// <br>When evaluating the expression for each member in the data set,
85// a <src>TableExprData></src> needs to be passed (which is automatically
86// converted to <linkto class=TableExprId>TableExprId</linkto>).
87// So a class needs to be written to access the data in the data set.
88// It needs to be derived from the abstract base class <src>TableExprData</src>
89// defined in this file. An example is given below.
90// <p>
91// It is also possible that the data set contains records and that
92// the selection is based on fields in those records. In such a case
93// the record passed to <src>TableExprNodeRecordField</src> should contain
94// subrecords representing those records. The field index in the various
95// functions as passed as a <src>Block<Int></src> to denote the fields
96// in the subrecords (and possibly subsubrecords, etc..
97// However, normally records won't be used and <src>fieldNrs[0]</src>
98// gives the field index.
99// </synopsis>
100
101// <example>
102// This example shows how a data set consisting of two vectors
103// of scalars can be used.
104// <srcblock>
105// // Write a class derived from TableExprData to handle the vectors.
106// class MyTestClass : public TableExprData
107// {
108// public:
109// // Constructor checks if both vectors have equal length.
110// MyTestClass (const Vector<Int>& fld1, const Vector<String>& fld2)
111// : itsFld1(fld1), itsFld2(fld2), itsEntry(0)
112// { AlwaysAssert (fld1.nelements() == fld2.nelements(), AipsError); }
113// virtual ~MyTestClass()
114// {}
115// void next()
116// { itsEntry++; }
117// // Note that only the get functions for the possible types are needed.
118// // Also note that all numeric types are handled by TaQL as Double.
119// // The exception should never be thrown unless things are screwed up.
120// virtual Double getDouble (const Block<Int>& fieldNrs) const
121// { switch (fieldNrs[0]) {
122// case 0:
123// return itsFld1(itsEntry);
124// default:
125// throw AipsError();
126// }
127// }
128// virtual String getString (const Block<Int>& fieldNrs) const
129// { switch (fieldNrs[0]) {
130// case 1:
131// return itsFld2(itsEntry);
132// default:
133// throw AipsError();
134// }
135// }
136// virtual DataType dataType (const Block<Int>& fieldNrs) const
137// { switch (fieldNrs[0]) {
138// case 0:
139// return TpInt;
140// case 1:
141// return TpString;
142// default:
143// throw AipsError();
144// }
145// }
146// // Make a Record to give to vectors a name.
147// // The order in which the fields are defined determines the fieldnrs
148// // passed to the get functions.
149// static Record makeRecord()
150// { RecordDesc desc;
151// desc.addField ("fld1", TpInt);
152// desc.addField ("fld2", TpString);
153// return Record(desc);
154// }
155// private:
156// Vector<Int> itsFld1;
157// Vector<String> itsFld2;
158// uInt itsEntry;
159// };
160//
161// Vector<uInt> findMatches (const Vector<Int>& fld1,
162// const Vector<String>& fld2)
163// {
164// // Make some expression.
165// // First create a Record to make the names and types known.
166// Record rec(MyTestClass::makeRecord());
167// TableExprNode expr (makeRecordExpr(rec,"fld1") > 10 &&
168// makeRecordExpr(rec,"fld2") != pattern("*xxx*"));
169// // Now evaluate the expression for each entry in the vector.
170// // Make a MyTestClass object to handle the vectors and put it in
171// // a TableExprId object for the TaQL evaluator.
172// // Note that TableExprId holds a pointer to the original MyTestClass
173// // object, so the TaQL evaluator 'sees' the changes we make by
174// // using the its next() function.
175// MyTestClass subj(fld1, fld2);
176// TableExprId eid(subj);
177// // The matching entry numbers are stored in a vector.
178// Vector<uInt> result(fld1.nelements());
179// uInt nr=0;
180// Bool valb;
181// for (uInt i=0; i<fld1.nelements(); i++) {
182// expr.get (eid, valb);
183// if (valb) {
184// result(nr++) = i;
185// }
186// subj.next(); // Next time the next entry must be used
187// }
188// result.resize (nr, True);
189// return result;
190// }
191// </srcBlock>
192// </example>
193
194// <motivation>
195// This class makes it possible that TaQL can be used in a very versatile way.
196// </motivation>
197
198//# <todo asof="1996/03/12">
199//# </todo>
200
201
203{
204public:
205 // Construct it from a row number.
207 {;}
208
209 virtual ~TableExprData();
210
211 // Get the shape of the given field.
212 // Need only be implemented if there are arrays in the data.
213 // The default implementation returns an empty IPosition.
214 virtual IPosition shape (const Block<Int>& fieldNrs) const;
215
216 // Get the data type of the given field.
217 // Note that TpArray types have to be returned for arrays.
218 // If the field is unknown, TpOther should be returned.
219 // It is used for the isdefined function to check if the field
220 // is really defined.
221 virtual DataType dataType (const Block<Int>& fieldNrs) const = 0;
222
223 // Get a scalar in the given type.
224 // This might involve converting for Double and DComplex.
225 // Most default implementations throws an "not possible" exception.
226 // The default <src>getDouble</src> invokes <src>getInt</src>.
227 // The default <src>getDComplex</src> invokes <src>getDouble</src>.
228 // <group>
229 virtual Bool getBool (const Block<Int>& fieldNrs) const;
230 virtual Int64 getInt (const Block<Int>& fieldNrs) const;
231 virtual Double getDouble (const Block<Int>& fieldNrs) const;
232 virtual DComplex getDComplex (const Block<Int>& fieldNrs) const;
233 virtual String getString (const Block<Int>& fieldNrs) const;
234 // </group>
235
236 // Get an array in the given type.
237 // This might involve converting for Double and DComplex.
238 // Most default implementations throws an "not possible" exception.
239 // The default <src>getArrayDComplex</src> invokes
240 // <src>getArrayDouble</src>.
241 // <group>
242 virtual Array<Bool> getArrayBool (const Block<Int>& fieldNrs) const;
243 virtual Array<Int64> getArrayInt (const Block<Int>& fieldNrs) const;
244 virtual Array<Double> getArrayDouble (const Block<Int>& fieldNrs) const;
245 virtual Array<DComplex> getArrayDComplex (const Block<Int>& fieldNrs) const;
246 virtual Array<String> getArrayString (const Block<Int>& fieldNrs) const;
247 // </group>
248};
249
250
251} //# NAMESPACE CASACORE - END
252
253#endif
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual Int64 getInt(const Block< Int > &fieldNrs) const
virtual Array< Int64 > getArrayInt(const Block< Int > &fieldNrs) const
virtual Bool getBool(const Block< Int > &fieldNrs) const
Get a scalar in the given type.
virtual Array< Bool > getArrayBool(const Block< Int > &fieldNrs) const
Get an array in the given type.
virtual Array< Double > getArrayDouble(const Block< Int > &fieldNrs) const
virtual DComplex getDComplex(const Block< Int > &fieldNrs) const
TableExprData()
Construct it from a row number.
virtual Array< String > getArrayString(const Block< Int > &fieldNrs) const
virtual Array< DComplex > getArrayDComplex(const Block< Int > &fieldNrs) const
virtual IPosition shape(const Block< Int > &fieldNrs) const
Get the shape of the given field.
virtual Double getDouble(const Block< Int > &fieldNrs) const
virtual String getString(const Block< Int > &fieldNrs) const
virtual DataType dataType(const Block< Int > &fieldNrs) const =0
Get the data type of the given field.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
double Double
Definition: aipstype.h:55