casacore
RowCopier.h
Go to the documentation of this file.
1 //# RowCopier.h: RowCopier copies part or all of a row from one table to another.
2 //# Copyright (C) 1995,2000
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 
29 #ifndef TABLES_ROWCOPIER_H
30 #define TABLES_ROWCOPIER_H
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Arrays/ArrayFwd.h>
35 #include <casacore/casa/Utilities/CountedPtr.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class Table;
41 class String;
42 class ColumnHolder; //# Only in the .cc file
43 
44 
45 // <summary>
46 // RowCopier copies all or part of a row from one table to another.
47 // </summary>
48 
49 // <use visibility=export>
50 
51 // <reviewed reviewer="Mark Wieringa" date="21Nov94" tests="tRowCopier">
52 // </reviewed>
53 
54 // <prerequisite>
55 // <li> Table
56 // </prerequisite>
57 
58 // <etymology>
59 // RowCopier is a class that copies rows from one table to another, hence
60 // the name.
61 // </etymology>
62 
63 // <synopsis>
64 // The primary organization in a Table is the TableColumn. However, data
65 // is often organized primarily by rows, at least initially (e.g. for an
66 // on-line system, the data will arrive in chunks that are likely to be
67 // individual rows rather than individual columns). RowCopier is used
68 // to copy values in a row from all or some of the columns of one table to
69 // another table.
70 //
71 // Some things to keep in mind:
72 // <ol>
73 // <li> For each column to be copied, the data types and dimensionality
74 // must match.
75 // <li> The input row number need not be the same as the output row number.
76 // <li> The output row number must already exist (i.e. no new rows are created).
77 // <li> The output column name need not be the same as the input column name.
78 // <li> The output column name and input column name, when specified, must
79 // already exist.
80 // <li> The output table and each output column must be writable.
81 // </ol>
82 // </synopsis>
83 
84 // <example>
85 // In the FITS Binary Table extension to Table conversion class, BinTable,
86 // the input FITS file is a stream that must be read sequentially, so the
87 // input arrives row-by-row. Internally, there is a single row table that
88 // is used to hold the values for the current row. To fill a Casacore table
89 // with the data from each row, one creates the output table using the
90 // table descriptor from the input, single-row table and uses RowCopier to
91 // copy the single-row table to the appropriate row of the full table,
92 // refilling the single-row table at each step. This is how that looks
93 // (leaving out some details not important to this example):
94 //
95 // Background:
96 // singleRowTab is a table constisting of a single row. It is filled
97 // from the input FITS classes using the fillRow() member function.
98 // The nrows() member function returns the total number of FITS binary
99 // table rows and currrow() returns the current row number.
100 //
101 // <srcblock>
102 // // Create an empty Table able to hold all remaining FITS rows, including
103 // // the current one and having the same descriptor as singleRowTab
104 // SetupNewTable newTab("FullTable", singleRowTab.getDescriptor(),
105 // Table:New);
106 // Table full(newTab, (nrows() - currrow() + 1));
107 // // create the copier to copy all columns
108 // RowCopier copier(full, singleRowTab);
109 // // loop over all remaining rows
110 // // since full was just created, we start filling it at row 0.
111 // for (rownr_t outRow = 0, fitsRow = currrow(); fitsRow < nrows();
112 // outRow++, fitsRow++) {
113 // // copy the only row from currRowTab (row 0) to the outRow of full
114 // copier.copy(outRow, 0);
115 // // fill the next row of currRowTab
116 // fillRow();
117 // }
118 // </srcblock>
119 //
120 // This example shows how to copy some of the values from one table to
121 // another. This is a contrived example. The input table
122 // has columns named "HSource" and "VSource" along with other columns.
123 // This example places the values from these columns to columns named
124 // "RA (1950)" and "DEC (1950)" in the output table (which also has other
125 // columns). Note that each input column must have the same type and
126 // dimensionality as the corresponding output column.
127 //
128 // <srcblock>
129 // // construct a vector of the input column names to copy and the
130 // // associated output column names
131 // Vector<String> inColNames(2), outColNames(2);
132 // inColNames(0) = "HSource"; outColNames(0) = "RA (1950)"
133 // inColNames(1) = "VSource"; outColNames(1) = "DEC (1950)"
134 //
135 // // construct the copier
136 // RowCopier copier(inTable, outTable, inColNames, outColNames);
137 //
138 // // Copy a row from in to out, obviously a typical use would do
139 // // more than just one row.
140 // copier.copy(outRownr, outRownr-1);
141 // </srcblock>
142 // </example>
143 
144 // <motivation>
145 // See the comments in the synopsis.
146 // </motivation>
147 
148 // <todo asof=$DATE:$">
149 // <li> resize should probably happen in powers of 2
150 // <li> is throwing exceptions really what we want to happen?
151 // </todo>
152 
153 
154 class RowCopier {
155 public:
156  // This constructs a copier which will copy all columns which have the
157  // same name in both tables from in to out.
158  // An exception is thrown if the columns having the same name in both
159  // tables are not conformant (not the same type and not both scalar of both
160  // array columns)
161  // <thrown>
162  // <li> TableError
163  // </thrown>
164  RowCopier (Table &out, const Table &in);
165 
166  // This constructs a copier which will copy innames columns to outnames
167  // columns, outnames and innames must be conformant. Columns are
168  // matched up element-by-element in innames and outnames.
169  // An exception is thrown if an element of innames or outnames is not
170  // present in the corresponding table, if innames and outnames are
171  // not conformant and if the corresponding columns are not conformant
172  // (not the same type and not both scalar or both array columns)
173  // <thrown>
174  // <li> TableError
175  // </thrown>
176  RowCopier (Table &out, const Table &in, const Vector<String>& outNames,
177  const Vector<String>& inNames);
178 
179  // The things that actually do the copying when requested.
180  // <group>
181  // Copy different row numbers.
182  Bool copy (rownr_t toRow, rownr_t fromRow);
183  // Copy to and from the same row number
184  Bool copy (rownr_t rownr);
185  // </group>
186 
188 
189 private:
190  //# The following constructors and operator don't seem to be useful
191  // <group>
193  RowCopier(const RowCopier &other);
194  RowCopier &operator=(const RowCopier &other);
195  // </group>
196 
197  // The ColumnHolder class exists only in the .cc file, it is what
198  // ultimately does the work.
200 };
201 
202 
204  { return copy (rownr, rownr); }
205 
206 
207 
208 } //# NAMESPACE CASACORE - END
209 
210 #endif
CountedPtr< ColumnHolder > columns_p
The ColumnHolder class exists only in the.cc file, it is what ultimately does the work.
Definition: RowCopier.h:199
RowCopier(Table &out, const Table &in, const Vector< String > &outNames, const Vector< String > &inNames)
This constructs a copier which will copy innames columns to outnames columns, outnames and innames mu...
Bool copy(rownr_t toRow, rownr_t fromRow)
The things that actually do the copying when requested.
RowCopier(Table &out, const Table &in)
This constructs a copier which will copy all columns which have the same name in both tables from in ...
RowCopier(const RowCopier &other)
RowCopier & operator=(const RowCopier &other)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46