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: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//# $Id$

#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 - END

#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/tables/Tables/TableCopy.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif