casacore
Loading...
Searching...
No Matches
ArrColDesc.h
Go to the documentation of this file.
1//# ArrColDesc.h: Templated class to describe columns of arrays in tables
2//# Copyright (C) 1994,1995,1996,1997,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_ARRCOLDESC_H
29#define TABLES_ARRCOLDESC_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/tables/Tables/BaseColDesc.h>
34#include <casacore/casa/Arrays/IPosition.h>
35#include <casacore/casa/Arrays/ArrayFwd.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40class PlainColumn;
41class ColumnSet;
42
43
44// <summary>
45// Abstract base class for description of table array columns
46// </summary>
47
48// <use visibility=local>
49
50// <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
51// </reviewed>
52
53// <prerequisite>
54// <li> BaseColumnDesc (and its prerequisites)
55// <li> TableDesc
56// </prerequisite>
57
58// <synopsis>
59// This class contains the common functionality for the templated class
60// ArrayColumnDesc which describes an array column.
61// </synopsis>
62
64{
65public:
66 // Construct with given parameters.
70 DataType, const String& dataTypeId,
72
73 // Copy constructor (copy semantics);
75
77
78 // Assignment (copy semantics);
80
81 // Get the name of this class. It is used by the registration process.
82 // The template argument gets part of the name.
84
85 // Create a Column object out of this.
86 // This is used by class ColumnSet to construct a table column object.
87 virtual PlainColumn* makeColumn (ColumnSet*) const;
88
89 // Show the column.
90 void show (ostream& os) const;
91
92protected:
93 // Put the object.
94 virtual void putDesc (AipsIO&) const;
95
96 // Get the object.
97 virtual void getDesc (AipsIO&);
98};
99
100
101// <summary>
102// Templated class for description of table array columns
103// </summary>
104
105// <use visibility=export>
106
107// <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
108// </reviewed>
109
110// <prerequisite>
111// <li> ArrayColumnDescBase (and its prerequisites)
112// <li> TableDesc
113// </prerequisite>
114
115// <etymology>
116// This class builds descriptions of table columns where each cell (which
117// may also be called a row) will hold an array.
118// </etymology>
119
120// <synopsis>
121// ArrayColumnDesc is a templated class for defining a table column
122// containing arrays.
123//
124// The table values are handled by a data manager. This can be
125// a storage manager to store the values in a file or it can be
126// a virtual column engine to calculate them on-the-fly.
127// Only the basic data types are allowed when storing in a file. These are:
128// Bool, uChar, Short, uShort, Int, uInt, Int64, float, double,
129// Complex, DComplex and String.
130//
131// At table creation time (when a table gets created from a table
132// description), each column needs to be bound to a data manager.
133// If not done explicitly, the table system will bind a column to the
134// default manager defined in the column description.
135//
136// An array column description consists of the following attributes:
137// <ul>
138// <li> Name, which has to be unique and must also be different
139// from possible table keyword names.
140// <li> Data type, which is determined by the template parameter
141// (e.g. ArrayColumnDesc<Int>).
142// <li> A data type id, which tells the unique name of non-standard
143// data types (i.e. for data type == TpOther).
144// <li> Comment, which defaults to the empty string.
145// This serves purely as an informational string for the user.
146// <li> Dimensionality. If given, all arrays in the column need
147// to have that dimensionality.
148// <li> Shape. If given, all arrays in the column need to have
149// that shape.
150// <li> Default data manager, which will be used if a column
151// for a newly created table is not explicitly bound to a
152// datamanager.
153// <li> Data manager group, which serves 2 purposes.
154// Firstly it can be used in class SetupNewTable to bind a group
155// of columns.
156// Secondly, when the default data managers are used, it
157// allows, for example, to have 2 AipsIO storage managers.
158// One for one group of columns and one for another group of columns.
159// <li> Options. These are defined in ColumnDesc.h and can be combined
160// by logically or-ing them.
161// <ol>
162// <li>
163// ColumnDesc::FixedShape says that the arrays in all cells
164// of a column have the same shape. This shape must be defined
165// before a table is created. It does not tell if
166// the array is direct or indirect.
167// A FixedShape array is defined in every cell, while for
168// non-FixedShape arrays a cell can be empty.
169// <li>
170// ColumnDesc::Direct determines if an array is directly
171// stored in the table or if it is stored indirectly in a separate
172// file. Direct arrays enforce the FixedShape option.
173// Usually indirect arrays are only read in on command, while
174// direct arrays are held in memory. So the size of the
175// arrays is an important factor.
176// </ol>
177// <li> Default keyword set, which defaults to an empty set.
178// When a table column gets created from the description, it gets
179// a copy of this keyword set as its initial keyword set.
180// </ul>
181//
182// There are several constructors, which allow the definition of most
183// of the above mentioned attributes. Others, like the default keyword
184// set, have to be defined explicitly.
185//
186// This class is derived from ArrayColumnDescBase, thus the functions
187// in there also apply to this class.
188//
189// Once a column description is set up satisfactorily, it must be added
190// to a table description before it can be used by the table system.
191// </synopsis>
192
193// <example>
194// <srcblock>
195// TableDesc tabDesc("tTableDesc", "1", TableDesc::New);
196//
197// // Now define array columns.
198// // This one is indirect and has no dimensionality mentioned yet.
199// // Define the keyword UNIT in it.
200// ArrayColumnDesc<Complex> arr1Column("Arr1", "comment for Arr1");
201// arr1Column.rwKeywordSet().define ("UNIT", "Jy");
202// tabDesc.addColumn (arr1Column);
203//
204// // This one is indirect and has 3-dim arrays.
205// tabDesc.addColumn (ArrayColumnDesc<Int>("Arr2",
206// "comment for Arr2",
207// 3));
208// // This one is direct and has 2-dim arrays with axis lengths 4 and 7.
209// tabDesc.addColumn (ArrayColumnDesc<uInt>("Arr3",
210// "comment for Arr1",
211// IPosition(2,4,7),
212// ColumnDesc::Direct));
213// </srcblock>
214// </example>
215
216// <motivation>
217// Several column description classes are needed to allow the user
218// to define attributes which are special for each column type.
219// For scalars the special attribute is the default value.
220// They all have to be templated to support arbitrary data types.
221// </motivation>
222
223// <templating arg=T>
224// <li> Default constructor
225// <li> Copy constructor
226// <li> Assignment operator
227// <li> <src>static String dataTypeId(); // (not needed for builtin types)</src>
228// This should return the unique "name" of the class.
229// </templating>
230
231//# <todo asof="$DATE:$">
232//# A List of bugs, limitations, extensions or planned refinements.
233//# </todo>
234
235template<class T>
237{
238friend class ColumnDesc;
239
240public:
241 // Construct the column with the given name and dimensionality.
242 // The data manager type defaults to the StandardStman storage manager.
243 // The data manager group defaults to the data manager type.
244 // Ndim <=0 means that the number of dimensions is free and will
245 // be defined when creating the table (rows). Ndim>0 means that
246 // the arrays in this column must have the given dimensionality.
247 // The possible options are defined in ColumnDesc.h.
248 explicit ArrayColumnDesc (const String& name, Int ndim = -1,
249 int options = 0);
250
251 // Construct the column with the given name, dimensionality, and comment.
252 // The data manager type defaults to the StandardStman storage manager.
253 // The data manager group defaults to the data manager type.
254 // Ndim <=0 means that the number of dimensions is free and will
255 // be defined when creating the table (rows). Ndim>0 means that
256 // the arrays in this column must have the given dimensionality.
257 // The possible options are defined in ColumnDesc.h.
259 Int ndim = -1, int options = 0);
260
261 // Construct the column with the given name, dimensionality, comment,
262 // and default data manager type and group.
263 // A blank data manager group defaults to the data manager type.
264 // Ndim <=0 means that the number of dimensions is free and will
265 // be defined when creating the table (rows). Ndim>0 means that
266 // the arrays in this column must have the given dimensionality.
267 // The possible options are defined in ColumnDesc.h.
269 const String& dataManName, const String& dataManGroup,
270 Int ndim = -1, int options = 0);
271
272 // Construct the column with the given name and shape.
273 // The data manager type defaults to the StandardStman storage manager.
274 // The data manager group defaults to the data manager type.
275 // The possible options are defined in ColumnDesc.h.
276 // This constructor can only be used for FixedShape arrays, because the
277 // shape of other arrays can only be set per row.
279 const IPosition& shape, int options = 0);
280
281 // Construct the column with the given name, shape, and comment.
282 // The data manager type defaults to the StandardStman storage manager.
283 // The data manager group defaults to the data manager type.
284 // The possible options are defined in ColumnDesc.h.
285 // This constructor can only be used for FixedShape arrays, because the
286 // shape of other arrays can only be set per row.
288 const IPosition& shape, int options = 0);
289
290 // Construct the column with the given name, shape, comment,
291 // and default data manager type and group.
292 // A blank data manager group defaults to the data manager type.
293 // The possible options are defined in ColumnDesc.h.
294 // This constructor can only be used for FixedShape arrays, because the
295 // shape of other arrays can only be set per row.
296 // If both ndim and shape are given as > 0, ndim should match the length
297 // of shape.
299 const String& dataManName, const String& dataManGroup,
300 const IPosition& shape, int options = 0, int ndim=-1);
301
302 // Copy constructor (copy semantics);
304
306
307 // Assignment (copy semantics);
309
310 // Clone this column description to another.
312
313 // Register the construction function of this class.
314 void registerClass() const;
315
316 // Create the object from AipsIO (this function is registered).
318};
319
320
321//# Explicitly instantiate these templates in ArrColDesc_tmpl.cc
322 extern template class ArrayColumnDesc<Bool>;
323 extern template class ArrayColumnDesc<Char>;
324 extern template class ArrayColumnDesc<Short>;
325 extern template class ArrayColumnDesc<uShort>;
326 extern template class ArrayColumnDesc<Int>;
327 extern template class ArrayColumnDesc<uInt>;
328 extern template class ArrayColumnDesc<Int64>;
329 extern template class ArrayColumnDesc<Float>;
330 extern template class ArrayColumnDesc<Double>;
331 extern template class ArrayColumnDesc<Complex>;
332 extern template class ArrayColumnDesc<DComplex>;
333 extern template class ArrayColumnDesc<String>;
334
335
336} //# NAMESPACE CASACORE - END
337
338#ifndef CASACORE_NO_AUTO_TEMPLATES
339#include <casacore/tables/Tables/ArrColDesc.tcc>
340#endif //# CASACORE_NO_AUTO_TEMPLATES
341#endif
virtual PlainColumn * makeColumn(ColumnSet *) const
Create a Column object out of this.
virtual void putDesc(AipsIO &) const
Put the object.
ArrayColumnDescBase(const String &name, const String &comment, const String &dataManagerType, const String &dataManagerGroup, DataType, const String &dataTypeId, Int options, uInt ndim, const IPosition &shape)
Construct with given parameters.
void show(ostream &os) const
Show the column.
virtual void getDesc(AipsIO &)
Get the object.
ArrayColumnDescBase & operator=(const ArrayColumnDescBase &)
Assignment (copy semantics);.
ArrayColumnDescBase(const ArrayColumnDescBase &)
Copy constructor (copy semantics);.
String className() const
Get the name of this class.
Templated class for description of table array columns.
Definition ArrColDesc.h:237
ArrayColumnDesc(const String &name, const String &comment, const IPosition &shape, int options=0)
Construct the column with the given name, shape, and comment.
ArrayColumnDesc(const String &name, const String &comment, Int ndim=-1, int options=0)
Construct the column with the given name, dimensionality, and comment.
BaseColumnDesc * clone() const
Clone this column description to another.
void registerClass() const
Register the construction function of this class.
ArrayColumnDesc(const String &name, const String &comment, const String &dataManName, const String &dataManGroup, Int ndim=-1, int options=0)
Construct the column with the given name, dimensionality, comment, and default data manager type and ...
ArrayColumnDesc< T > & operator=(const ArrayColumnDesc< T > &)
Assignment (copy semantics);.
ArrayColumnDesc(const String &name, const IPosition &shape, int options=0)
Construct the column with the given name and shape.
ArrayColumnDesc(const ArrayColumnDesc< T > &)
Copy constructor (copy semantics);.
static BaseColumnDesc * makeDesc(const String &name)
Create the object from AipsIO (this function is registered).
ArrayColumnDesc(const String &name, const String &comment, const String &dataManName, const String &dataManGroup, const IPosition &shape, int options=0, int ndim=-1)
Construct the column with the given name, shape, comment, and default data manager type and group.
ArrayColumnDesc(const String &name, Int ndim=-1, int options=0)
Construct the column with the given name and dimensionality.
const String & dataManagerGroup() const
Get the data manager group.
const IPosition & shape() const
Get the predefined shape.
Int options() const
Get the options.
const String & comment() const
Get comment string.
const String & dataTypeId() const
Get the type id for non-standard data types (i.e.
const String & name() const
Get the name of the column.
Int ndim() const
Get the number of dimensions.
const String & dataManagerType() const
Get the type name of the default data manager.
String: the storage and methods of handling collections of characters.
Definition String.h:225
this file contains all the compiler specific defines
Definition mainpage.dox:28
unsigned int uInt
Definition aipstype.h:51
int Int
Definition aipstype.h:50