TableCopy.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1