casacore
SubTabDesc.h
Go to the documentation of this file.
1//# SubTabDesc.h: Description of columns containing tables
2//# Copyright (C) 1994,1995,1996,1997,1999
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_SUBTABDESC_H
29#define TABLES_SUBTABDESC_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/tables/Tables/BaseColDesc.h>
34
35namespace casacore { //# NAMESPACE CASACORE - BEGIN
36
37//# Forward Declarations
38class PlainColumn;
39class ColumnSet;
40class TableDesc;
41class String;
42class AipsIO;
43
44
45// <summary>
46// Description of columns containing tables
47// </summary>
48
49// <use visibility=export>
50
51// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
52// </reviewed>
53
54// <prerequisite>
55//# Classes you should understand before using this one.
56// <li> TableDesc
57// <li> BaseColumnDesc
58// </prerequisite>
59
60// <etymology>
61// SubTableDesc holds a description of a subtable contained in the
62// columns of the parent table.
63// </etymology>
64
65// <synopsis>
66// SubTableDesc describes a table column containing subtables.
67// The semantics of subtables are described below.
68// The column description is constructed using a table description
69// describing the subtable. This subtable decription or its name is
70// stored with the column description.
71// When a table containing this column gets created, the subtable
72// description gets copied and this copy is thereafter frozen.
73
74// Constructing a column description for a subtable can be done
75// in 3 ways:
76// <ul>
77// <li> It can be constructed with the name of a table description
78// kept in a file. Only this name will be stored with the column
79// description. Only when the table column gets created,
80// it will read the newest version of this table description.
81// This is a completely dynamic way of defining the column.
82// When the subtable description in the file changes, this column
83// in newly created tables gets the latest version.
84// <li> It can be constructed with a given table description.
85// This means that a copy of that description will be made.
86// The frozen subtable description will be stored with the
87// column description.
88// This is a completely static way of defining the column.
89// <li> It can be constructed with a pointer to a table description.
90// This means that a copy will only be made when the column
91// description gets written. Thus changes to the subtable
92// description will as long as possible be reflected in the
93// column description.
94// This is a mix of the first two ways.
95// </ul>
96//
97// A column can be direct or indirect.
98// Direct columns will be written directly in the table file. All cells
99// in the column must have the same description and it is therefore not
100// possible to change a description.
101// The subtables in indirect columns will be stored in separate files.
102// The cells in indirect columns can contain different tables.
103// </synopsis>
104
105// <example>
106// <srcblock>
107// // First build the new description of a subtable.
108// // Define keyword subkey (integer) having value 10.
109// // Define columns ra and dec (double).
110// TableDesc subTableDesc("tTableDesc_sub", "1", TableDesc::New);
111// subTableDesc.keywordSet().keysInt()("subkey") = 10;
112// subTableDesc.addColumn (TpDouble, "ra");
113// subTableDesc.addColumn (TpDouble, "dec");
114//
115// // Now create a new table description
116// TableDesc td("tTableDesc", "1", TableDesc::New);
117//
118// // Add columns containing subtables.
119// // This is done in 3 slighty different ways, which all have
120// // their own (dis)advantages.
121// // This is described in detail at the SubTableDesc constructors.
122// td.addColumn (SubTableDesc("sub1", "subtable by name","tTableDesc_sub"));
123// td.addColumn (SubTableDesc("sub2", "subtable copy", subTableDesc));
124// td.addColumn (SubTableDesc("sub3", "subtable pointer", &subTableDesc));
125// </srcblock>
126// </example>
127
128// <motivation>
129// Several column description classes are needed to allow the user
130// to define attributes which are special for each column type.
131// For columns containing a table this is the table description.
132// </motivation>
133
134// <todo asof="$DATE:$">
135//# A List of bugs, limitations, extensions or planned refinements.
136// <li> Probably only direct table descriptions should be allowed.
137// Indirect arrays can have a shape in the description
138// (although they can have #dim), so tables should behave
139// similarly.
140// </todo>
141
142
144{
145public:
146friend class ColumnDesc;
147
148public:
149 // Construct from a table description with the given name.
150 // The description does not need to exist yet. Only when the
151 // table gets created, the description will be read and must exist.
152 // This means that the table description is not frozen; the most
153 // recent description will be used when creating the column.
154 SubTableDesc (const String& columnName, const String& comment,
155 const String& tableDescName, int options = 0);
156
157 // Construct from the given table description, which will be copied
158 // and frozen.
159 SubTableDesc (const String& columnName, const String& comment,
160 const TableDesc&, int options = 0);
161
162 // Construct from the given table description, which will be used
163 // directly. The description gets frozen when the column is written.
164 // Care should be taken, because the given table description must
165 // not be deleted before the column description gets destructed.
166 SubTableDesc (const String& columnName, const String& comment,
167 TableDesc*, int options = 0);
168
169 // Copy constructor (copy semantics).
171
173
174 // Assignment (copy semantics).
176
177 // Clone this column description to another.
179
180 // Get the table description.
181 // <thrown>
182 // <li> TableNoFile
183 // </thrown>
185
186 // Get the name of this class.
188
189 // Create a Column column object out of this.
190 // This is used by class ColumnSet to construct a table column object.
192
193 // Show the column.
194 void show (ostream& os) const;
195
196 // Create the object from AipsIO (this function is registered).
198
199protected:
200 // Put the object.
201 virtual void putDesc (AipsIO&) const;
202
203 // Get the object.
204 virtual void getDesc (AipsIO&);
205
206private:
207 TableDesc* tabDescPtr_p; //# pointer to Table Description
208 String tabDescTyp_p; //# type of table description
209 Bool byName_p; //# True = TableDesc name is given
210 Bool allocSelf_p; //# True = allocated tdptr itself
211 Bool shallowCopy_p; //# True = make shallow copy
212 //# (is only set when !allocSelf)
213
214 // Read table description (if passed by name).
215 // If the table description is not found, a False value is returned.
217
218 // Handle the addition of the subtable description (clear the flag).
220};
221
222
223
224} //# NAMESPACE CASACORE - END
225
226#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
String: the storage and methods of handling collections of characters.
Definition: String.h:225
SubTableDesc & operator=(const SubTableDesc &)
Assignment (copy semantics).
virtual void putDesc(AipsIO &) const
Put the object.
static BaseColumnDesc * makeDesc(const String &name)
Create the object from AipsIO (this function is registered).
SubTableDesc(const String &columnName, const String &comment, TableDesc *, int options=0)
Construct from the given table description, which will be used directly.
SubTableDesc(const String &columnName, const String &comment, const String &tableDescName, int options=0)
Construct from a table description with the given name.
TableDesc * tabDescPtr_p
Definition: SubTabDesc.h:207
void handleAdd(ColumnDescSet &)
Handle the addition of the subtable description (clear the flag).
TableDesc * tableDesc()
Get the table description.
BaseColumnDesc * clone() const
Clone this column description to another.
SubTableDesc(const SubTableDesc &)
Copy constructor (copy semantics).
SubTableDesc(const String &columnName, const String &comment, const TableDesc &, int options=0)
Construct from the given table description, which will be copied and frozen.
PlainColumn * makeColumn(ColumnSet *) const
Create a Column column object out of this.
String className() const
Get the name of this class.
Bool readTableDesc()
Read table description (if passed by name).
virtual void getDesc(AipsIO &)
Get the object.
void show(ostream &os) const
Show the column.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42