TableCopy.h

Go to the documentation of this file.

// # TableCopy.h: Class with static functions for copying a table
// # Copyright (C) 2001,2002,2003
// # Associated Universities, Inc. Washington DC, USA.
// #
// # This library is free software; you can redistribute it and/or modify it
// # under the terms of the GNU Library General Public License as published by
// # the Free Software Foundation; either version 2 of the License, or (at your
// # option) any later version.
// #
// # This library is distributed in the hope that it will be useful, but WITHOUT
// # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
// # License for more details.
// #
// # You should have received a copy of the GNU Library General Public License
// # along with this library; if not, write to the Free Software Foundation,
// # Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
// #
// # Correspondence concerning AIPS++ should be addressed as follows:
// #        Internet email: casa-feedback@nrao.edu.
// #        Postal address: AIPS++ Project Office
// #                        National Radio Astronomy Observatory
// #                        520 Edgemont Road
// #                        Charlottesville, VA 22903-2475 USA
 
#ifndef TABLES_TABLECOPY_H
#define TABLES_TABLECOPY_H
 
// # Includes
#include <casacore/casa/aips.h>
#include <casacore/tables/DataMan/DataManInfo.h>
#include <casacore/tables/Tables/Table.h>
#include <casacore/casa/Arrays/Vector.h>
#include <casacore/casa/Containers/Record.h>
 
namespace casacore {  // # NAMESPACE CASACORE - BEGIN
 
// <summary>
// Class with static functions for copying a table.
// </summary>
 
// <use visibility=export>
 
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
// </reviewed>
 
// <prerequisite>
// # Classes you should understand before using this one.
//   <li> Table
// </prerequisite>
 
// <synopsis>
// TableCopy is a class for making a deep copy of a table.
// The table can be a PlainTable or a RefTable.
// It contains the following static functions:
// <ol>
//  <li> <src>makeEmptyTable</src> creates a new table using the
//       description and storage managers of the input table.
//       By default TiledDataStMan (which is more or less obsolete) will
//       be replaced by TiledShapeStMan.
//       By default the new table contains the same number of rows as the
//       existing table.
//  <li> <src>copyRows</src> copies the data of one to another table.
//       It is possible to specify where to start in the input and output.
//  <li> <src>CopyInfo</src> copies the table info data.
//  <li> <src>copySubTables</src> copies all the subtables in table and
//       column keywords. It is done recursively.
// </ol>
// </synopsis>
 
// # <todo asof="$DATE:$">
// # </todo>
 
class TableCopy {
 public:
  // Make an (empty) table with the given description.
  // If the description contains no columns, the description of the input
  // table is used, so it has the same keywords and columns as the input one.
  // The data managers can be given in the dataManagerInfo record.
  // If it is empty, the info is taken from the input table.
  // <br>Non-writable storage managers (like LofarStMan) are by default replaced
  // by StandardStMan. If <src>replaceMSM</src> is set, MemoryStMan is also
  // replaced by StandardStMan.
  // <br>By default, the TiledDataStMan will be replaced by the TiledShapeStMan.
  // <br>By default, the new table has the same nr of rows as the input table.
  // If <src>noRows=True</src> is given, it does not contain any row.
  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) memory table with the same layout as the input one.
  // It has the same keywords and columns as the input one.
  // By default, the new table has the same nr of rows as the input table.
  // If <src>noRows=True</src> is given, it does not contain any row.
  static Table makeEmptyMemoryTable(const String& newName, const Table& tab, Bool noRows = False);
 
  // Copy rows from the input to the output.
  // By default all rows will be copied starting at row 0 of the output.
  // Rows will be added to the output table as needed.
  // The output table will by default be flushed after the rows are copied.
  // <br> All columns in Table <src>out</src> will be filled from the
  // column with the same name in table <src>in</src>. In principle only
  // stored columns will be filled; however if the output table has only
  // one column, it can also be a virtual one.
  // <group>
  static void copyRows(Table& out, const Table& in, Bool flush = True) {
    copyRows(out, in, 0, 0, in.nrow(), flush);
  }
  static void copyRows(Table& out, const Table& in, rownr_t startout, rownr_t startin,
                       rownr_t nrrow, Bool flush = True);
  // </group>
 
