casacore
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 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class PlainColumn;
41 class 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 {
65 public:
66  // Construct with given parameters.
68  const String& dataManagerType,
69  const String& dataManagerGroup,
70  DataType, const String& dataTypeId,
71  Int options, uInt ndim, const IPosition& shape);
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.
83  String className() const;
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 
92 protected:
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 
235 template<class T>
237 {
238 friend class ColumnDesc;
239 
240 public:
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
ArrayColumnDescBase & operator=(const ArrayColumnDescBase &)
Assignment (copy semantics);.
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(const ArrayColumnDescBase &)
Copy constructor (copy semantics);.
String className() const
Get the name of this class.
virtual PlainColumn * makeColumn(ColumnSet *) const
Create a Column object out of this.
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.
void registerClass() const
Register the construction function of this class.
BaseColumnDesc * clone() const
Clone this column description to another.
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 ...
static BaseColumnDesc * makeDesc(const String &name)
Create the object from AipsIO (this function is registered).
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);.
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.
Definition: BaseColDesc.h:160
const String & dataManagerType() const
Get the type name of the default data manager.
Definition: BaseColDesc.h:151
const String & name() const
Get the name of the column.
Definition: BaseColDesc.h:138
const String & comment() const
Get comment string.
Definition: BaseColDesc.h:173
const String & dataTypeId() const
Get the type id for non-standard data types (i.e.
Definition: BaseColDesc.h:147
Int options() const
Get the options.
Definition: BaseColDesc.h:181
const IPosition & shape() const
Get the predefined shape.
Definition: BaseColDesc.h:200
Int ndim() const
Get the number of dimensions.
Definition: BaseColDesc.h:195
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