Definition of a Measure Reference in a Table. More...

#include <TableMeasRefDesc.h>

Public Types
typedef void	TypesFunc (Vector< String > &types, Vector< uInt > &codes, const MeasureHolder &)
	Set the function used to get all reference codes for a MeasureHolder.
Public Member Functions
	TableMeasRefDesc (uInt refCode=0)
	Define a fixed MeasRef by supplying its reference code Optionally a Measure offset can be specified.
	TableMeasRefDesc (uInt refCode, const TableMeasOffsetDesc &)
	TableMeasRefDesc (const TableDesc &, const String &column)
	Define a variable reference by supplying the name of the column in which the reference is to be stored.
	TableMeasRefDesc (const TableDesc &, const String &column, const TableMeasOffsetDesc &)
	TableMeasRefDesc (const TableRecord &measInfo, const Table &, const MeasureHolder &measHolder, const TableMeasDescBase &)
	Reconstruct the object from the MEASINFO record.
	TableMeasRefDesc (const TableMeasRefDesc &that)
	Copy constructor (copy semantics)
	~TableMeasRefDesc ()
TableMeasRefDesc &	operator= (const TableMeasRefDesc &that)
	Assignment operator (copy semantics).
uInt	getRefCode () const
	Return the reference code.
Bool	isRefCodeVariable () const
	Is the reference variable?
const String &	columnName () const
	Return the name of its variable reference code column.
Bool	isRefCodeColumnInt () const
	Is the reference code variable and stored in an integer column?
Bool	hasRefTab () const
	Do the keywords contain the reference codes and types.
Bool	hasOffset () const
	Returns True if the reference has an offset.
Bool	isOffsetVariable () const
	Returns True if the offset is variable.
Bool	isOffsetArray () const
	Returns True is the offset is variable and it is an ArrayMeasColumn.
const Measure &	getOffset () const
	Return the fixed Measure offset.
const String &	offsetColumnName () const
	Return the name of the Measure offset column.
void	resetRefCode (uInt refCode)
	Reset the refCode or offset.
void	resetOffset (const Measure &offset)
void	write (TableDesc &, TableRecord &measInfo, const TableMeasDescBase &)
	Make the Measure value descriptor persistent.
void	write (Table &, TableRecord &measInfo, const TableMeasDescBase &)
void	initTabRef (const MeasureHolder &measHolder)
	Initialize the table reference codes and types and the maps (mapping a code onto itself).
uInt	tab2cur (uInt tabRefCode) const
	Reference codes can be persistent in tables.
uInt	cur2tab (uInt curRefCode) const
Static Public Member Functions
static void	setTypesFunc (TypesFunc *func)
static void	defaultTypesFunc (Vector< String > &types, Vector< uInt > &codes, const MeasureHolder &)
Static Public Attributes
static TypesFunc *	theirTypesFunc
Private Member Functions
void	initTabRefMap ()
	Fill the reference code mappings for table<->current.
void	fillTabRefMap (const MeasureHolder &measHolder)
uInt	fillMap (Block< Int > &f2t, const Vector< uInt > &codesf, const Vector< String > &typesf, Vector< uInt > &codest, Vector< String > &typest, Int maxnr)
void	writeKeys (TableRecord &measInfo, const TableMeasDescBase &measDesc)
	Write the actual keywords.
void	checkColumn (const TableDesc &td)
	Throw an exception if the column doesn't exist or is of the wrong type.
Private Attributes
uInt	itsRefCode

String	itsColumn
	The name of column containing its variable references.
Bool	itsRefCodeColInt
	Is the reference code column a string column?
Bool	itsHasRefTab
	Do the keywords contain the reference codes and types?
TableMeasOffsetDesc *	itsOffset
Vector< String >	itsTabRefTypes
Vector< uInt >	itsTabRefCodes
Block< Int >	itsTab2Cur
Block< Int >	itsCur2Tab

Detailed Description

Definition of a Measure Reference in a Table.

Intended use:

Public interface

Review Status

Reviewed By:: Bob Garwood
Date Reviewed:: 1999/12/23
Test programs:: tTableMeasures

Prerequisite

Measures
Tables
TableMeasDesc

Synopsis

TableMeasRefDesc is a class for setting up the MeasRef component of a TableMeasDesc in the TableMeasures system. With the aid of a TableMeasRefDesc the following possibilities for defining a Measure column's reference exist:

a fixed, non-variable, reference code, where all Measures in a column are to have the same reference code.
a unique (and probably different) reference code stored in each row.
a unique reference code stored in each array element per (Array)column row.

For each of the above options an offset component can be specified along with a reference code. When a Measure offset is required a TableMeasOffsetDesc is supplied as an argument to the TableMeasRefDesc constructor. With references containing an offset component either component can be set to be variable or fixed independently of the other.