  // Copy the table info block from input to output table.
  static void copyInfo(Table& out, const Table& in);
 
  // Copy all subtables (in table and column keywords) from input to
  // output table.
  // Subtables of which the keyword name matches an omit value are skipped.
  // Optionally the row contents are not copied.
  static void copySubTables(Table& out, 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.
  // Subtables of which the keyword name matches an omit value are skipped.
  // Optionally the row contents are not copied.
  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>());
 
  // Clone a column in the from table to a new column in the to table.
  // The new column gets the same table description as the source column.
  // If newdmInfo is empty, the same data manager type as the source column is used.
  // It has to have a unique data manager name. If not given, it is the new column name.
  static void cloneColumn(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.
  template <typename T>
  static void cloneColumnTyped(const Table& fromTable, const String& fromColumn, Table& toTable,
                               const String& newColumn, const String& dataManagerName = String(),
                               const Record& newdmInfo = Record());
 
  // Copy the data from one column to another.
  // It can be used after function cloneColumn to populate the new column.
  // Note that the data types of the column do not need to match; data type
  // promotion is done if needed.
  // <br>The <src>preserveTileShape</src> argument tells if the original
  // tile shape is kept if a tiled data manager is used. If False, the
  // default tile shape of the data manager is used.
  // <note role=tip>
  // Note that a TaQL command can be used to fill a column in any way.
  // For example, fill toColumn with the real part of a complex fromColumn:
  // <srcblock>
  //   Block<Table> tables(2);
  //   tables[0] = toTable;
  //   tables[1] = fromTable;
  //   tableCommand ("update $1 set toColumn=real(t2.fromColumn) from $2 t2",
  //                 tables);
  // </srcblock>
  // When copying a column in a straightforward way, the TaQL way is about 25%
  // slower than using the function <src>copyColumnData</src>.
  // </note>
  static void copyColumnData(const Table& fromTable, const String& fromColumn, Table& toTable,
                             const String& toColumn, Bool preserveTileShape = True);
 
  // Fill the table column with the given array.
  // The template type must match the column data type.
  template <typename T>
  static void fillArrayColumn(Table& table, const String& column, const Array<T>& value);
 
  // Fill the table column with the given value.
  // If the column contains arrays, the arrays are filled with the value.
  // The template type must match the column data type.
  template <typename T>
  static void fillColumnData(Table& table, const String& column, const T& value);
  // Specialization to handle a C-string correctly.
  static void fillColumnData(Table& table, const String& column, const char* value) {
    fillColumnData(table, column, String(value));
  }
 
  // Fill the table column with the given value.
  // The column must contain arrays. The arrays get the shape of the
  // corresponding row in the fromColumn in the fromTable.
  // It can be used after function cloneColumn to initialize the new column.
  // The template type must match the column data type.
  template <typename T>
  static void fillColumnData(Table& table, const String& column, const T& value,
                             const Table& fromTable, const String& fromColumn,
                             Bool preserveTileShape = True);
  // Specialization to handle a C-string correctly.
  static void fillColumnData(Table& table, const String& column, const char* value,
                             const Table& fromTable, const String& fromColumn,
                             Bool preserveTileShape = True) {
    fillColumnData(table, column, String(value), fromTable, fromColumn, preserveTileShape);
  }
 
 private:
  static void doCloneColumn(const Table& fromTable, const String& fromColumn, Table& toTable,
                            const ColumnDesc& newColumn, const String& dataManagerName,
                            const Record& newdmInfo);
};
 
}  // namespace casacore
 
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/tables/Tables/TableCopy.tcc>
#endif  // # CASACORE_NO_AUTO_TEMPLATES
#endif