casacore
Loading...
Searching...
No Matches
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
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40class Table;
41class String;
42class 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
155public:
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
189private:
190 //# The following constructors and operator don't seem to be useful
191 // <group>
193 RowCopier(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
Referenced counted pointer for constant data.
Definition CountedPtr.h:81
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 & operator=(const RowCopier &other)
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)
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