ArrayQuantColumn.h

The ROArrayQuantColumn class provides read-only access to quanta stored in a array Quantum Table column. The Quantum column should already exist in the table and would have been defined by means of a TableQuantumDesc object. In addition, for a ROArrayQuantColumn object to be useful the column should contain Quanta. Inserting Quanta into a column requires the use of a ArrayQuantColumn object.

The ROArrayQuantColumn class is the array version of the ROScalarQuantColumn class.

Quantum Units

Quanta retrieved from the column will normally have the Unit that was specified when the Quantum column was defined. However, it is possible to override the default column Unit by supplying a Unit in the ROArrayQuantColumn constructor. When constructed in this fashion the retrieved Quanta will by default be retrieved in this unit, i.e. they will by default be converted to this unit.
By giving a unit (as a Unit or Quantum object) to a get function, the data can be retrieved in another unit than the default.

Example

(See TableQuantumDesc class for an example of how to define a Quantum column).

    // Create the column object with default units "deg".
    // It gets the quantum array from row 0 and prints it to stdout.
    ROArrayQuantColumn<Double> roaqCol(qtab, "ArrQuantDouble", "deg");
    cout << roaqCol(0) << endl;
    // This retrieves the same array with units converted to "m/s".	
    cout << roaqCol(0, "m/s") << endl;

Motivation

Add support for Quanta in the Tables system.

Thrown Exceptions

TableInvOper if the Table column is null.

To Do

Support for fixed unit per array element (e.g. for positions) In that case #units should match first array dimension.
Functions like getColumn, getSlice.
get as Quantum<Array<T>>.
optimize when converting when units are the same for entire array.

Member Description

ROArrayQuantColumn()

The default constructor creates a null object. It is useful for creating arrays of ROArrayQuantColumn objects. Attempting to use a null object will produce a segmentation fault so care needs to be taken to initialize the objects by using the attach() member before any attempt is made to use the object. The isNull() member can be used to test if a ROArrayQuantColumn object is null.

ROArrayQuantColumn (const Table& tab, const String& columnName)

Create the ROArrayQuantColumn from the supplied table and column name. The default unit for data retrieved is the unit in which they were stored.

ROArrayQuantColumn (const Table& tab, const String& columnName, const Unit&)
ROArrayQuantColumn (const Table& tab, const String& columnName, const Vector<Unit>&)

Create the ROArrayQuantColumn from the supplied table and column name. The default unit for data retrieved is the given unit (the data is converted as needed).

ROArrayQuantColumn (const ROArrayQuantColumn<T>& that)

Copy constructor (copy semantics).

~ROArrayQuantColumn()

void reference (const ROArrayQuantColumn<T>& that)

Make this object reference the column in "that".

void attach (const Table& tab, const String& columnName)
void attach (const Table& tab, const String& columnName, const Unit&)
void attach (const Table& tab, const String& columnName, const Vector<Unit>&)

Attach a column to the object. Optionally supply a default unit. which has the same meaning as the constructor unit argument.

void get (uInt rownr, Array<Quantum<T> >& q, const Unit&, Bool resize = False) const

Get the quantum array in the specified row. If resize is True the resulting array is resized if its shape is not correct. Otherwise a "conformance exception" is thrown if the array is not empty and its shape mismatches.

Get the quantum array in the specified row. Each quantum is converted to the given unit.

void get (uInt rownr, Array<Quantum<T> >& q, const Vector<Vector>&, Bool resize = False) const

Get the quantum array in the specified row. Each quantum is converted to the given units.

void get (uInt rownr, Array<Quantum<T> >& q, const Quantum<T>& other, Bool resize = False) const

Get the quantum array in the specified row. Each quantum is converted to the unit in other.

void get (uInt rownr, Array<Quantum<T> >& q, Bool resize = False) const

Array<Quantum<T> > operator() (uInt rownr, const Unit&) const

Return the quantum array stored in the specified row.

Return the quantum array stored in the specified row, converted to the given unit.

Array<Quantum<T> > operator() (uInt rownr, const Vector<Vector>&) const

Return the quantum array stored in the specified row.

Return the quantum array stored in the specified row, converted to the given units.

Array<Quantum<T> > operator() (uInt rownr, const Quantum<T>& other) const

Return the quantum array stored in the specified row.

Return the quantum array stored in the specified row, converted to the unit in other.

Array<Quantum<T> > operator() (uInt rownr) const

Return the quantum array stored in the specified row.

Bool isUnitVariable() const

Test whether the Quantum column has variable units

Vector<String> getUnits() const

Returns the column's units as a vector of strings. An empty vector is returned if the column has no fixed units.

Bool isNull() const

Test if the object is null.

void throwIfNull() const

Throw an exception if the object is null.

const ROArrayColumn<String>* arrUnitsCol() const
const ROScalarColumn<String>* scaUnitsCol() const

Get access to itsUnitsCol.

void init (const Table& tab, const String& columnName)

Initialize the ROArrayQuantColumn from the specified table and column.

void cleanUp()

