casacore
TableVector.h
Go to the documentation of this file.
1 //# TableVector.h: Templated read/write table column vectors
2 //# Copyright (C) 1994,1995,1996,1999,2000
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_TABLEVECTOR_H
29 #define TABLES_TABLEVECTOR_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/Tables/TVec.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 //# Forward Declarations
38 class Table;
39 class TableColumn;
40 template<class T> class TableVectorHelper;
41 class String;
42 
43 
44 // <summary>
45 // Templated readonly table column vectors
46 // </summary>
47 
48 // <use visibility=export>
49 
50 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
51 // </reviewed>
52 
53 // <prerequisite>
54 //# Classes you should understand before using this one.
55 // <li> Vector
56 // <li> Table
57 // </prerequisite>
58 
59 // <etymology>
60 // TableVector allows to operate on a column in a readonly table as a vector.
61 // </etymology>
62 
63 // <synopsis>
64 // A TableVector object is a read/write view of data in a Table.
65 // This means that the vector data can be changed if the underlying column
66 // is writable.
67 //
68 // Table vectors can be used in the same way as the normal vectors.
69 // They allow to handle a column in a table as a vector.
70 // Many mathematical and logical operations are defined for them
71 // in TabVecMath.h and TabVecLogic.h. In fact, constructors exist
72 // to convert a TableColumn or a Vector object to a TableVector,
73 // so they can often directly be used in a table vector expression.
74 // There are 2 kinds of table vectors:
75 // <ul>
76 // <li> A table vector representing a scalar column in a table.
77 // The data types of the vector and the column must conform.
78 // </li> A temporary vector, which is held in memory.
79 // These are usually the result of operations on table vectors.
80 // </ul>
81 //
82 // TableVector is implemented by referencing the counted TabVecRep object.
83 // A default constructor is defined to allow construction of an array
84 // of TableVector objects. However, it constructs an object not
85 // referencing anything. Functions like operator() will fail (i.e. result
86 // in a segmentation fault) when used on such objects. The functions
87 // isNull and throwIfNull can be used to test on this.
88 // </synopsis>
89 
90 // <example>
91 // <srcblock>
92 // // Create a table vector for column COL1.
93 // Table tab ("Table.data");
94 // TableVector<Int> tabvec(tab, "COL1");
95 // // Multiply it by a constant.
96 // // The result has to be stored in a TableVector,
97 // // since a TableVector cannot be written.
98 // TableVector<Int> temp = 2 * tabvec;
99 // </srcblock>
100 // </example>
101 
102 // <motivation>
103 // It is very useful to be able to handle a column as a vector.
104 // To handle a column in a readonly table, a TableVector class
105 // is needed, otherwise output operations could not be forbidden.
106 // </motivation>
107 
108 // <todo asof="$DATE:$">
109 //# A List of bugs, limitations, extensions or planned refinements.
110 // <li> derive from Lattice one day
111 // <li> support slicing
112 // <li> support table array columns
113 // <li> do we ever need Row vectors?
114 // </todo>
115 
116 
117 template<class T>
119 {
120 public:
121  // The default constructor creates a null table vector.
122  // This does not contain an actual vector and cannot be used until
123  // it references an actual vector (using function reference).
124  // Its sole purpose is to be able to construct an array of TableVectors.
125  // Note that operator(), etc. will cause a segmentation fault
126  // when operating on a null object. It was felt it was too expensive
127  // to test on null over and over again. The user should use the isNull
128  // or throwIfNull function in case of doubt.
130 
131  // Create a read/write table vector from the given table column name.
132  // Only scalar columns are supported.
133  TableVector (const Table&, const String& columnName);
134 
135  // Create a read/write table vector from the given table column.
136  // Only scalar columns are supported.
137  // This constructor converts a TableColumn to a TableVector and
138  // allows the use of TableColumn objects in table vector expressions.
139  TableVector (const TableColumn& column);
140 
141  // Create a table vector from another one (reference semantics)
143 
144  // Create a table vector containing the given Vector (reference semantics).
145  // This constructor converts a Vector to a TableVector and
146  // allows the use of Vector objects in table vector expressions.
148 
149  // Create a table vector containing a Vector with the given length.
151 
152  // Destruct the object.
154 
155  // Assign a table vector to another one (copy semantics).
156  // The vectors must have equal length.
158 
159  // Test if the table vector is null, i.e. has no actual vector.
160  // This is the case if the default constructor has been used.
161  Bool isNull() const;
162 
163  // Throw an exception if the table vector is null, i.e.
164  // if function isNull() is true.
165  void throwIfNull() const;
166 
167  // Make a reference to the table vector of the other TableVector.
168  // It will replace an already existing reference.
169  // It handles null objects correctly.
170  void reference (const TableVector<T>&);
171 
172  // Make a (normal) Vector from a TableVector (copy semantics).
174 
175  // Get the value of a single pixel.
176  T operator() (rownr_t index) const;
177 
178  //# Get a slice.
179 //# TableVector<T> operator() (const NSlice&) const;
180 
181  // Set all elements to a value.
182  // <group>
183  TableVector<T>& operator= (const T&);
184  void set (const T& value);
185  // </group>
186 
187  // Put a value into a single pixel.
188  // <br><src> tabvec(i) = value; </src>
189  void set (rownr_t index, const T& value);
190 
191  // Get nr of dimensions (is always 1).
192  uInt ndim() const;
193 
194  // Get nr of elements (ie. vector length).
195  rownr_t nelements() const;
196 
197  // Test if the shape of the given table vector conforms.
198  Bool conform (const TableVector<T>&) const;
199 
200  // Test if the shape of the given vector conforms.
201  Bool conform (const Vector<T>&) const;
202 
203  // Test if internal state is correct.
204  Bool ok() const;
205 
206 protected:
208 
209  // Destruct the object. It decreases the reference count in the
210  // underlying object.
211  void destruct();
212 
213 public:
214  // Return the TabVecRep reference.
215  TabVecRep<T>& tabVec();
216  const TabVecRep<T>& tabVec() const;
217 
218  // Create a TableVector from a TabVecRep as result of an operation.
220 };
221 
222 
223 template<class T>
225  { return (tabVecPtr_p == 0 ? True : False); }
226 
227 template<class T>
228 inline uInt TableVector<T>::ndim () const
229  { return tabVecPtr_p->ndim(); }
230 
231 template<class T>
233  { return tabVecPtr_p->nelements(); }
234 
235 //# Check if 2 table vectors are conformant.
236 template<class T>
237 inline Bool TableVector<T>::conform (const TableVector<T>& vec) const
238  { return tabVecPtr_p->conform (*vec.tabVecPtr_p); }
239 template<class T>
240 inline Bool TableVector<T>::conform (const Vector<T>& vec) const
241  { return tabVecPtr_p->conform (vec); }
242 
243 //# Get the ith pixel.
244 template<class T>
246  { return tabVecPtr_p->value (index); }
247 
248 //# Return the TabVecRep (for TabVecMath and Logic).
249 template<class T>
251  { return *tabVecPtr_p; }
252 template<class T>
254  { return *tabVecPtr_p; }
255 
256 
257 //# Create a new object as a result of an addition, etc..
258 template<class T>
260  { tabVecPtr_p = vec.link(); }
261 
262 //# Assign a table vector to this one.
263 template<class T>
265 {
266  tabVecPtr_p->assign (that.tabVec());
267  return *this;
268 }
269 
270 template<class T>
271 inline void TableVector<T>::set (rownr_t index, const T& value)
272 {
273  tabVecPtr_p->putVal (index, value);
274 }
275 template<class T>
276 inline void TableVector<T>::set (const T& value)
277 {
278  tabVecPtr_p->set (value);
279 }
280 template<class T>
282 {
283  tabVecPtr_p->set (value);
284  return *this;
285 }
286 
287 
288 } //# NAMESPACE CASACORE - END
289 
290 
291 //# Make old name ROTableVector still available.
292 #define ROTableVector TableVector
293 
294 
295 #ifndef CASACORE_NO_AUTO_TEMPLATES
296 #include <casacore/tables/Tables/TableVector.tcc>
297 #endif //# CASACORE_NO_AUTO_TEMPLATES
298 #endif
String: the storage and methods of handling collections of characters.
Definition: String.h:225
Templated base class for table vectors.
Definition: TVec.h:108
TabVecRep< T > * link()
Increments the reference count.
Definition: TVec.h:197
void reference(const TableVector< T > &)
Make a reference to the table vector of the other TableVector.
TableVector(rownr_t leng)
Create a table vector containing a Vector with the given length.
TabVecRep< T > & tabVec()
Return the TabVecRep reference.
Definition: TableVector.h:253
void throwIfNull() const
Throw an exception if the table vector is null, i.e.
TableVector(const TableVector< T > &)
Create a table vector from another one (reference semantics)
TableVector(const TableColumn &column)
Create a read/write table vector from the given table column.
T operator()(rownr_t index) const
Get the value of a single pixel.
Definition: TableVector.h:245
TableVector()
The default constructor creates a null table vector.
void destruct()
Destruct the object.
uInt ndim() const
Get nr of dimensions (is always 1).
Definition: TableVector.h:228
void set(const T &value)
Definition: TableVector.h:276
TableVector< T > & operator=(const TableVector< T > &)
Assign a table vector to another one (copy semantics).
Definition: TableVector.h:264
Bool isNull() const
Test if the table vector is null, i.e.
Definition: TableVector.h:224
TableVector(const Table &, const String &columnName)
Create a read/write table vector from the given table column name.
TableVector(const Vector< T > &)
Create a table vector containing the given Vector (reference semantics).
TabVecRep< T > * tabVecPtr_p
Definition: TableVector.h:207
Bool ok() const
Test if internal state is correct.
~TableVector()
Destruct the object.
Bool conform(const TableVector< T > &) const
Test if the shape of the given table vector conforms.
Definition: TableVector.h:237
Vector< T > makeVector() const
Make a (normal) Vector from a TableVector (copy semantics).
rownr_t nelements() const
Get nr of elements (ie.
Definition: TableVector.h:232
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
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
const Bool True
Definition: aipstype.h:43
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46