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 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 class String;
42 class IPosition;
43 template<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 {
204 public:
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 Bool getBool(const Block< Int > &fieldNrs) const
Get a scalar in the given type.
virtual Array< DComplex > getArrayDComplex(const Block< Int > &fieldNrs) const
virtual DComplex getDComplex(const Block< Int > &fieldNrs) const
TableExprData()
Construct it from a row number.
virtual Array< Int64 > getArrayInt(const Block< Int > &fieldNrs) const
virtual IPosition shape(const Block< Int > &fieldNrs) const
Get the shape of the given field.
virtual Array< String > getArrayString(const Block< Int > &fieldNrs) const
virtual Double getDouble(const Block< Int > &fieldNrs) const
virtual String getString(const Block< Int > &fieldNrs) const
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 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