Deletes allocated memory etc. Called by ~tor and any member which needs to reallocate data.

void getData (uInt rownr, Array<Quantum<T> >& q, Bool resize) const

Get the data without possible conversion.

ROArrayQuantColumn& operator= (const ROArrayQuantColumn<T>& that)

Assignment makes no sense in a read only class. Declaring this operator private makes it unusable.

Bool operator== (const ROArrayQuantColumn<T>& that)

Comparison is not defined, since its semantics are unclear.

template<class T> class ArrayQuantColumn : public ROArrayQuantColumn<T>

Interface

Public Members

ArrayQuantColumn()

ArrayQuantColumn (const Table& tab, const String& columnName)

ArrayQuantColumn (const ArrayQuantColumn<T>& that)

~ArrayQuantColumn()

void reference(const ArrayQuantColumn<T>& that)

void attach (const Table& tab, const String& columnName)

void put (uInt rownr, const Array<Quantum<T> >& q)

Private Members

ArrayQuantColumn& operator= (const ArrayQuantColumn<T>& that)

Bool operator== (const ArrayQuantColumn<T>& that)

void cleanUp()

Description

Review Status

Reviewed By:

Bob Garwood

Date Reviewed:

1999/12/23

Programs:

Tests:

tTableQuantum.cc

Prerequisite

Synopsis

The ArrayQuantColumn class provides read/write access to Quanta stored in a Quantum Table column. The column should previously have been defined as a Quantum column by means of the TableQuantumDesc object. In addition to the operations provided by its read-only partner, ROArrayQuantColumn, use of a ArrayQuantColumn object allows the insertion of Quanta into a column.

Quantum Units

The underlying Quantum column will have been defined to have either variable or fixed Units. A variable unit can be variable per row (thus the same for an entire array in that row) or it can be variable per array element. If the Quantum column's Unit is fixed then writing quanta converts the data to that unit. If the column's unit is variable, the data is written unconverted and the unit is written into the unit column defined in the TableQuantumDesc object.
See TableQuantumDesc for more details.

Example

(See TableQuantumDesc class for an example of how to define a Quantum column).

    // This creates the Quantum array object.
    ArrayQuantColumn<Double> aqCol(qtab, "ArrQuantDouble");

    // Test if the column has variable of fixed units
    if (aqCol.isUnitVariable()) {
        cout << "Quantum column supports variable units!" << endl;
    } else {
        cout << "Unit for the column is: ", << aqCol.getUnits() << endl;
    }

    // need an array of Quanta.
    IPosition shape(2, 3, 2);
    Array<Quantum<Double> > qArr(shape);
    Bool deleteIt;
    Quantum<Double>* q_p = qArr.getStorage(deleteIt);
    q_p->setValue(1.41212);
    q_p->setUnit("GHz");
    q_p++;
    q_p->setValue(1.4921);
    q_p->setUnit("deg");
    q_p++;
    q_p->setValue(1.4111);
    q_p->setUnit("ms-1");
    q_p++;
    q_p->setValue(1.4003);
    q_p->setUnit("Jy");
    q_p++;
    q_p->setValue(1.22);
    q_p->setUnit("GHz");
    q_p++;
    q_p->setValue(1.090909);
    q_p->setUnit("g");	
    qArr.putStorage(q_p, deleteIt);
 	
    // put the quantum array in the column at row 0.  If the column has
    // fixed units the Unit component of each quantum will be lost.  Just
    // their values will be stored.
    aqCol.put(0, qArr);

Motivation

Add support for Quanta in the Tables system.

Thrown Exceptions

TableInvOper if the Table column is null.

To Do

Functions like putColumn, putSlice

Member Description

ArrayQuantColumn()

The default constructor creates a null object. Useful for creating arrays of ArrayQuantColumn objects. Attempting to use a null object will produce a segmentation fault, so care needs to be taken to initialize the objects by using the attach() member before any attempt is made to use the object. The isNull() member can be used to test if a ArrayQuantColumn object is null.

ArrayQuantColumn (const Table& tab, const String& columnName)

Create the ArrayQuantColumn from the supplied table and column name. The default unit for data retrieved is the unit in which they were stored.

ArrayQuantColumn (const ArrayQuantColumn<T>& that)

Copy constructor (copy semantics).

~ArrayQuantColumn()

void reference(const ArrayQuantColumn<T>& that)

Make this object reference the column in "that".

void attach (const Table& tab, const String& columnName)

Attach a column to the object.

void put (uInt rownr, const Array<Quantum<T> >& q)

Put an array of quanta into the specified row of the table. If the column supports variable units, the units are stored as well. Otherwise the quanta are converted to the column's units.

ArrayQuantColumn& operator= (const ArrayQuantColumn<T>& that)

reference() can be used for assignment. Declaring this operator private makes it unusable.

Bool operator== (const ArrayQuantColumn<T>& that)

Comparison is not defined, since its semantics are unclear.

void cleanUp()

Deletes allocated memory etc. Called by destructor and any member which needs to reallocate data.