casacore
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 
41 namespace 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 {
134 friend class ColumnDescSet;
135 friend class ColumnSet;
136 friend class BaseColumn;
137 
138 public:
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>
176  Bool operator== (const ColumnDesc&) const;
177  Bool operator!= (const ColumnDesc&) const;
178  // </group>
179 
180  // Get access to the set of keywords.
181  // <group>
183  { return colPtr_p->rwKeywordSet(); }
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).
215  { return colPtr_p->dataManagerType(); }
216 
217  // Get the data manager group.
218  const String& dataManagerGroup() const
219  { return colPtr_p->dataManagerGroup(); }
220 
221  // Get the data manager group.
222  // (allowing it to be changed).
224  { return colPtr_p->dataManagerGroup(); }
225 
226  // If <src>always==True</src> they are always set, otherwise only if empty.
228  { colPtr_p->setDefaultDataManager (always); }
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.
255  Bool isScalar() const
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>
290  void setShape (const IPosition& shape)
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.
300  void setOptions (int options)
301  { colPtr_p->setOptions (options); }
302 
303  // Get the maximum value length.
304  uInt maxLength() const
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.
333  friend AipsIO& operator>> (AipsIO& ios, ColumnDesc& cd);
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.
348  { return colPtr_p->makeConcatColumn (rtp); }
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).
355  static ColumnDescCtor* getCtor (const String& name);
356 
357  // Register a "XXColumnDesc" constructor (thread-safe).
358  static void registerCtor (const String& name, ColumnDescCtor* func);
359 
360 private:
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 
424 protected:
426  Bool allocated_p; //# False = not allocated -> do not delete
427 };
428 
429 
430 } //# NAMESPACE CASACORE - END
431 
432 #endif
const String & dataManagerGroup() const
Get the data manager group.
Definition: BaseColDesc.h:160
const String & dataManagerType() const
Get the type name of the default data manager.
Definition: BaseColDesc.h:151
RefColumn * makeRefColumn(RefTable *, BaseColumn *) const
Make a RefColumn object out of the description.
void setMaxLength(uInt maxLength)
Set the maximum value length.
void setNdim(uInt ndim)
Set the number of dimensions.
const String & comment() const
Get comment string.
Definition: BaseColDesc.h:173
virtual void checkAdd(const ColumnDescSet &cds) const
Check if a column can be handled by ColumnDescSet.
virtual void handleRemove(ColumnDescSet &cds)
virtual void handleRename(ColumnDescSet &cds, const String &oldName)
virtual PlainColumn * makeColumn(ColumnSet *) const =0
Make a PlainColumn object out of the description.
const String & dataTypeId() const
Get the type id for non-standard data types (i.e.
Definition: BaseColDesc.h:147
void setDefaultDataManager(Bool always)
Set the data manager type and group to the default.
Int options() const
Get the options.
Definition: BaseColDesc.h:181
uInt maxLength() const
Get the maximum value length.
Definition: BaseColDesc.h:230
Bool isScalar() const
Test if column is scalar, array or table.
Definition: BaseColDesc.h:186
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).
Definition: BaseColDesc.h:324
virtual void checkRename(const ColumnDescSet &cds, const String &newName) const
virtual ConcatColumn * makeConcatColumn(ConcatTable *) const
Make a ConcatColumn object out of the description.
const IPosition & shape() const
Get the predefined shape.
Definition: BaseColDesc.h:200
void setOptions(Int options)
Set the options to the given value.
void setShape(const IPosition &shape)
Set the predefined shape.
Int ndim() const
Get the number of dimensions.
Definition: BaseColDesc.h:195
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.
Definition: BaseColDesc.h:142
TableRecord & rwKeywordSet()
Get access to the set of keywords.
Definition: BaseColDesc.h:128
const TableRecord & keywordSet() const
Definition: BaseColDesc.h:130
const TableDesc * tableDesc() const
Get table description (in case column contains subtables).
Definition: BaseColDesc.h:244
const String & dataTypeId() const
Get the type id for non-standard data types (i.e.
Definition: ColumnDesc.h:205
static ColumnDescCtor * getCtor(const String &name)
Get a construction function for a XXColumnDesc object (thread-safe).
void setName(const String &name)
Set the name of the column.
Definition: ColumnDesc.h:339
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
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 TableRecord & keywordSet() const
Definition: ColumnDesc.h:184
void checkRename(const ColumnDescSet &cds, const String &newName) const
Check when a column gets renamed in a table description.
Definition: ColumnDesc.h:390
friend AipsIO & operator<<(AipsIO &ios, const ColumnDesc &cd)
Write into AipsIO.
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).
const IPosition & shape() const
Get the predefined shape.
Definition: ColumnDesc.h:270
String & comment()
Get comment string (allowing it to be changed).
Definition: ColumnDesc.h:235
BaseColumnDesc * colPtr_p
Definition: ColumnDesc.h:425
ConcatColumn * makeConcatColumn(ConcatTable *rtp) const
Create a ConcatColumn column object out of this column description.
Definition: ColumnDesc.h:347
void handleRemove(ColumnDescSet &cds)
Definition: ColumnDesc.h:403
TableRecord & rwKeywordSet()
Get access to the set of keywords.
Definition: ColumnDesc.h:182
void getFile(AipsIO &, const TableAttr &)
Get the object from AipsIO.
Bool operator!=(const ColumnDesc &) const
const String & dataManagerType() const
Get the type name of the default data manager.
Definition: ColumnDesc.h:209
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.
const TableDesc * tableDesc() const
Get table description (in case column contains subtables).
Definition: ColumnDesc.h:317
TableDesc * tableDesc()
Definition: ColumnDesc.h:319
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
static std::map< String, ColumnDescCtor * > & getRegisterMap()
Define a map which maps the name of the various XXColumnDesc classes to a static function constructin...
BaseColumnDesc * ColumnDescCtor(const String &className)
Define the type of a XXColumnDesc construction function.
Definition: ColumnDesc.h:352
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 String & dataManagerGroup() const
Get the data manager group.
Definition: ColumnDesc.h:218
void setMaxLength(uInt maxLength)
Set the maximum value length.
Definition: ColumnDesc.h:312
void handleRename(ColumnDescSet &cds, const String &oldName)
Definition: ColumnDesc.h:401
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
const String & comment() const
Get comment string.
Definition: ColumnDesc.h:231
ColumnDesc & operator=(const ColumnDesc &that)
Assignment (copy semantics).
friend AipsIO & operator>>(AipsIO &ios, ColumnDesc &cd)
Read from AipsIO.
PlainColumn * makeColumn(ColumnSet *csp) const
Create a PlainColumn column object out of this column description.
Definition: ColumnDesc.h:414
static std::mutex theirMutex
A mutex for additions to the constructor map.
Definition: ColumnDesc.h:362
uInt maxLength() const
Get the maximum value length.
Definition: ColumnDesc.h:304
static std::map< String, ColumnDescCtor * > initRegisterMap()
Register the main data managers.
Int ndim() const
Get the number of dimensions.
Definition: ColumnDesc.h:265
String & dataManagerGroup()
Get the data manager group.
Definition: ColumnDesc.h:223
const String & name() const
Get the name of the column.
Bool isTable() const
Test if column is a table.
Definition: ColumnDesc.h:261
Bool isScalar() const
Test if column is a scalar.
Definition: ColumnDesc.h:255
RefColumn * makeRefColumn(RefTable *rtp, BaseColumn *bcp) const
Create a RefColumn column object out of this column description.
Definition: ColumnDesc.h:343
void show(ostream &os) const
Show the column.
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