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