RowCopier.h

Go to the documentation of this file.
00001 //# RowCopier.h: RowCopier copies part or all of a row from one table to another.
00002 //# Copyright (C) 1995,2000
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 
00029 #ifndef TABLES_ROWCOPIER_H
00030 #define TABLES_ROWCOPIER_H
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/casa/Utilities/CountedPtr.h>
00035 
00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00037 
00038 //# Forward Declarations
00039 class Table;
00040 template<class T> class Vector;
00041 class String;
00042 class ColumnHolder; //# Only in the .cc file
00043 
00044 
00045 // <summary> 
00046 // RowCopier copies all or part of a row from one table to another.
00047 // </summary>
00048 
00049 // <use visibility=export>
00050 
00051 // <reviewed reviewer="Mark Wieringa" date="21Nov94" tests="tRowCopier">
00052 // </reviewed>
00053 
00054 // <prerequisite>
00055 //  <li> Table
00056 // </prerequisite>
00057 
00058 // <etymology>
00059 // RowCopier is a class that copies rows from one table to another, hence
00060 // the name.
00061 // </etymology>
00062 
00063 // <synopsis>
00064 // The primary organization in a Table is the TableColumn.  However, data
00065 // is often organized primarily by rows, at least initially (e.g. for an
00066 // on-line system, the data will arrive in chunks that are likely to be
00067 // individual rows rather than individual columns).  RowCopier is used 
00068 // to copy values in a row from all or some of the columns of one table to
00069 // another table.
00070 //
00071 // Some things to keep in mind:
00072 // <ol>
00073 // <li> For each column to be copied, the data types and dimensionality 
00074 // must match.
00075 // <li> The input row number need not be the same as the output row number.
00076 // <li> The output row number must already exist (i.e. no new rows are created).
00077 // <li> The output column name need not be the same as the input column name.
00078 // <li> The output column name and input column name, when specified, must 
00079 // already exist.
00080 // <li> The output table and each output column must be writable.
00081 // </ol>
00082 // </synopsis>
00083 
00084 // <example>
00085 // In the FITS Binary Table extension to Table conversion class, BinTable,
00086 // the input FITS file is a stream that must be read sequentially, so the
00087 // input arrives row-by-row.  Internally, there is a single row table that
00088 // is used to hold the values for the current row.  To fill a Casacore table
00089 // with the data from each row, one creates the output table using the
00090 // table descriptor from the input, single-row table and uses RowCopier to
00091 // copy the single-row table to the appropriate row of the full table, 
00092 // refilling the single-row table at each step. This is how that looks
00093 // (leaving out some details not important to this example):
00094 // 
00095 // Background:
00096 //   singleRowTab is a table constisting of a single row.  It is filled
00097 //   from the input FITS classes using the fillRow() member function.
00098 //   The nrows() member function returns the total number of FITS binary
00099 //   table rows and currrow() returns the current row number.
00100 //
00101 // <srcblock>
00102 // //   Create an empty Table able to hold all remaining FITS rows, including
00103 // //   the current one and having the same descriptor as singleRowTab
00104 //    SetupNewTable newTab("FullTable", singleRowTab.getDescriptor(), 
00105 //                         Table:New);
00106 //    Table full(newTab, (nrows() - currrow() + 1));
00107 // //   create the copier to copy all columns
00108 //    RowCopier copier(full, singleRowTab);
00109 //    // loop over all remaining rows
00110 //    // since full was just created, we start filling it at row 0.
00111 //    for (uInt outRow = 0, fitsRow = currrow(); fitsRow < nrows();
00112 //         outRow++, fitsRow++) {
00113 //        // copy the only row from currRowTab (row 0) to the outRow of full
00114 //        copier.copy(outRow, 0);
00115 //        // fill the next row of currRowTab
00116 //        fillRow();
00117 //    }
00118 // </srcblock>
00119 //
00120 // This example shows how to copy some of the values from one table to
00121 // another.  This is a contrived example.  The input table 
00122 // has columns named "HSource" and "VSource" along with other columns.
00123 // This example places the values from these columns to columns named
00124 // "RA (1950)" and "DEC (1950)" in the output table (which also has other
00125 // columns).  Note that each input column must have the same type and
00126 // dimensionality as the corresponding output column.  
00127 //  
00128 // <srcblock>
00129 //  // construct a vector of the input column names to copy and the
00130 //  // associated output column names
00131 //  Vector<String> inColNames(2), outColNames(2);
00132 //  inColNames(0) = "HSource"; outColNames(0) = "RA (1950)"
00133 //  inColNames(1) = "VSource"; outColNames(1) = "DEC (1950)"
00134 //
00135 //  // construct the copier
00136 //  RowCopier copier(inTable, outTable, inColNames, outColNames);
00137 //
00138 //  // Copy a row from in to out, obviously a typical use would do
00139 //  // more than just one row.
00140 //  copier.copy(outRownr, outRownr-1);
00141 // </srcblock>
00142 // </example>
00143 
00144 // <motivation>
00145 // See the comments in the synopsis.
00146 // </motivation>
00147 
00148 // <todo asof=$DATE:$">
00149 //  <li> resize should probably happen in powers of 2
00150 //  <li> is throwing exceptions really what we want to happen?
00151 // </todo>
00152 
00153 
00154 class RowCopier {
00155 public:
00156     // This constructs a copier which will copy all columns which have the 
00157     // same name in both tables from in to out.
00158     // An exception is thrown if the columns having the same name in both
00159     // tables are not conformant (not the same type and not both scalar of both
00160     // array columns)
00161     // <thrown>
00162     //  <li> TableError
00163     // </thrown>
00164     RowCopier (Table &out, const Table &in);
00165 
00166     // This constructs a copier which will copy innames columns to outnames 
00167     // columns, outnames and innames must be conformant.  Columns are 
00168     // matched up element-by-element in innames and outnames.
00169     // An exception is thrown if an element of innames or outnames is not
00170     // present in the corresponding table, if innames and outnames are
00171     // not conformant and if the corresponding columns are not conformant
00172     // (not the same type and not both scalar or both array columns)
00173     // <thrown>
00174     //  <li> TableError
00175     // </thrown>
00176     RowCopier (Table &out, const Table &in, const Vector<String>& outNames,
00177                const Vector<String>& inNames);
00178    
00179     // The things that actually do the copying when requested.
00180     // <group>
00181     // Copy different row numbers.
00182     Bool copy (uInt toRow, uInt fromRow);
00183     // Copy to and from the same row number
00184     Bool copy (uInt rownr);
00185     // </group>
00186 
00187     ~RowCopier();
00188 
00189 private:
00190     //# The following constructors and operator don't seem to be useful
00191     // <group>
00192     RowCopier();
00193     RowCopier(const RowCopier &other);
00194     RowCopier &operator=(const RowCopier &other);
00195     // </group>
00196 
00197     // The ColumnHolder class exists only in the .cc file, it is what
00198     // ultimately does the work.
00199     CountedPtr<ColumnHolder> columns_p;
00200 };
00201 
00202 
00203 inline Bool RowCopier::copy (uInt rownr)
00204     { return copy (rownr, rownr); }
00205 
00206 
00207 
00208 } //# NAMESPACE CASACORE - END
00209 
00210 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1