casacore
TableCopy.h
Go to the documentation of this file.
1 //# TableCopy.h: Class with static functions for copying a table
2 //# Copyright (C) 2001,2002,2003
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_TABLECOPY_H
29 #define TABLES_TABLECOPY_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/DataMan/DataManInfo.h>
35 #include <casacore/tables/Tables/Table.h>
36 #include <casacore/casa/Arrays/Vector.h>
37 #include <casacore/casa/Containers/Record.h>
38 
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 // <summary>
42 // Class with static functions for copying a table.
43 // </summary>
44 
45 // <use visibility=export>
46 
47 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
48 // </reviewed>
49 
50 // <prerequisite>
51 //# Classes you should understand before using this one.
52 // <li> Table
53 // </prerequisite>
54 
55 // <synopsis>
56 // TableCopy is a class for making a deep copy of a table.
57 // The table can be a PlainTable or a RefTable.
58 // It contains the following static functions:
59 // <ol>
60 // <li> <src>makeEmptyTable</src> creates a new table using the
61 // description and storage managers of the input table.
62 // By default TiledDataStMan (which is more or less obsolete) will
63 // be replaced by TiledShapeStMan.
64 // By default the new table contains the same number of rows as the
65 // existing table.
66 // <li> <src>copyRows</src> copies the data of one to another table.
67 // It is possible to specify where to start in the input and output.
68 // <li> <src>CopyInfo</src> copies the table info data.
69 // <li> <src>copySubTables</src> copies all the subtables in table and
70 // column keywords. It is done recursively.
71 // </ol>
72 // </synopsis>
73 
74 //# <todo asof="$DATE:$">
75 //# </todo>
76 
77 
78 class TableCopy
79 {
80 public:
81  // Make an (empty) table with the given description.
82  // If the description contains no columns, the description of the input
83  // table is used, so it has the same keywords and columns as the input one.
84  // The data managers can be given in the dataManagerInfo record.
85  // If it is empty, the info is taken from the input table.
86  // <br>Non-writable storage managers (like LofarStMan) are by default replaced
87  // by StandardStMan. If <src>replaceMSM</src> is set, MemoryStMan is also
88  // replaced by StandardStMan.
89  // <br>By default, the TiledDataStMan will be replaced by the TiledShapeStMan.
90  // <br>By default, the new table has the same nr of rows as the input table.
91  // If <src>noRows=True</src> is given, it does not contain any row.
92  static Table makeEmptyTable (const String& newName,
93  const Record& dataManagerInfo,
94  const Table& tab,
95  Table::TableOption option,
96  Table::EndianFormat endianFormat,
97  Bool replaceTSM = True,
98  Bool noRows = False,
99  const StorageOption& = StorageOption());
100 
101  // Make an (empty) memory table with the same layout as the input one.
102  // It has the same keywords and columns as the input one.
103  // By default, the new table has the same nr of rows as the input table.
104  // If <src>noRows=True</src> is given, it does not contain any row.
105  static Table makeEmptyMemoryTable (const String& newName,
106  const Table& tab,
107  Bool noRows = False);
108 
109  // Copy rows from the input to the output.
110  // By default all rows will be copied starting at row 0 of the output.
111  // Rows will be added to the output table as needed.
112  // The output table will by default be flushed after the rows are copied.
113  // <br> All columns in Table <src>out</src> will be filled from the
114  // column with the same name in table <src>in</src>. In principle only
115  // stored columns will be filled; however if the output table has only
116  // one column, it can also be a virtual one.
117  // <group>
118  static void copyRows (Table& out, const Table& in, Bool flush=True)
119  { copyRows (out, in, 0, 0, in.nrow(), flush); }
120  static void copyRows (Table& out, const Table& in,
121  rownr_t startout, rownr_t startin, rownr_t nrrow,
122  Bool flush=True);
123  // </group>
124 
125  // Copy the table info block from input to output table.
126  static void copyInfo (Table& out, const Table& in);
127 
128  // Copy all subtables (in table and column keywords) from input to
129  // output table.
130  // Subtables of which the keyword name matches an omit value are skipped.
131  // Optionally the row contents are not copied.
132  static void copySubTables (Table& out, const Table& in, Bool noRows=False,
133  const Block<String>& omit=Block<String>());
134 
135  // Copy the subtables in the given keywordset to the output keywordset
136  // in the table with the given name.
137  // Subtables of which the keyword name matches an omit value are skipped.
138  // Optionally the row contents are not copied.
139  static void copySubTables (TableRecord& outKeys,
140  const TableRecord& inKeys,
141  const String& outName,
142  Table::TableType outType,
143  const Table& in,
144  Bool noRows=False,
145  const Block<String>& omit=Block<String>());
146 
147  // Clone a column in the from table to a new column in the to table.
148  // The new column gets the same table description as the source column.
149  // If newdmInfo is empty, the same data manager type as the source column is used.
150  // It has to have a unique data manager name. If not given, it is the new column name.
151  static void cloneColumn (const Table& fromTable,
152  const String& fromColumn,
153  Table& toTable,
154  const String& newColumn,
155  const String& dataManagerName = String(),
156  const Record& newdmInfo = Record());
157 
158  // Cloning as above, but the data type is set to the template parameter.
159  template<typename T>
160  static void cloneColumnTyped (const Table& fromTable,
161  const String& fromColumn,
162  Table& toTable,
163  const String& newColumn,
164  const String& dataManagerName = String(),
165  const Record& newdmInfo = Record());
166 
167  // Copy the data from one column to another.
168  // It can be used after function cloneColumn to populate the new column.
169  // Note that the data types of the column do not need to match; data type
170  // promotion is done if needed.
171  // <br>The <src>preserveTileShape</src> argument tells if the original
172  // tile shape is kept if a tiled data manager is used. If False, the
173  // default tile shape of the data manager is used.
174  // <note role=tip>
175  // Note that a TaQL command can be used to fill a column in any way.
176  // For example, fill toColumn with the real part of a complex fromColumn:
177  // <srcblock>
178  // Block<Table> tables(2);
179  // tables[0] = toTable;
180  // tables[1] = fromTable;
181  // tableCommand ("update $1 set toColumn=real(t2.fromColumn) from $2 t2",
182  // tables);
183  // </srcblock>
184  // When copying a column in a straightforward way, the TaQL way is about 25%
185  // slower than using the function <src>copyColumnData</src>.
186  // </note>
187  static void copyColumnData (const Table& fromTable,
188  const String& fromColumn,
189  Table& toTable,
190  const String& toColumn,
191  Bool preserveTileShape=True);
192 
193  // Fill the table column with the given array.
194  // The template type must match the column data type.
195  template<typename T>
196  static void fillArrayColumn (Table& table, const String& column,
197  const Array<T>& value);
198 
199  // Fill the table column with the given value.
200  // If the column contains arrays, the arrays are filled with the value.
201  // The template type must match the column data type.
202  template<typename T>
203  static void fillColumnData (Table& table, const String& column,
204  const T& value);
205  // Specialization to handle a C-string correctly.
206  static void fillColumnData (Table& table, const String& column,
207  const char* value)
208  { fillColumnData (table, column, String(value)); }
209 
210  // Fill the table column with the given value.
211  // The column must contain arrays. The arrays get the shape of the
212  // corresponding row in the fromColumn in the fromTable.
213  // It can be used after function cloneColumn to initialize the new column.
214  // The template type must match the column data type.
215  template<typename T>
216  static void fillColumnData (Table& table, const String& column,
217  const T& value,
218  const Table& fromTable, const String& fromColumn,
219  Bool preserveTileShape=True);
220  // Specialization to handle a C-string correctly.
221  static void fillColumnData (Table& table, const String& column,
222  const char* value,
223  const Table& fromTable, const String& fromColumn,
224  Bool preserveTileShape=True)
225  { fillColumnData (table, column, String(value), fromTable, fromColumn,
226  preserveTileShape); }
227 
228 private:
229  static void doCloneColumn (const Table& fromTable, const String& fromColumn,
230  Table& toTable, const ColumnDesc& newColumn,
231  const String& dataManagerName,
232  const Record& newdmInfo);
233 };
234 
235 
236 
237 } //# NAMESPACE CASACORE - END
238 
239 #ifndef CASACORE_NO_AUTO_TEMPLATES
240 #include <casacore/tables/Tables/TableCopy.tcc>
241 #endif //# CASACORE_NO_AUTO_TEMPLATES
242 #endif
simple 1-D array
Definition: Block.h:200
String: the storage and methods of handling collections of characters.
Definition: String.h:225
static void fillColumnData(Table &table, const String &column, const T &value, const Table &fromTable, const String &fromColumn, Bool preserveTileShape=True)
Fill the table column with the given value.
static void fillArrayColumn(Table &table, const String &column, const Array< T > &value)
Fill the table column with the given array.
static void copyColumnData(const Table &fromTable, const String &fromColumn, Table &toTable, const String &toColumn, Bool preserveTileShape=True)
Copy the data from one column to another.
static Table makeEmptyMemoryTable(const String &newName, const Table &tab, Bool noRows=False)
Make an (empty) memory table with the same layout as the input one.
static void cloneColumn(const Table &fromTable, const String &fromColumn, Table &toTable, const String &newColumn, const String &dataManagerName=String(), const Record &newdmInfo=Record())
Clone a column in the from table to a new column in the to table.
static Table makeEmptyTable(const String &newName, const Record &dataManagerInfo, const Table &tab, Table::TableOption option, Table::EndianFormat endianFormat, Bool replaceTSM=True, Bool noRows=False, const StorageOption &=StorageOption())
Make an (empty) table with the given description.
static void cloneColumnTyped(const Table &fromTable, const String &fromColumn, Table &toTable, const String &newColumn, const String &dataManagerName=String(), const Record &newdmInfo=Record())
Cloning as above, but the data type is set to the template parameter.
static void copySubTables(TableRecord &outKeys, const TableRecord &inKeys, const String &outName, Table::TableType outType, const Table &in, Bool noRows=False, const Block< String > &omit=Block< String >())
Copy the subtables in the given keywordset to the output keywordset in the table with the given name.
static void copyInfo(Table &out, const Table &in)
Copy the table info block from input to output table.
static void fillColumnData(Table &table, const String &column, const T &value)
Fill the table column with the given value.
static void copyRows(Table &out, const Table &in, rownr_t startout, rownr_t startin, rownr_t nrrow, Bool flush=True)
static void copySubTables(Table &out, const Table &in, Bool noRows=False, const Block< String > &omit=Block< String >())
Copy all subtables (in table and column keywords) from input to output table.
static void fillColumnData(Table &table, const String &column, const char *value, const Table &fromTable, const String &fromColumn, Bool preserveTileShape=True)
Specialization to handle a C-string correctly.
Definition: TableCopy.h:221
static void fillColumnData(Table &table, const String &column, const char *value)
Specialization to handle a C-string correctly.
Definition: TableCopy.h:206
static void doCloneColumn(const Table &fromTable, const String &fromColumn, Table &toTable, const ColumnDesc &newColumn, const String &dataManagerName, const Record &newdmInfo)
static void copyRows(Table &out, const Table &in, Bool flush=True)
Copy rows from the input to the output.
Definition: TableCopy.h:118
EndianFormat
Define the possible endian formats in which table data can be stored.
Definition: Table.h:196
TableOption
Define the possible options how a table can be opened.
Definition: Table.h:172
rownr_t nrow() const
Get the number of rows.
Definition: Table.h:1171
TableType
Define the possible table types.
Definition: Table.h:188
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
const Bool True
Definition: aipstype.h:43
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46