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