Description of the fields in a record object. More...

#include <RecordDesc.h>

Public Member Functions
	RecordDesc ()
	Create a description with no fields.
	RecordDesc (const RecordDesc &other)
	Create a description which is a copy of other.
RecordDesc &	operator= (const RecordDesc &other)
	Replace this description with other.
	~RecordDesc ()
uInt	addField (const String &fieldName, DataType dataType)
	Add scalar, array, sub-record, or table field.
uInt	addField (const String &fieldName, DataType scalarOrArrayType, const IPosition &shape)
	Add an array field of the indicated type.
uInt	addField (const String &fieldName, const RecordDesc &subDesc)
	Add a Record field to the description.
uInt	addTable (const String &fieldName, const String &tableDescName)
	Add a Table field to the description.
const String &	comment (Int whichField) const
	Get the comment for this field.
void	setComment (Int whichField, const String &comment)
	Set the comment for this field.
void	setShape (Int whichField, const IPosition &shape)
	Set the shape for this field.
uInt	mergeField (const RecordDesc &other, Int whichFieldFromOther, RecordInterface::DuplicatesFlag DuplicateAction=RecordInterface::ThrowOnDuplicates)
	Merge a single field from other.
uInt	merge (const RecordDesc &other, RecordInterface::DuplicatesFlag DuplicateAction=RecordInterface::ThrowOnDuplicates)
	Add all the fields from another RecordDesc to the current objects.
uInt	removeField (Int whichField)
	Remove the given field from the description.
void	renameField (const String &newName, Int whichField)
	Rename the given field.
Int	fieldNumber (const String &fieldName) const
	Returns the index of the field named fieldName.
uInt	nfields () const
	Number of fields in the description.
DataType	type (Int whichField) const
	What is the type of the given field.
const String &	name (Int whichField) const
	What is the name of the given field.
String	makeName (Int whichField) const
	Create a name for a field defined by index as *i (similar to glish).
String	uniqueName (const String &name) const
	Make the given name unique by adding a suffix _j when needed.
Bool	isArray (Int whichField) const
	Returns True if whichField is an array.
Bool	isScalar (Int whichField) const
	Returns True if whichField is a scalar.
Bool	isSubRecord (Int whichField) const
	Returns True if whichField is a sub-record.
Bool	isTable (Int whichField) const
	Returns True if whichField is a table.
const IPosition &	shape (Int whichField) const
	What is the shape of the given field.
const String &	tableDescName (Int whichField) const
	What is the name of the table description.
const RecordDesc &	subRecord (Int whichField) const
	If whichField is a sub-record return its description.
RecordDesc &	rwSubRecord (Int whichField)
Bool	operator== (const RecordDesc &other) const
	This and other compare equal if the field types and shapes are identical (recursively if there are described sub-records).
Bool	operator!= (const RecordDesc &other) const
Bool	conform (const RecordDesc &other) const
	Test if this description conforms the other.
Bool	isEqual (const RecordDesc &other, Bool &equalDataTypes) const
	Test if this description equals another one.
Bool	isSubset (const RecordDesc &other, Bool &equalDataTypes) const
	Test if this description is a subset of another one.
Bool	isStrictSubset (const RecordDesc &other, Bool &equalDataTypes) const
	Test if this description is a strict subset of another one, thus if it is a subset and not equal.
Bool	isSuperset (const RecordDesc &other, Bool &equalDataTypes) const
	Test if this description is a superset of another one.
Bool	isStrictSuperset (const RecordDesc &other, Bool &equalDataTypes) const
	Test if this description is a strict superset of another one, thus if it is a superset and not equal.