Tip: It is not necessary to specify a Reference when defining a Measure column; In such cases the Measures retrieved from the column will have the default reference for the type of Measure stored in the column;

A fixed reference code is trivially stored as part of the column keywords in the Measure column but a variable reference code requires its own column. A Scalar or Array column can be used dependent on your needs but its type must always be either Int or String. Note that it is legal to specify a Scalar reference column for use with an ArrayMeasColumn. In such cases a single reference code will be stored per array (row) of Measures. However, attempting to associate an Array column for references with a ScalarMeasColumn will generate an exception.
Note: Because the reference codes stored are the enums defined in the Measures classes, it is possible that they change over time; The type strings, however, wille never change; Therefore the reference codes and types valid at the time of the table creation, are stored in the column keywords if the reference codes are kept in an integer column;
This has only been added in March 2007, but is fully backward compatible; Older tables will get the codes and types stored when accessed for read/write;

Caution: When storing Measures into a Measure column with a fixed reference code the reference code component of the Measures stored is ignored;

Example

Simplest kind of TableMeasRefDesc (apart from not specifying one at all) is a fixed reference code. All Measures subsequently retrieved from the column will have the reference MEpoch::LAST.
```
       // measure reference column
       TableMeasRefDesc reference(MEpoch::LAST);
```

A variable reference code requires its own Int column.

       // An int column for the variable references.
       ScalarColumnDesc<Int> cdRefCol("refCol", "Measure reference column");
       td.addColumn(cdRefCol);
       ..\.
       // create the Measure reference descriptor
       TableMeasRefDesc varRef(td, "refCol");

