casacore
ScaColDesc.h
Go to the documentation of this file.
1//# ScaColDesc.h: Templated class for description of table scalar columns
2//# Copyright (C) 1994,1995,1996,1997,1998,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_SCACOLDESC_H
29#define TABLES_SCACOLDESC_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/tables/Tables/BaseColDesc.h>
35
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39class PlainColumn;
40class ColumnSet;
41
42
43// <summary>
44// Templated class to define columns of scalars in tables
45// </summary>
46
47// <reviewed reviewer="Gareth Hunt" date="94Nov17" tests="">
48// </reviewed>
49
50// <use visibility=export>
51
52// <prerequisite>
53// <li> BaseColumnDesc
54// <li> TableDesc
55// </prerequisite>
56
57// <etymology>
58// This class builds descriptions of table columns where each cell (which
59// may also be called a row) will hold a scalar value.
60// </etymology>
61
62// <synopsis>
63// ScalarColumnDesc is a templated class for defining a
64// table column containing scalar values.
65// Note that class
66// <linkto class=ScalarRecordColumnDesc>ScalarRecordColumnDesc</linkto>
67// has to be used to define the description of a column containing records.
68// <p>
69// The table values are handled by a data manager. This can be
70// a storage manager to store the values in a file or it can be
71// a virtual column engine to calculate them on-the-fly.
72// Only the basic data types are allowed when storing in a file. These are:
73// Bool, uChar, Short, uShort, Int, uInt, Int64, float, double,
74// Complex, DComplex and String.
75// <p>
76// At table creation time (when a table gets created from a table
77// description), each column needs to be bound to a data manager.
78// If not done explicitly, the table system will bind a column to the
79// default data manager defined in the column description.
80// <p>
81// A scalar column description consists of the following attributes:
82// <ul>
83// <li> Name, which has to be unique and must also be different
84// from possible table keyword names.
85// <li> Data type, which is determined by the template parameter
86// (e.g. ArrayColumnDesc<Int>).
87// <li> A data type id, which tells the unique name of non-standard
88// data types (i.e. for data type == TpOther).
89// <li> Comment, which defaults to an empty string.
90// This serves purely as an informational string for the user.
91// <li> Default value, which is only possible for the standard data types.
92// It defaults to the undefined value defined in ValType.h.
93// When a row gets added to a table, it is possible to
94// initialize the column fields in the row with this default value.
95// <li> Default data manager, which will be used if a column
96// for a newly created table is not explicitly bound to a
97// data manager.
98// <li> Data manager group, which serves 2 purposes.
99// Firstly it can be used in class SetupNewTable to bind a group
100// of columns.
101// Secondly, when the default data managers are used, it
102// allows, for example, to have 2 StandardStMan storage managers.
103// One for one group of columns and one for another group of columns.
104// <li> Options. These are defined in ColumnDesc.h and can be combined
105// by or-ing them.
106// Currently only the Undefined flag applies to scalars.
107// <li> Default keyword set, which defaults to an empty set.
108// When a table column gets created from the description, it gets
109// a copy of this keyword set as its initial keyword set.
110// </ul>
111//
112// There are several constructors, which allow to define most
113// of the above mentioned attributes. Others, like the default keyword
114// set, have to be defined explicitly.
115// <p>
116// This class is derived from BaseColumnDesc, thus the functions
117// in there also apply to this class.
118// <br>
119// Once a column description is setup satisfactorily, it must be added
120// to a table description before it can be used by the table system.
121// </synopsis>
122
123// <example>
124// <srcblock>
125// TableDesc tabDesc("tTableDesc", "1", TableDesc::New);
126//
127// // Add a scalar integer column ac, define keywords for it
128// // and define a default value 0.
129// ScalarColumnDesc<Int> acColumn("ac");
130// acColumn.rwKeywordSet().define ("scale", Complex(0));
131// acColumn.rwKeywordSet().define ("unit", "");
132// acColumn.setDefault (0);
133// tabDesc.addColumn (acColumn);
134//
135// // Add another column, now with data type String..
136// // This can be added directly, because no special things like
137// // keywords or default values have to be set.
138// tabDesc.addColumn (ScalarColumnDesc<String>("name", "comments"));
139// </srcblock>
140// </example>
141
142// <motivation>
143// Several column description classes are needed to allow the user
144// to define attributes which are special for each column type.
145// For scalars the special attribute is the default value.
146// They all have to be templated to support arbitrary data types.
147// </motivation>
148
149// <templating arg=T>
150// <li> Default constructor
151// <li> Copy constructor
152// <li> Assignment operator
153// <li> <src>static String dataTypeId(); // (not needed for builtin types)</src>
154// This should return the unique "name" of the class.
155// </templating>
156
157// <todo asof="$DATE:$">
158//# A List of bugs, limitations, extensions or planned refinements.
159// </todo>
160
161
162template<class T>
164{
165friend class ColumnDesc;
166
167public:
168 // Construct the column with the given name.
169 // The data manager type defaults to the StandardStMan storage manager.
170 // The data manager group defaults to the data manager type.
171 // The possible options are defined in ColumnDesc.h.
172 explicit ScalarColumnDesc (const String& name, int options = 0);
173
174 // Construct the column with the given name and comment.
175 // The data manager type defaults to the StandardStMan storage manager.
176 // The data manager group defaults to the data manager type.
177 // The possible options are defined in ColumnDesc.h.
179 int options = 0);
180
181 // Construct the column with the given name, comment, and
182 // default data manager type and group.
183 // A blank data manager group defaults to the data manager type.
184 // The possible options are defined in ColumnDesc.h.
186 const String& dataManName, const String& dataManGroup,
187 int options = 0);
188
189 // Construct the column with the given name, comment, default
190 // data manager type and group, and default value.
191 // A blank data manager group defaults to the data manager type.
192 // The possible options are defined in ColumnDesc.h.
194 const String& dataManName, const String& dataManGroup,
195 const T& defaultValue, int options = 0);
196
197 // Copy constructor (copy semantics);
199
201
202 // Assignment (copy semantics);
204
205 // Clone this column description.
207
208 // Get the name of this class. It is used by the registration process.
209 // The template argument gets part of the name.
211
212 // Set the default value.
213 void setDefault (const T& defaultValue)
215
216 // Get the default value.
217 const T& defaultValue() const
218 { return defaultVal_p; }
219
220 // Create a Column object out of this.
221 // This is used by class ColumnSet to construct a table column object.
223
224 // Make a ConcatColumn object out of the description.
226
227 // Show the column.
228 void show (ostream& os) const;
229
230 // Register the construction function of this class.
231 void registerClass() const;
232
233 // Create the object from AipsIO (this function is registered).
235
236private:
237 T defaultVal_p; //# default value
238
239 // Put the object.
240 virtual void putDesc (AipsIO&) const;
241
242 // Get the object.
243 virtual void getDesc (AipsIO&);
244};
245
246
247//# Explicitly instantiate these templates in ScaColDesc_tmpl.cc
248 extern template class ScalarColumnDesc<Bool>;
249 extern template class ScalarColumnDesc<Char>;
250 extern template class ScalarColumnDesc<Short>;
251 extern template class ScalarColumnDesc<uShort>;
252 extern template class ScalarColumnDesc<Int>;
253 extern template class ScalarColumnDesc<uInt>;
254 extern template class ScalarColumnDesc<Int64>;
255 extern template class ScalarColumnDesc<Float>;
256 extern template class ScalarColumnDesc<Double>;
257 extern template class ScalarColumnDesc<Complex>;
258 extern template class ScalarColumnDesc<DComplex>;
259 extern template class ScalarColumnDesc<String>;
260
261
262} //# NAMESPACE CASACORE - END
263
264#ifndef CASACORE_NO_AUTO_TEMPLATES
265#include <casacore/tables/Tables/ScaColDesc.tcc>
266#endif //# CASACORE_NO_AUTO_TEMPLATES
267#endif
Int options() const
Get the options.
Definition: BaseColDesc.h:181
const String & comment() const
Get comment string.
Definition: BaseColDesc.h:173
const String & name() const
Get the name of the column.
Definition: BaseColDesc.h:138
ScalarColumnDesc(const String &name, int options=0)
Construct the column with the given name.
virtual void putDesc(AipsIO &) const
Put the object.
String className() const
Get the name of this class.
const T & defaultValue() const
Get the default value.
Definition: ScaColDesc.h:217
ScalarColumnDesc< T > & operator=(const ScalarColumnDesc< T > &)
Assignment (copy semantics);.
void registerClass() const
Register the construction function of this class.
void setDefault(const T &defaultValue)
Set the default value.
Definition: ScaColDesc.h:213
virtual void getDesc(AipsIO &)
Get the object.
ScalarColumnDesc(const String &name, const String &comment, const String &dataManName, const String &dataManGroup, int options=0)
Construct the column with the given name, comment, and default data manager type and group.
virtual ConcatColumn * makeConcatColumn(ConcatTable *) const
Make a ConcatColumn object out of the description.
ScalarColumnDesc(const ScalarColumnDesc< T > &)
Copy constructor (copy semantics);.
ScalarColumnDesc(const String &name, const String &comment, const String &dataManName, const String &dataManGroup, const T &defaultValue, int options=0)
Construct the column with the given name, comment, default data manager type and group,...
BaseColumnDesc * clone() const
Clone this column description.
void show(ostream &os) const
Show the column.
virtual PlainColumn * makeColumn(ColumnSet *) const
Create a Column object out of this.
ScalarColumnDesc(const String &name, const String &comment, int options=0)
Construct the column with the given name and comment.
static BaseColumnDesc * makeDesc(const String &name)
Create the object from AipsIO (this function is registered).
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