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