00001 //# TableCopy.h: Class with static functions for copying a table 00002 //# Copyright (C) 2001,2002,2003 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef TABLES_TABLECOPY_H 00029 #define TABLES_TABLECOPY_H 00030 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/tables/DataMan/DataManInfo.h> 00035 #include <casacore/tables/Tables/Table.h> 00036 #include <casacore/casa/Arrays/Vector.h> 00037 #include <casacore/casa/Containers/Record.h> 00038 00039 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00040 00041 // <summary> 00042 // Class with static functions for copying a table. 00043 // </summary> 00044 00045 // <use visibility=export> 00046 00047 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests=""> 00048 // </reviewed> 00049 00050 // <prerequisite> 00051 //# Classes you should understand before using this one. 00052 // <li> Table 00053 // </prerequisite> 00054 00055 // <synopsis> 00056 // TableCopy is a class for making a deep copy of a table. 00057 // The table can be a PlainTable or a RefTable. 00058 // It contains the following static functions: 00059 // <ol> 00060 // <li> <src>makeEmptyTable</src> creates a new table using the 00061 // description and storage managers of the input table. 00062 // By default TiledDataStMan (which is more or less obsolete) will 00063 // be replaced by TiledShapeStMan. 00064 // By default the new table contains the same number of rows as the 00065 // existing table. 00066 // <li> <src>copyRows</src> copies the data of one to another table. 00067 // It is possible to specify where to start in the input and output. 00068 // <li> <src>CopyInfo</src> copies the table info data. 00069 // <li> <src>copySubTables</src> copies all the subtables in table and 00070 // column keywords. It is done recursively. 00071 // </ol> 00072 // </synopsis> 00073 00074 //# <todo asof="$DATE:$"> 00075 //# </todo> 00076 00077 00078 class TableCopy 00079 { 00080 public: 00081 // Make an (empty) table with the given description. 00082 // If the description contains no columns, the description of the input 00083 // table is used, so it has the same keywords and columns as the input one. 00084 // The data managers can be given in the dataManagerInfo record. 00085 // If it is empty, the info is taken from the input table. 00086 // <br>Non-writable storage managers (like LofarStMan) are by default replaced 00087 // by StandardStMan. If <src>replaceMSM</src> is set, MemoryStMan is also 00088 // replaced by StandardStMan. 00089 // <br>By default, the TiledDataStMan will be replaced by the TiledShapeStMan. 00090 // <br>By default, the new table has the same nr of rows as the input table. 00091 // If <src>noRows=True</src> is given, it does not contain any row. 00092 static Table makeEmptyTable (const String& newName, 00093 const Record& dataManagerInfo, 00094 const Table& tab, 00095 Table::TableOption option, 00096 Table::EndianFormat endianFormat, 00097 Bool replaceTSM = True, 00098 Bool noRows = False, 00099 const StorageOption& = StorageOption()); 00100 00101 // Make an (empty) memory table with the same layout as the input one. 00102 // It has the same keywords and columns as the input one. 00103 // By default, the new table has the same nr of rows as the input table. 00104 // If <src>noRows=True</src> is given, it does not contain any row. 00105 static Table makeEmptyMemoryTable (const String& newName, 00106 const Table& tab, 00107 Bool noRows = False); 00108 00109 // Copy rows from the input to the output. 00110 // By default all rows will be copied starting at row 0 of the output. 00111 // Rows will be added to the output table as needed. 00112 // The output table will by default be flushed after the rows are copied. 00113 // <br> All columns in Table <src>out</src> will be filled from the 00114 // column with the same name in table <src>in</src>. In principle only 00115 // stored columns will be filled; however if the output table has only 00116 // one column, it can also be a virtual one. 00117 // <group> 00118 static void copyRows (Table& out, const Table& in, Bool flush=True) 00119 { copyRows (out, in, 0, 0, in.nrow(), flush); } 00120 static void copyRows (Table& out, const Table& in, 00121 uInt startout, uInt startin, uInt nrrow, 00122 Bool flush=True); 00123 // </group> 00124 00125 // Copy the table info block from input to output table. 00126 static void copyInfo (Table& out, const Table& in); 00127 00128 // Copy all subtables (in table and column keywords) from input to 00129 // output table. 00130 // Subtables of which the keyword name matches an omit value are skipped. 00131 // Optionally the row contents are not copied. 00132 static void copySubTables (Table& out, const Table& in, Bool noRows=False, 00133 const Block<String>& omit=Block<String>()); 00134 00135 // Copy the subtables in the given keywordset to the output keywordset 00136 // in the table with the given name. 00137 // Subtables of which the keyword name matches an omit value are skipped. 00138 // Optionally the row contents are not copied. 00139 static void copySubTables (TableRecord& outKeys, 00140 const TableRecord& inKeys, 00141 const String& outName, 00142 Table::TableType outType, 00143 const Table& in, 00144 Bool noRows=False, 00145 const Block<String>& omit=Block<String>()); 00146 00147 // Clone a column in the from table to a new column in the to table. 00148 // The new column gets the same table description and data manager as the 00149 // from column. It has to get a unique data manager name. If not given, 00150 // it is the new column name. 00151 static void cloneColumn (const Table& fromTable, 00152 const String& fromColumn, 00153 Table& toTable, 00154 const String& newColumn, 00155 const String& dataManagerName = String()); 00156 // Cloning as above, but the data type is set to the template parameter. 00157 template<typename T> 00158 static void cloneColumnTyped (const Table& fromTable, 00159 const String& fromColumn, 00160 Table& toTable, 00161 const String& newColumn, 00162 const String& dataManagerName = String()); 00163 00164 // Copy the data from one column to another. 00165 // It can be used after function cloneColumn to populate the new column. 00166 // Note that the data types of the column do not need to match; data type 00167 // promotion is done if needed. 00168 // <br>The <src>preserveTileShape</src> argument tells if the original 00169 // tile shape is kept if a tiled data manager is used. If False, the 00170 // default tile shape of the data manager is used. 00171 // <note role=tip> 00172 // Note that a TaQL command can be used to fill a column in any way. 00173 // For example, fill toColumn with the real part of a complex fromColumn: 00174 // <srcblock> 00175 // Block<Table> tables(2); 00176 // tables[0] = toTable; 00177 // tables[1] = fromTable; 00178 // tableCommand ("update $1 set toColumn=real(t2.fromColumn) from $2 t2", 00179 // tables); 00180 // </srcblock> 00181 // When copying a column in a straightforward way, the TaQL way is about 25% 00182 // slower than using the function <src>copyColumnData</src>. 00183 // </note> 00184 static void copyColumnData (const Table& fromTable, 00185 const String& fromColumn, 00186 Table& toTable, 00187 const String& toColumn, 00188 Bool preserveTileShape=True); 00189 00190 // Fill the table column with the given array. 00191 // The template type must match the column data type. 00192 template<typename T> 00193 static void fillArrayColumn (Table& table, const String& column, 00194 const Array<T>& value); 00195 00196 // Fill the table column with the given value. 00197 // If the column contains arrays, the arrays are filled with the value. 00198 // The template type must match the column data type. 00199 template<typename T> 00200 static void fillColumnData (Table& table, const String& column, 00201 const T& value); 00202 // Specialization to handle a C-string correctly. 00203 static void fillColumnData (Table& table, const String& column, 00204 const char* value) 00205 { fillColumnData (table, column, String(value)); } 00206 00207 // Fill the table column with the given value. 00208 // The column must contain arrays. The arrays get the shape of the 00209 // corresponding row in the fromColumn in the fromTable. 00210 // It can be used after function cloneColumn to initialize the new column. 00211 // The template type must match the column data type. 00212 template<typename T> 00213 static void fillColumnData (Table& table, const String& column, 00214 const T& value, 00215 const Table& fromTable, const String& fromColumn, 00216 Bool preserveTileShape=True); 00217 // Specialization to handle a C-string correctly. 00218 static void fillColumnData (Table& table, const String& column, 00219 const char* value, 00220 const Table& fromTable, const String& fromColumn, 00221 Bool preserveTileShape=True) 00222 { fillColumnData (table, column, String(value), fromTable, fromColumn, 00223 preserveTileShape); } 00224 00225 00226 // Replace TiledDataStMan by TiledShapeStMan in the DataManagerInfo record. 00227 // Since TiledShapeStMan does not support ID columns, they are 00228 // adjusted as well in tabDesc and dminfo. 00229 static void adjustTSM (TableDesc& tabDesc, Record& dminfo) 00230 { DataManInfo::adjustTSM (tabDesc, dminfo); } 00231 00232 // Replace non-writable storage managers by StandardStMan. This is needed 00233 // for special storage managers like LofarStMan. 00234 static Record adjustStMan (const Record& dminfo) 00235 { return DataManInfo::adjustStMan (dminfo, "StandardStMan"); } 00236 00237 // Set the data managers of the given column(s) to the given tiled storage 00238 // manager (normally TiledShapeStMan or TiledColumnStMan). 00239 // The columns are combined in a single storage manager, so the function 00240 // has to be called multiple times if, say, one per column is needed. 00241 // The columns already having a tiled storage manager are not changed. 00242 static void setTiledStMan (Record& dminfo, const Vector<String>& columns, 00243 const String& dmType, const String& dmName, 00244 const IPosition& defaultTileShape) 00245 { DataManInfo::setTiledStMan (dminfo, columns, dmType, dmName, 00246 defaultTileShape); } 00247 00248 // Remove the columns from the dminfo record and return a vector with the 00249 // names of the columns actually removed. 00250 // The columns having a data manager matching <src>keepType</src> are not 00251 // removed. Matching means that the beginning of the data manager name 00252 // have to match, so "Tiled" matches all tiled storagemanagers. 00253 static Vector<String> removeDminfoColumns (Record& dminfo, 00254 const Vector<String>& columns, 00255 const String& keepType= String()) 00256 { return DataManInfo::removeDminfoColumns (dminfo, columns, keepType); } 00257 00258 // Adjust the data manager types and groups and the 00259 // hypercolumn definitions to the actual data manager info. 00260 static void adjustDesc (TableDesc& tabDesc, const Record& dminfo) 00261 { DataManInfo::adjustDesc (tabDesc, dminfo); } 00262 00263 private: 00264 static void doCloneColumn (const Table& fromTable, const String& fromColumn, 00265 Table& toTable, const ColumnDesc& newColumn, 00266 const String& dataManagerName); 00267 }; 00268 00269 00270 00271 } //# NAMESPACE CASACORE - END 00272 00273 #ifndef CASACORE_NO_AUTO_TEMPLATES 00274 #include <casacore/tables/Tables/TableCopy.tcc> 00275 #endif //# CASACORE_NO_AUTO_TEMPLATES 00276 #endif