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