RowCopier.h

Classes

RowCopier -- RowCopier copies all or part of a row from one table to another. (full description)

class RowCopier

Interface

Public Members
RowCopier (Table &out, const Table &in)
RowCopier (Table &out, const Table &in, const Vector<String>& outNames, const Vector<String>& inNames)
Bool copy (uInt toRow, uInt fromRow)
Bool copy (uInt rownr)
~RowCopier()
Private Members
RowCopier()
RowCopier(const RowCopier &other)
RowCopier &operator=(const RowCopier &other)

Description

Review Status

Reviewed By:
Mark Wieringa
Date Reviewed:
21Nov94
Programs:
Tests:

Prerequisite

Etymology

RowCopier is a class that copies rows from one table to another, hence the name.

Synopsis

The primary organization in a Table is the TableColumn. However, data is often organized primarily by rows, at least initially (e.g. for an on-line system, the data will arrive in chunks that are likely to be individual rows rather than individual columns). RowCopier is used to copy values in a row from all or some of the columns of one table to another table.

Some things to keep in mind:

  1. For each column to be copied, the data types and dimensionality must match.
  2. The input row number need not be the same as the output row number.
  3. The output row number must already exist (i.e. no new rows are created).
  4. The output column name need not be the same as the input column name.
  5. The output column name and input column name, when specified, must already exist.
  6. The output table and each output column must be writable.

Example

In the FITS Binary Table extension to Table conversion class, BinTable, the input FITS file is a stream that must be read sequentially, so the input arrives row-by-row. Internally, there is a single row table that is used to hold the values for the current row. To fill an aips++ table with the data from each row, one creates the output table using the table descriptor from the input, single-row table and uses RowCopier to copy the single-row table to the appropriate row of the full table, refilling the single-row table at each step. This is how that looks (leaving out some details not important to this example):

Background: singleRowTab is a table constisting of a single row. It is filled from the input FITS classes using the fillRow() member function. The nrows() member function returns the total number of FITS binary table rows and currrow() returns the current row number. 

    //   Create an empty Table able to hold all remaining FITS rows, including
    //   the current one and having the same descriptor as singleRowTab
       SetupNewTable newTab("FullTable", singleRowTab.getDescriptor(), 
                            Table:New);
       Table full(newTab, (nrows() - currrow() + 1));
    //   create the copier to copy all columns
       RowCopier copier(full, singleRowTab);
       // loop over all remaining rows
       // since full was just created, we start filling it at row 0.
       for (uInt outRow = 0, fitsRow = currrow(); fitsRow < nrows();
            outRow++, fitsRow++) {
           // copy the only row from currRowTab (row 0) to the outRow of full
           copier.copy(outRow, 0);
           // fill the next row of currRowTab
           fillRow();
       }

This example shows how to copy some of the values from one table to another. This is a contrived example. The input table has columns named "HSource" and "VSource" along with other columns. This example places the values from these columns to columns named "RA (1950)" and "DEC (1950)" in the output table (which also has other columns). Note that each input column must have the same type and dimensionality as the corresponding output column. 

  // construct a vector of the input column names to copy and the
  // associated output column names
  Vector<String> inColNames(2), outColNames(2);
  inColNames(0) = "HSource"; outColNames(0) = "RA (1950)"
  inColNames(1) = "VSource"; outColNames(1) = "DEC (1950)"

  // construct the copier
  RowCopier copier(inTable, outTable, inColNames, outColNames);

  // Copy a row from in to out, obviously a typical use would do
  // more than just one row.
  copier.copy(outRownr, outRownr-1);

Motivation

See the comments in the synopsis.

To Do

Member Description

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 to out. An exception is thrown if the columns having the same name in both tables are not conformant (not the same type and not both scalar of both array columns)

Thrown Exceptions

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 must be conformant. Columns are matched up element-by-element in innames and outnames. An exception is thrown if an element of innames or outnames is not present in the corresponding table, if innames and outnames are not conformant and if the corresponding columns are not conformant (not the same type and not both scalar or both array columns)

Thrown Exceptions

Bool copy (uInt toRow, uInt fromRow)

The things that actually do the copying when requested.

Copy different row numbers.

Bool copy (uInt rownr)

The things that actually do the copying when requested.

Copy to and from the same row number

~RowCopier()

RowCopier()
RowCopier(const RowCopier &other)
RowCopier &operator=(const RowCopier &other)