casacore
Loading...
Searching...
No Matches
ColumnDesc.h
Go to the documentation of this file.
1//# ColumnDesc.h: an envelope class for column descriptions in tables
2//# Copyright (C) 1994,1995,1996,1997,1998,1999,2000,2001,2016
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_COLUMNDESC_H
29#define TABLES_COLUMNDESC_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/tables/Tables/BaseColDesc.h>
35#include <casacore/casa/BasicSL/String.h>
36#include <casacore/casa/Arrays/IPosition.h>
37
38#include <map>
39#include <mutex>
40
41namespace casacore { //# NAMESPACE CASACORE - BEGIN
42
43// <summary>
44// Envelope class for the description of a table column
45// </summary>
46
47// <use visibility=export>
48
49// <reviewed reviewer="Paul Shannon" date="1994/08/11" tests="none">
50// </reviewed>
51
52// <prerequisite>
53// <li> Tables module (see especially Tables.h, the module header file)
54// <li> Envelope/Letter class design (see J. Coplien, Advanced C++)
55// </prerequisite>
56
57// <synopsis>
58// Class ColumnDesc is an envelope for the letter class BaseColDesc
59// and its derivations like
60// <linkto class="ScalarColumnDesc:description">ScalarColumnDesc</linkto>,
61// <linkto class="ScalarRecordColumnDesc:description">
62// ScalarRecordColumnDesc</linkto>.
63// <linkto class="ArrayColumnDesc:description">ArrayColumnDesc</linkto>, and
64// <linkto class="SubTableDesc:description">SubTableDesc</linkto>.
65// ColumnDesc is meant to examine or slightly modify already existing
66// column descriptions.
67// It allows the retrieval of attributes like name, data type, etc..
68// For non-const ColumnDesc objects it is possible to modify the
69// attributes comment and keyword set.
70//
71// Since there are several types of columns, the class ColumnDesc
72// cannot handle all details of those column types. Therefore,
73// to create a column description, an instance of the specialized
74// classes ArrayColumnDesc<T>, etc. has to be constructed.
75// In there column type dependent things like array shape and
76// default value can be defined.
77//
78// This class also enumerates the possible options which can be used
79// when defining a column via classes like ScalarColumnDesc<T>.
80// These options are:
81// <dl>
82// <dt> FixedShape
83// <dd>
84// This is only useful for columns containing arrays and tables.
85// FixedShape means that the shape of the array or table must
86// be the same in each cell of the column.
87// If not given, the array or table shape may vary.
88// Option Direct forces FixedShape.
89// <dt> Direct
90// <dd>
91// This is only useful for columns containing arrays and tables.
92// Direct means that the data is directly stored in the table.
93// Direct forces option FixedShape.
94// If not given, the array or table is indirect, which implies
95// that the data will be stored in a separate file.
96// <dt> Undefined
97// <dd>
98// Undefined is only useful for scalars. If not given, all possible
99// values of the scalar have a meaning. If given, a value equal to
100// the default value in the column description is an undefined value.
101// The function TableColumn::isDefined will return False for such
102// values.
103// </dl>
104// </synopsis>
105
106// <example>
107// <srcblock>
108// TableDesc tableDesc("theTableDesc", TableDesc::New);
109// // Add a float scalar column.
110// tableDesc.addColumn (ScalarColumnDesc<float> ("NAME");
111// // Get the description of a column and change the comments.
112// // In order to change the comments, a reference must be used
113// // (because the ColumnDesc copy constructor and assign have copy
114// // semantics).
115// ColumnDesc& myColDesc = tableDesc.columnDesc ("aName");
116// myColDesc.comment() += "some more comments";
117// </srcblock>
118// </example>
119
120// <motivation>
121// When getting the description of an arbitrary column, a pointer to
122// that description is needed to allow proper execution of virtual
123// functions.
124// An envelope class is needed to hide this from the user.
125// </motivation>
126
127// <todo asof="$DATE:$">
128//# A List of bugs, limitations, extensions or planned refinements.
129// </todo>
130
131
133{
134friend class ColumnDescSet;
135friend class ColumnSet;
136friend class BaseColumn;
137
138public:
139
140 // Enumerate the possible column options.
141 // They can be combined by adding (logical or-ing) them.
142 enum Option {
143 // direct table or array
145 // undefined values are possible
147 // fixed array/table shape
148 FixedShape=4
149 };
150
151 // Construct from a column description.
152 // This constructor is merely for the purpose of the automatic
153 // conversion of an object like ScalarColumnDesc<T> to
154 // ColumnDesc when adding a column to the table description
155 // using the function TableDesc::addColumn.
157
158 // Copy constructor (copy semantics).
159 ColumnDesc (const ColumnDesc& that);
160
161 // Default constructor (needed for ColumnDescSet).
163 : colPtr_p(0),
165 {}
166
168
169 // Assignment (copy semantics).
171
172 // Comparison.
173 // Two descriptions are equal when their data types, value types
174 // (scalar, array or table) and possible dimensionalities are equal.
175 // <group>
178 // </group>
179
180 // Get access to the set of keywords.
181 // <group>
184 const TableRecord& keywordSet() const
185 { return colPtr_p->keywordSet(); }
186 // </group>
187
188 // Get the name of the column.
189 //# Maybe it can be inlined.
190 const String& name() const;
191
192 // Get the data type of the column.
193 // This always returns the type of a scalar, even when the column
194 // contains arrays.
195 DataType dataType() const
196 { return colPtr_p->dataType(); }
197
198 // Get the true data type of the column.
199 // Unlike dataType, it returns an array data type (e.g. TpArrayInt)
200 // when the column contains arrays.
201 DataType trueDataType() const;
202
203 // Get the type id for non-standard data types (i.e. for TpOther).
204 // For standard data types the returned string is empty.
205 const String& dataTypeId() const
206 { return colPtr_p->dataTypeId(); }
207
208 // Get the type name of the default data manager.
209 const String& dataManagerType() const
210 { return colPtr_p->dataManagerType(); }
211
212 // Get the type name of the default data manager
213 // (allowing it to be changed).
216
217 // Get the data manager group.
219 { return colPtr_p->dataManagerGroup(); }
220
221 // Get the data manager group.
222 // (allowing it to be changed).
225
226 // If <src>always==True</src> they are always set, otherwise only if empty.
229
230 // Get comment string.
231 const String& comment() const
232 { return colPtr_p->comment(); }
233
234 // Get comment string (allowing it to be changed).
236 { return colPtr_p->comment(); }
237
238 // Get the options. The possible options are defined by the enum Option.
239 // E.g.
240 // <srcblock>
241 // const ColumnDesc& coldesc = tableDesc.getColumn ("column_name");
242 // if (coldesc.option() & ColumnDesc::Direct == ColumnDesc::Direct) {
243 // // the column has the Direct flag set
244 // }
245 // </srcblock>
246 int options() const
247 { return colPtr_p->options(); }
248
249 // Check if the column is defined with a fixed shape.
250 // This is always true for scalars. For arrays it is true when
251 // the FixedShape flag was set when the column was defined.
253
254 // Test if column is a scalar.
256 { return colPtr_p->isScalar(); }
257 // Test if column is an array.
258 Bool isArray() const
259 { return colPtr_p->isArray(); }
260 // Test if column is a table.
261 Bool isTable() const
262 { return colPtr_p->isTable(); }
263
264 // Get the number of dimensions.
265 Int ndim() const
266 { return colPtr_p->ndim(); }
267
268 // Get the predefined shape.
269 // If not defined, a zero shape will be returned.
270 const IPosition& shape() const
271 { return colPtr_p->shape(); }
272
273 // Set the number of dimensions.
274 // This is only allowed for arrays.
275 // <src>ndim</src> can be zero to clear the number of dimensions
276 // and the shape.
277 // Otherwise it can only be used if the dimensionality has not been
278 // defined yet.
280 { colPtr_p->setNdim (ndim); }
281
282 // Set the predefined shape.
283 // This is only allowed for arrays, for which the shape
284 // has not been defined yet.
285 // If the dimensionality has already been defined, it must match.
286 // It will set the option <src>FixedShape</src> if not set yet.
287 // <br> The first version leaves the <src>Direct</src> option as is.
288 // The second version sets the <src>Direct</src> option as given.
289 // <group>
291 { colPtr_p->setShape (shape); }
292 void setShape (const IPosition& shape, Bool directOption)
293 { colPtr_p->setShape (shape, directOption); }
294 // </group>
295
296 // Set the options to the given value.
297 // Option <src>ColumnDesc::Direct</src> forces <src>FixedShape</src>.
298 // If <src>FixedShape</src> is not given (implicitly or explicitly),
299 // the column can have no shape, so its shape is cleared.
302
303 // Get the maximum value length.
305 { return colPtr_p->maxLength(); }
306
307 // Set the maximum value length.
308 // So far, this is only possible for columns containing String values.
309 // An exception is thrown if the column data type is not TpString.
310 // Some storage managers support fixed length strings and can store
311 // them more efficiently than variable length strings.
314
315 // Get table description (in case column contains subtables).
316 // <group>
317 const TableDesc* tableDesc() const
318 { return colPtr_p->tableDesc(); }
320 { return colPtr_p->tableDesc(); }
321 // </group>
322
323 // Show the column on cout.
324 void show() const;
325
326 // Show the column.
327 void show (ostream& os) const;
328
329 // Write into AipsIO.
330 friend AipsIO& operator<< (AipsIO& ios, const ColumnDesc& cd);
331
332 // Read from AipsIO.
334
335 // Show on ostream.
336 friend ostream& operator<< (ostream& ios, const ColumnDesc& cd);
337
338 // Set the name of the column.
339 void setName (const String& name)
340 { colPtr_p->setName(name); }
341
342 // Create a RefColumn column object out of this column description.
344 { return colPtr_p->makeRefColumn (rtp, bcp); }
345
346 // Create a ConcatColumn column object out of this column description.
349
350
351 // Define the type of a XXColumnDesc construction function.
352 typedef BaseColumnDesc* ColumnDescCtor (const String& className);
353
354 // Get a construction function for a XXColumnDesc object (thread-safe).
356
357 // Register a "XXColumnDesc" constructor (thread-safe).
358 static void registerCtor (const String& name, ColumnDescCtor* func);
359
360private:
361 // A mutex for additions to the constructor map.
362 static std::mutex theirMutex;
363
364 // Define a map which maps the name of the various XXColumnDesc
365 // classes to a static function constructing them.
366 // This is used when reading a column description back; it in fact
367 // determines the exact column type and is an easier thing to do
368 // than an enormous switch statement.
369 // The map is filled with the main XXColumnDesc construction functions
370 // by the function registerColumnDesc upon the first call of
371 // <src>ColumnDesc::getFile</src>.
372 static std::map<String, ColumnDescCtor*>& getRegisterMap();
373
374 // Register the main data managers.
375 static std::map<String, ColumnDescCtor*> initRegisterMap();
376
377 // Construct from a pointer (for class BaseColumn).
379
380 // Check if a column can be handled by ColumnDescSet.
381 // It is called before the column gets actually added, etc..
382 // <group>
383 // Check if the column can be added to the table description.
384 // It is implemented for a virtual column to check if the columns
385 // it uses really exist.
386 void checkAdd (const ColumnDescSet& cds) const
387 { colPtr_p->checkAdd (cds); }
388 // Check when a column gets renamed in a table description.
389 // It is not used.
390 void checkRename (const ColumnDescSet& cds, const String& newName) const
391 { colPtr_p->checkRename (cds, newName); }
392 // </group>
393
394 // Take action after a column has been handled by ColumnDescSet.
395 // It is called after the column has been actually added, etc..
396 // This gives, for instance, the virtual column class the opportunity
397 // to update the virtual column list.
398 // <group>
400 { colPtr_p->handleAdd (cds); }
401 void handleRename (ColumnDescSet& cds, const String& oldName)
402 { colPtr_p->handleRename (cds, oldName); }
404 { colPtr_p->handleRemove (cds); }
405 // </group>
406
407 // This function allows each column to act upon a rename of another column.
408 // If the old name is used internally, the column can update itself.
409 // It is called after handleRename has been called.
410 void renameAction (const String& newName, const String& oldName)
411 { colPtr_p->renameAction (newName, oldName); }
412
413 // Create a PlainColumn column object out of this column description.
415 { return colPtr_p->makeColumn (csp); }
416
417 // Store the object in AipsIO.
418 void putFile (AipsIO& ios, const TableAttr&) const;
419
420 // Get the object from AipsIO.
421 void getFile (AipsIO&, const TableAttr&);
422
423
424protected:
426 Bool allocated_p; //# False = not allocated -> do not delete
427};
428
429
430} //# NAMESPACE CASACORE - END
431
432#endif
void setMaxLength(uInt maxLength)
Set the maximum value length.
void setNdim(uInt ndim)
Set the number of dimensions.
virtual void checkAdd(const ColumnDescSet &cds) const
Check if a column can be handled by ColumnDescSet.
const String & dataManagerGroup() const
Get the data manager group.
const TableRecord & keywordSet() const
virtual void handleRemove(ColumnDescSet &cds)
virtual void handleRename(ColumnDescSet &cds, const String &oldName)
const IPosition & shape() const
Get the predefined shape.
void setDefaultDataManager(Bool always)
Set the data manager type and group to the default.
Int options() const
Get the options.
TableRecord & rwKeywordSet()
Get access to the set of keywords.
const String & comment() const
Get comment string.
uInt maxLength() const
Get the maximum value length.
Bool isScalar() const
Test if column is scalar, array or table.
virtual void handleAdd(ColumnDescSet &cds)
Take action after a column has been handled by ColumnDescSet.
void setName(const String &name)
Set the name of the column (for a rename).
virtual PlainColumn * makeColumn(ColumnSet *) const =0
Make a PlainColumn object out of the description.
virtual void checkRename(const ColumnDescSet &cds, const String &newName) const
const String & dataTypeId() const
Get the type id for non-standard data types (i.e.
void setOptions(Int options)
Set the options to the given value.
virtual ConcatColumn * makeConcatColumn(ConcatTable *) const
Make a ConcatColumn object out of the description.
RefColumn * makeRefColumn(RefTable *, BaseColumn *) const
Make a RefColumn object out of the description.
void setShape(const IPosition &shape)
Set the predefined shape.
Int ndim() const
Get the number of dimensions.
const TableDesc * tableDesc() const
Get table description (in case column contains subtables).
virtual void renameAction(const String &newName, const String &oldName)
This function allows each column to act upon a rename of another column.
DataType dataType() const
Get the data type of the column.
const String & dataManagerType() const
Get the type name of the default data manager.
String & comment()
Get comment string (allowing it to be changed).
Definition ColumnDesc.h:235
RefColumn * makeRefColumn(RefTable *rtp, BaseColumn *bcp) const
Create a RefColumn column object out of this column description.
Definition ColumnDesc.h:343
void setName(const String &name)
Set the name of the column.
Definition ColumnDesc.h:339
const String & name() const
Get the name of the column.
DataType trueDataType() const
Get the true data type of the column.
DataType dataType() const
Get the data type of the column.
Definition ColumnDesc.h:195
static std::map< String, ColumnDescCtor * > & getRegisterMap()
Define a map which maps the name of the various XXColumnDesc classes to a static function constructin...
friend AipsIO & operator<<(AipsIO &ios, const ColumnDesc &cd)
Write into AipsIO.
Bool operator==(const ColumnDesc &) const
Comparison.
Bool isFixedShape() const
Check if the column is defined with a fixed shape.
ColumnDesc()
Default constructor (needed for ColumnDescSet).
Definition ColumnDesc.h:162
const IPosition & shape() const
Get the predefined shape.
Definition ColumnDesc.h:270
void checkRename(const ColumnDescSet &cds, const String &newName) const
Check when a column gets renamed in a table description.
Definition ColumnDesc.h:390
void setShape(const IPosition &shape)
Set the predefined shape.
Definition ColumnDesc.h:290
static void registerCtor(const String &name, ColumnDescCtor *func)
Register a "XXColumnDesc" constructor (thread-safe).
BaseColumnDesc * colPtr_p
Definition ColumnDesc.h:425
const String & dataManagerType() const
Get the type name of the default data manager.
Definition ColumnDesc.h:209
void handleRemove(ColumnDescSet &cds)
Definition ColumnDesc.h:403
static std::map< String, ColumnDescCtor * > initRegisterMap()
Register the main data managers.
void getFile(AipsIO &, const TableAttr &)
Get the object from AipsIO.
Bool operator!=(const ColumnDesc &) const
const String & comment() const
Get comment string.
Definition ColumnDesc.h:231
ColumnDesc(const BaseColumnDesc &)
Construct from a column description.
ColumnDesc(BaseColumnDesc *)
Construct from a pointer (for class BaseColumn).
void setShape(const IPosition &shape, Bool directOption)
Definition ColumnDesc.h:292
void setOptions(int options)
Set the options to the given value.
Definition ColumnDesc.h:300
String & dataManagerType()
Get the type name of the default data manager (allowing it to be changed).
Definition ColumnDesc.h:214
void setDefaultDataManager(Bool always=True)
If always==True they are always set, otherwise only if empty.
Definition ColumnDesc.h:227
void show() const
Show the column on cout.
ColumnDesc & operator=(const ColumnDesc &that)
Assignment (copy semantics).
void setNdim(uInt ndim)
Set the number of dimensions.
Definition ColumnDesc.h:279
void handleAdd(ColumnDescSet &cds)
Take action after a column has been handled by ColumnDescSet.
Definition ColumnDesc.h:399
String & dataManagerGroup()
Get the data manager group.
Definition ColumnDesc.h:223
PlainColumn * makeColumn(ColumnSet *csp) const
Create a PlainColumn column object out of this column description.
Definition ColumnDesc.h:414
Option
Enumerate the possible column options.
Definition ColumnDesc.h:142
@ Direct
direct table or array
Definition ColumnDesc.h:144
@ FixedShape
fixed array/table shape
Definition ColumnDesc.h:148
@ Undefined
undefined values are possible
Definition ColumnDesc.h:146
const TableRecord & keywordSet() const
Definition ColumnDesc.h:184
void setMaxLength(uInt maxLength)
Set the maximum value length.
Definition ColumnDesc.h:312
TableRecord & rwKeywordSet()
Get access to the set of keywords.
Definition ColumnDesc.h:182
TableDesc * tableDesc()
Definition ColumnDesc.h:319
void handleRename(ColumnDescSet &cds, const String &oldName)
Definition ColumnDesc.h:401
BaseColumnDesc * ColumnDescCtor(const String &className)
Define the type of a XXColumnDesc construction function.
Definition ColumnDesc.h:352
ConcatColumn * makeConcatColumn(ConcatTable *rtp) const
Create a ConcatColumn column object out of this column description.
Definition ColumnDesc.h:347
static ColumnDescCtor * getCtor(const String &name)
Get a construction function for a XXColumnDesc object (thread-safe).
int options() const
Get the options.
Definition ColumnDesc.h:246
void renameAction(const String &newName, const String &oldName)
This function allows each column to act upon a rename of another column.
Definition ColumnDesc.h:410
void putFile(AipsIO &ios, const TableAttr &) const
Store the object in AipsIO.
ColumnDesc(const ColumnDesc &that)
Copy constructor (copy semantics).
void checkAdd(const ColumnDescSet &cds) const
Check if a column can be handled by ColumnDescSet.
Definition ColumnDesc.h:386
Bool isArray() const
Test if column is an array.
Definition ColumnDesc.h:258
static std::mutex theirMutex
A mutex for additions to the constructor map.
Definition ColumnDesc.h:362
const String & dataTypeId() const
Get the type id for non-standard data types (i.e.
Definition ColumnDesc.h:205
uInt maxLength() const
Get the maximum value length.
Definition ColumnDesc.h:304
Int ndim() const
Get the number of dimensions.
Definition ColumnDesc.h:265
Bool isTable() const
Test if column is a table.
Definition ColumnDesc.h:261
friend AipsIO & operator>>(AipsIO &ios, ColumnDesc &cd)
Read from AipsIO.
Bool isScalar() const
Test if column is a scalar.
Definition ColumnDesc.h:255
void show(ostream &os) const
Show the column.
const TableDesc * tableDesc() const
Get table description (in case column contains subtables).
Definition ColumnDesc.h:317
const String & dataManagerGroup() const
Get the data manager group.
Definition ColumnDesc.h:218
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
const Bool False
Definition aipstype.h:44
unsigned int uInt
Definition aipstype.h:51
int Int
Definition aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
const Bool True
Definition aipstype.h:43