A fix Measure reference code with a fixed Offset

       // Create the Offset descriptor
       MEpoch offset(MVEpoch(MVTime(1996, 5, 17, (8+18./60.)/24.))
       TableMeasOffsetDesc offsetDesc(offset);
       // create the Measure reference descriptor
       TableMeasRefDesc varRef(MEpoch::LAST, offsetDesc);

For an example of the use of a TableMeasRefDesc in the context of a full TableMeasDesc declaration see class TableMeasDesc .

Motivation

Creating the required keyword for the definition of a Measure in a Table is somewhat complicated. This class assists in that process.

Thrown Exceptions

AipsError if the specified column doesn't exist or its type is not Int or String.

Definition at line 166 of file TableMeasRefDesc.h.

Member Typedef Documentation

typedef void casa::TableMeasRefDesc::TypesFunc(Vector< String > &types, Vector< uInt > &codes, const MeasureHolder &)

Set the function used to get all reference codes for a MeasureHolder.

This is not reaaly needed for normal practice, but makes it possible to add extra codes when testing.
The default function simply calls MeasureHolder.asMeasure.allTypes.

Definition at line 284 of file TableMeasRefDesc.h.

Constructor & Destructor Documentation

casa::TableMeasRefDesc::TableMeasRefDesc ( uInt refCode = 0 ) [explicit]

Define a fixed MeasRef by supplying its reference code Optionally a Measure offset can be specified.

The reference code and offset should not need a reference frame.

casa::TableMeasRefDesc::TableMeasRefDesc	(	uInt	refCode,
		const TableMeasOffsetDesc &
	)

casa::TableMeasRefDesc::TableMeasRefDesc	(	const TableDesc &	,
		const String &	column
	)

Define a variable reference by supplying the name of the column in which the reference is to be stored.

Either an Int or String column can be specified. This determines how references are stored. Int columns are likely to be faster but storing references as Strings may be useful if there is a need to browse tables manually. Optionally supply a Measure offset. The reference code and offset should not need a reference frame.

casa::TableMeasRefDesc::TableMeasRefDesc	(	const TableDesc &	,
		const String &	column,
		const TableMeasOffsetDesc &
	)

casa::TableMeasRefDesc::TableMeasRefDesc	(	const TableRecord &	measInfo,
		const Table &	,
		const MeasureHolder &	measHolder,
		const TableMeasDescBase &
	)

Reconstruct the object from the MEASINFO record.

Not useful for the public.

casa::TableMeasRefDesc::TableMeasRefDesc ( const TableMeasRefDesc & that )

Copy constructor (copy semantics)

casa::TableMeasRefDesc::~TableMeasRefDesc ( )

Member Function Documentation

void casa::TableMeasRefDesc::checkColumn ( const TableDesc & td ) [private]

Throw an exception if the column doesn't exist or is of the wrong type.

const String& casa::TableMeasRefDesc::columnName ( ) const [inline]

Return the name of its variable reference code column.

Definition at line 215 of file TableMeasRefDesc.h.

References itsColumn.

Referenced by casa::TableMeasDescBase::refColumnName().

uInt casa::TableMeasRefDesc::cur2tab ( uInt curRefCode ) const

static void casa::TableMeasRefDesc::defaultTypesFunc	(	Vector< String > &	types,
		Vector< uInt > &	codes,
		const MeasureHolder &
	)		`[static]`

uInt casa::TableMeasRefDesc::fillMap	(	Block< Int > &	f2t,
		const Vector< uInt > &	codesf,
		const Vector< String > &	typesf,
		Vector< uInt > &	codest,
		Vector< String > &	typest,
		Int	maxnr
	)		`[private]`

void casa::TableMeasRefDesc::fillTabRefMap ( const MeasureHolder & measHolder ) [private]

const Measure& casa::TableMeasRefDesc::getOffset ( ) const [inline]

Return the fixed Measure offset.

It does not test if the offset is defined; hasOffset() should be used for that purpose.

Definition at line 242 of file TableMeasRefDesc.h.

References casa::TableMeasOffsetDesc::getOffset(), and itsOffset.

Referenced by casa::TableMeasDescBase::getOffset().

uInt casa::TableMeasRefDesc::getRefCode ( ) const [inline]

Return the reference code.

Definition at line 207 of file TableMeasRefDesc.h.

References itsRefCode.

Referenced by casa::TableMeasDescBase::getRefCode().

Bool casa::TableMeasRefDesc::hasOffset ( ) const [inline]

Returns True if the reference has an offset.

Definition at line 228 of file TableMeasRefDesc.h.

References itsOffset.

Referenced by casa::TableMeasDescBase::hasOffset().

Bool casa::TableMeasRefDesc::hasRefTab ( ) const [inline]

Do the keywords contain the reference codes and types.

For old tables this might not be the case.

Definition at line 224 of file TableMeasRefDesc.h.

References itsHasRefTab.

void casa::TableMeasRefDesc::initTabRef ( const MeasureHolder & measHolder )

Initialize the table reference codes and types and the maps (mapping a code onto itself).

void casa::TableMeasRefDesc::initTabRefMap ( ) [private]

Fill the reference code mappings for table<->current.

Bool casa::TableMeasRefDesc::isOffsetArray ( ) const [inline]

Returns True is the offset is variable and it is an ArrayMeasColumn.

Definition at line 236 of file TableMeasRefDesc.h.

References casa::False, casa::TableMeasOffsetDesc::isArray(), and itsOffset.

Referenced by casa::TableMeasDescBase::isOffsetArray().

Bool casa::TableMeasRefDesc::isOffsetVariable ( ) const [inline]

Returns True if the offset is variable.

Definition at line 232 of file TableMeasRefDesc.h.

References casa::False, casa::TableMeasOffsetDesc::isVariable(), and itsOffset.

Referenced by casa::TableMeasDescBase::isOffsetVariable().

Bool casa::TableMeasRefDesc::isRefCodeColumnInt ( ) const [inline]

Is the reference code variable and stored in an integer column?

Definition at line 219 of file TableMeasRefDesc.h.

References itsRefCodeColInt.

Bool casa::TableMeasRefDesc::isRefCodeVariable ( ) const [inline]

Is the reference variable?

Definition at line 211 of file TableMeasRefDesc.h.

References casa::String::empty(), and itsColumn.

Referenced by casa::TableMeasDescBase::isRefCodeVariable().

const String& casa::TableMeasRefDesc::offsetColumnName ( ) const [inline]

Return the name of the Measure offset column.

An empty string is returned if no variable offset is used.

Definition at line 247 of file TableMeasRefDesc.h.

References casa::TableMeasOffsetDesc::columnName(), and itsOffset.

Referenced by casa::TableMeasDescBase::offsetColumnName().

TableMeasRefDesc& casa::TableMeasRefDesc::operator= ( const TableMeasRefDesc & that )

Assignment operator (copy semantics).

void casa::TableMeasRefDesc::resetOffset ( const Measure & offset )

Referenced by casa::TableMeasDescBase::resetOffset().

void casa::TableMeasRefDesc::resetRefCode ( uInt refCode )

Reset the refCode or offset.

It overwrites the value used when defining the TableMeasDesc. It is only possible if it was defined as fixed for the entire column.

Referenced by casa::TableMeasDescBase::resetRefCode().

static void casa::TableMeasRefDesc::setTypesFunc ( TypesFunc * func ) [inline, static]

Definition at line 286 of file TableMeasRefDesc.h.

References theirTypesFunc.

uInt casa::TableMeasRefDesc::tab2cur ( uInt tabRefCode ) const

Reference codes can be persistent in tables.

Because their enum values can change, a mapping of current table to table value is maintained. The mapping is created using their never-changing string representations. These functions convert current refcode to and from table refcode.