Bool	isDisjoint (const RecordDesc &other) const
	Test if the set of field names in this and other record description is disjoint (i.e.
Private Member Functions
ostream &	put (ostream &os) const
	Writes/reads the RecordDesc to/from an output stream.
AipsIO &	put (AipsIO &os) const
AipsIO &	get (AipsIO &os)
Private Attributes
COWPtr< RecordDescRep >	desc_p
	Use a copy-on-write pointer to the RecordDescRep.
Friends

ostream &	operator<< (ostream &os, const RecordDesc &desc)
	Writes/reads the RecordDesc to/from an output stream.
AipsIO &	operator<< (AipsIO &os, const RecordDesc &desc)
AipsIO &	operator>> (AipsIO &os, RecordDesc &desc)

Detailed Description

Description of the fields in a record object.

Intended use:

Public interface

Review Status

Reviewed By:: Mark Wieringa
Date Reviewed:: 1996/04/15
Test programs:: tRecordDesc

Prerequisite

Etymology

RecordStructure would perhaps have been the clearest possible name. However it was decided to name it ``RecordDesc'' to use a compatible naming convention with other classes in the system, such as TableDesc. This class Describes the structure of a Record.

Synopsis

RecordDesc describes the structure of Record objects. A Record consists of a number of fields. A RecordDesc describes those fields by assigning to each one:

A name for the field.
A type from the DataType enum.
A shape if the field is an array.
A RecordDesc if the field is itself a Record (the Record is an hierarchical structure).

Only one field with a given name is allowed (although fields in subrecords may have the same name as a field in a parent or child Record).

Field indices are zero relative, i.e. they range from 0 to nfields()-1.

Example

See the example in the description of the Record class.

Motivation

It is useful to be able to create many new objects with the same structure as some other, without necessarily cloning it by copying all the values. A ``Description'' type is necessary to do this (e.g., shape for an Array).

To Do

Should the strategy wrt. field names be changed (not used in field description equality, must be unique at a given level?).
Perhaps we should be able to more conveniently change the description of an existing field.

Definition at line 104 of file RecordDesc.h.

Constructor & Destructor Documentation

casa::RecordDesc::RecordDesc ( ) [inline]

Create a description with no fields.

Definition at line 304 of file RecordDesc.h.

casa::RecordDesc::RecordDesc ( const RecordDesc & other ) [inline]

Create a description which is a copy of other.

Definition at line 308 of file RecordDesc.h.

casa::RecordDesc::~RecordDesc ( ) [inline]

Definition at line 320 of file RecordDesc.h.

Member Function Documentation

uInt casa::RecordDesc::addField	(	const String &	fieldName,
		DataType	dataType
	)		`[inline]`

Add scalar, array, sub-record, or table field.

If of array type, the shape is set to [-1], which indicates a variable sized array. If of sub-record type, the sub-record is free format. Returns the number of fields in the description.

Definition at line 323 of file RecordDesc.h.

References casa::RecordDescRep::addField(), desc_p, and casa::COWPtr< T >::rwRef().

uInt casa::RecordDesc::addField	(	const String &	fieldName,
		DataType	scalarOrArrayType,
		const IPosition &	shape
	)		`[inline]`

Add an array field of the indicated type.

The DataType is promoted from a scalar type to an array type if necessary, e.g., TpInt ->TpArrayInt. Returns the number of fields in the description. A shape of [-1] indicates a variable shape.

Definition at line 328 of file RecordDesc.h.

References casa::RecordDescRep::addArray(), desc_p, and casa::COWPtr< T >::rwRef().

uInt casa::RecordDesc::addField	(	const String &	fieldName,
		const RecordDesc &	subDesc
	)		`[inline]`

Add a Record field to the description.

This allows hierarchical descriptions to be developed. Returns the number of fields in the description.

Definition at line 335 of file RecordDesc.h.

References casa::RecordDescRep::addRecord(), desc_p, and casa::COWPtr< T >::rwRef().

uInt casa::RecordDesc::addTable	(	const String &	fieldName,
		const String &	tableDescName
	)		`[inline]`

Add a Table field to the description.

The Table description has the given name. Returns the number of fields in the description.
When a table is put in a record field, it is checked if the name of its description matches this name. If this name is empty, it matches any table description.
Warning: Note that not all record types are able to instantiate a table field; E;g; TableRecord can instantiate it, while Record cannot and throws an exception when a record description containing a table field is used;

Definition at line 341 of file RecordDesc.h.

References casa::RecordDescRep::addTable(), desc_p, and casa::COWPtr< T >::rwRef().

const String & casa::RecordDesc::comment ( Int whichField ) const [inline]

Get the comment for this field.

Definition at line 347 of file RecordDesc.h.

References casa::RecordDescRep::comment(), desc_p, and casa::COWPtr< T >::ref().

Referenced by casa::TableRecordRep::comment(), and casa::RecordRep::comment().

Bool casa::RecordDesc::conform ( const RecordDesc & other ) const [inline]

Test if this description conforms the other.

It is NOT doing it recursively, thus is does not check if sub-records are conforming.
This is used by Record, to see if another record can be assigned to this record.

Definition at line 465 of file RecordDesc.h.

References casa::RecordDescRep::conform(), desc_p, and casa::COWPtr< T >::ref().

Int casa::RecordDesc::fieldNumber ( const String & fieldName ) const [inline]

Returns the index of the field named fieldName.

Returns -1 if fieldName does not exist.

Definition at line 386 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::fieldNumber(), and casa::COWPtr< T >::ref().

AipsIO& casa::RecordDesc::get ( AipsIO & os ) [private]

Referenced by casa::operator>>().

Bool casa::RecordDesc::isArray ( Int whichField ) const [inline]

Returns True if whichField is an array.

Definition at line 416 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isArray(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::isDisjoint ( const RecordDesc & other ) const [inline]

Test if the set of field names in this and other record description is disjoint (i.e.

if they do not share names).

Definition at line 495 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isDisjoint(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::isEqual	(	const RecordDesc &	other,
		Bool &	equalDataTypes
	)		const `[inline]`

Test if this description equals another one.

It is equal if the number of fields is equal and all field names in this description occur in the other too. The order of the fields is not important.
The flag equalDataTypes is set to True if the data types of all fields match.
Use function operator== if order and types are important, but names are not.

Definition at line 470 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isEqual(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::isScalar ( Int whichField ) const [inline]

Returns True if whichField is a scalar.

Definition at line 421 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isScalar(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::isStrictSubset	(	const RecordDesc &	other,
		Bool &	equalDataTypes
	)		const `[inline]`

Test if this description is a strict subset of another one, thus if it is a subset and not equal.

Definition at line 480 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isStrictSubset(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::isStrictSuperset	(	const RecordDesc &	other,
		Bool &	equalDataTypes
	)		const `[inline]`

Test if this description is a strict superset of another one, thus if it is a superset and not equal.

Definition at line 490 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isStrictSubset(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::isSubRecord ( Int whichField ) const [inline]

Returns True if whichField is a sub-record.

Definition at line 426 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isSubRecord(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::isSubset	(	const RecordDesc &	other,
		Bool &	equalDataTypes
	)		const `[inline]`

Test if this description is a subset of another one.

It is similar to isEqual above.

Definition at line 475 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isSubset(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::isSuperset	(	const RecordDesc &	other,
		Bool &	equalDataTypes
	)		const `[inline]`

Test if this description is a superset of another one.

Definition at line 485 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isSubset(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::isTable ( Int whichField ) const [inline]

Returns True if whichField is a table.

Definition at line 431 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::isTable(), and casa::COWPtr< T >::ref().

String casa::RecordDesc::makeName ( Int whichField ) const [inline]

Create a name for a field defined by index as *i (similar to glish).

It takes care that the resulting name is unique by adding a suffix _j when needed.

Definition at line 406 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::makeName(), and casa::COWPtr< T >::ref().

uInt casa::RecordDesc::merge	(	const RecordDesc &	other,
		RecordInterface::DuplicatesFlag	DuplicateAction = `RecordInterface::ThrowOnDuplicates`
	)		`[inline]`

Add all the fields from another RecordDesc to the current objects.

It returns the new number of fields.

Definition at line 370 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::merge(), casa::COWPtr< T >::ref(), and casa::COWPtr< T >::rwRef().

uInt casa::RecordDesc::mergeField	(	const RecordDesc &	other,
		Int	whichFieldFromOther,
		RecordInterface::DuplicatesFlag	DuplicateAction = `RecordInterface::ThrowOnDuplicates`
	)		`[inline]`

Merge a single field from other.

If allowDuplicates is True, silently throw away fields if one with the same name and type already exists, otherwise an exception is thrown. Conflicting types always cause an exception. Returns the number of fields in the description.

Definition at line 362 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::mergeField(), casa::COWPtr< T >::ref(), and casa::COWPtr< T >::rwRef().

const String & casa::RecordDesc::name ( Int whichField ) const [inline]

What is the name of the given field.

Definition at line 411 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::name(), and casa::COWPtr< T >::ref().

uInt casa::RecordDesc::nfields ( ) const [inline]

Number of fields in the description.

Definition at line 391 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::nfields(), and casa::COWPtr< T >::ref().

Bool casa::RecordDesc::operator!= ( const RecordDesc & other ) const [inline]

Definition at line 461 of file RecordDesc.h.

References desc_p, and casa::COWPtr< T >::ref().

RecordDesc & casa::RecordDesc::operator= ( const RecordDesc & other ) [inline]

Replace this description with other.

Definition at line 312 of file RecordDesc.h.

References desc_p.

Bool casa::RecordDesc::operator== ( const RecordDesc & other ) const [inline]

This and other compare equal if the field types and shapes are identical (recursively if there are described sub-records).

The field names are not used.
Use function isEqual if names are important, but order is not.

Definition at line 456 of file RecordDesc.h.

References desc_p, and casa::COWPtr< T >::ref().

ostream& casa::RecordDesc::put ( ostream & os ) const [private]

Writes/reads the RecordDesc to/from an output stream.

Referenced by casa::operator<<().

AipsIO& casa::RecordDesc::put ( AipsIO & os ) const [private]

uInt casa::RecordDesc::removeField ( Int whichField ) [inline]

Remove the given field from the description.

It returns the new number of fields.

Definition at line 376 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::removeField(), and casa::COWPtr< T >::rwRef().

void casa::RecordDesc::renameField	(	const String &	newName,
		Int	whichField
	)		`[inline]`

Rename the given field.

Definition at line 381 of file RecordDesc.h.

References desc_p, casa::RecordDescRep::renameField(), and casa::COWPtr< T >::rwRef().

Referenced by casa::TableRecordRep::renameField(), and casa::RecordRep::renameField().

RecordDesc & casa::RecordDesc::rwSubRecord ( Int whichField ) [inline]

Definition at line 451 of file RecordDesc.h.

References desc_p, casa::COWPtr< T >::rwRef(), and casa::RecordDescRep::subRecord().

void casa::RecordDesc::setComment	(	Int	whichField,
		const String &	comment
	)		`[inline]`

Set the comment for this field.

Definition at line 352 of file RecordDesc.h.

References desc_p, casa::COWPtr< T >::rwRef(), and casa::RecordDescRep::setComment().

Referenced by casa::TableRecordRep::setComment(), and casa::RecordRep::setComment().

void casa::RecordDesc::setShape	(	Int	whichField,
		const IPosition &	shape
	)		`[inline]`

Set the shape for this field.

An exception will be thrown if the field is no array.

Definition at line 357 of file RecordDesc.h.

References desc_p, casa::COWPtr< T >::rwRef(), and casa::RecordDescRep::setShape().

const IPosition & casa::RecordDesc::shape ( Int whichField ) const [inline]

What is the shape of the given field.

Returns [1] if the field is a scalar, table or, sub-record, [-1] if it is a variable length array, and the actual shape for a fixed length array.

Definition at line 436 of file RecordDesc.h.

References desc_p, casa::COWPtr< T >::ref(), and casa::RecordDescRep::shape().

const RecordDesc & casa::RecordDesc::subRecord ( Int whichField ) const [inline]

If whichField is a sub-record return its description.

Otherwise an exception is thrown. The non-const version is named differently to prevent accidental use of the non-const version.

Definition at line 446 of file RecordDesc.h.

References desc_p, casa::COWPtr< T >::ref(), and casa::RecordDescRep::subRecord().

Referenced by casa::RecordDescRep::subRecord().

const String & casa::RecordDesc::tableDescName ( Int whichField ) const [inline]

What is the name of the table description.

Returns an empty string when the field is no table.

Definition at line 441 of file RecordDesc.h.

References desc_p, casa::COWPtr< T >::ref(), and casa::RecordDescRep::tableDescName().

DataType casa::RecordDesc::type ( Int whichField ) const [inline]

What is the type of the given field.

Returns TpRecord if the field is a sub-Record.

Definition at line 396 of file RecordDesc.h.

References desc_p, casa::COWPtr< T >::ref(), and casa::RecordDescRep::type().

String casa::RecordDesc::uniqueName ( const String & name ) const [inline]

Make the given name unique by adding a suffix _j when needed.

j is the minimal number needed to make it unique.

Definition at line 401 of file RecordDesc.h.

References desc_p, casa::COWPtr< T >::ref(), and casa::RecordDescRep::uniqueName().

Friends And Related Function Documentation

ostream& operator<<	(	ostream &	os,
		const RecordDesc &	desc
	)		`[friend]`

Writes/reads the RecordDesc to/from an output stream.

Definition at line 501 of file RecordDesc.h.

AipsIO& operator<<	(	AipsIO &	os,
		const RecordDesc &	desc
	)		`[friend]`

Definition at line 505 of file RecordDesc.h.

AipsIO& operator>>	(	AipsIO &	os,
		RecordDesc &	desc
	)		`[friend]`

Definition at line 509 of file RecordDesc.h.

Member Data Documentation

COWPtr<RecordDescRep> casa::RecordDesc::desc_p [private]

Use a copy-on-write pointer to the RecordDescRep.

Definition at line 299 of file RecordDesc.h.

Referenced by addField(), addTable(), comment(), conform(), fieldNumber(), isArray(), isDisjoint(), isEqual(), isScalar(), isStrictSubset(), isStrictSuperset(), isSubRecord(), isSubset(), isSuperset(), isTable(), makeName(), merge(), mergeField(), name(), nfields(), operator!=(), operator=(), operator==(), removeField(), renameField(), rwSubRecord(), setComment(), setShape(), shape(), subRecord(), tableDescName(), type(), and uniqueName().

The documentation for this class was generated from the following file:

casacore/casa/Containers/RecordDesc.h

Public Member Functions

Private Member Functions

Private Attributes

Friends