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:47
Templated class for description of table array columns.
Definition: ArrColData.h:40
void registerClass() const
Register the construction function of this class.
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
An abstract base class for table column descriptions.
Definition: BaseColDesc.h:107
BaseColumnDesc * clone() const
Clone this column description to another.
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 ndim() const
Get the number of dimensions.
Definition: BaseColDesc.h:195
virtual PlainColumn * makeColumn(ColumnSet *) const
Create a Column object out of this.
Class to manage a set of table columns.
Definition: ColumnSet.h:93
String className() const
Get the name of this class.
const String & comment() const
Get comment string.
Definition: BaseColDesc.h:173
void show(ostream &os) const
Show the column.
const IPosition & shape() const
Get the predefined shape.
Definition: BaseColDesc.h:200
Int options() const
Get the options.
Definition: BaseColDesc.h:181
virtual void getDesc(AipsIO &)
Get the object.
virtual void putDesc(AipsIO &) const
Put the object.
Base class for a column in a plain table.
Definition: PlainColumn.h:84
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).
const String & name() const
Get the name of the column.
Definition: BaseColDesc.h:138
this file contains all the compiler specific defines
Definition: mainpage.dox:28
ArrayColumnDesc< T > & operator=(const ArrayColumnDesc< T > &)
Assignment (copy semantics);.