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