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

#include <RecordDesc.h>

Public Member Functions
	RecordDesc ()
	Create a description with no fields. More...

	RecordDesc (const RecordDesc &other)
	Create a description which is a copy of other. More...

RecordDesc &	operator= (const RecordDesc &other)
	Replace this description with other. More...

	~RecordDesc ()

uInt	addField (const String &fieldName, DataType dataType)
	Add scalar, array, sub-record, or table field. More...

uInt	addField (const String &fieldName, DataType scalarOrArrayType, const IPosition &shape)
	Add an array field of the indicated type. More...

uInt	addField (const String &fieldName, const RecordDesc &subDesc)
	Add a Record field to the description. More...

uInt	addTable (const String &fieldName, const String &tableDescName)
	Add a Table field to the description. More...

const String &	comment (Int whichField) const
	Get the comment for this field. More...

void	setComment (Int whichField, const String &comment)
	Set the comment for this field. More...

void	setShape (Int whichField, const IPosition &shape)
	Set the shape for this field. More...

uInt	mergeField (const RecordDesc &other, Int whichFieldFromOther, RecordInterface::DuplicatesFlag DuplicateAction=RecordInterface::ThrowOnDuplicates)
	Merge a single field from other. More...

uInt	merge (const RecordDesc &other, RecordInterface::DuplicatesFlag DuplicateAction=RecordInterface::ThrowOnDuplicates)
	Add all the fields from another RecordDesc to the current objects. More...

uInt	removeField (Int whichField)
	Remove the given field from the description. More...

void	renameField (const String &newName, Int whichField)
	Rename the given field. More...

Int	fieldNumber (const String &fieldName) const
	Returns the index of the field named fieldName. More...

uInt	nfields () const
	Number of fields in the description. More...

DataType	type (Int whichField) const
	What is the type of the given field. More...

const String &	name (Int whichField) const
	What is the name of the given field. More...

String	makeName (Int whichField) const
	Create a name for a field defined by index as *i (similar to glish). More...

String	uniqueName (const String &name) const
	Make the given name unique by adding a suffix _j when needed. More...

Bool	isArray (Int whichField) const
	Returns True if whichField is an array. More...

Bool	isScalar (Int whichField) const
	Returns True if whichField is a scalar. More...

Bool	isSubRecord (Int whichField) const
	Returns True if whichField is a sub-record. More...

Bool	isTable (Int whichField) const
	Returns True if whichField is a table. More...

const IPosition &	shape (Int whichField) const
	What is the shape of the given field. More...

const String &	tableDescName (Int whichField) const
	What is the name of the table description. More...

const RecordDesc &	subRecord (Int whichField) const
	If whichField is a sub-record return its description. More...

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). More...

Bool	operator!= (const RecordDesc &other) const

Bool	conform (const RecordDesc &other) const
	Test if this description conforms the other. More...

Bool	isEqual (const RecordDesc &other, Bool &equalDataTypes) const
	Test if this description equals another one. More...

Bool	isSubset (const RecordDesc &other, Bool &equalDataTypes) const
	Test if this description is a subset of another one. More...

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. More...

Bool	isSuperset (const RecordDesc &other, Bool &equalDataTypes) const
	Test if this description is a superset of another one. More...

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. More...

Bool	isDisjoint (const RecordDesc &other) const
	Test if the set of field names in this and other record description is disjoint (i.e. More...

Private Member Functions
ostream &	put (ostream &os) const
	Writes/reads the RecordDesc to/from an output stream. More...

AipsIO &	put (AipsIO &os) const

AipsIO &	get (AipsIO &os)

Private Attributes
COWPtr< RecordDescRep >	desc_p
	Use a copy-on-write pointer to the RecordDescRep. More...

Friends

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

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 105 of file RecordDesc.h.

Constructor & Destructor Documentation

casacore::RecordDesc::RecordDesc ( )

inline

Create a description with no fields.

Definition at line 305 of file RecordDesc.h.

casacore::RecordDesc::RecordDesc ( const RecordDesc & other )

inline

Create a description which is a copy of other.

Definition at line 309 of file RecordDesc.h.

casacore::RecordDesc::~RecordDesc ( )

inline

Definition at line 321 of file RecordDesc.h.

Member Function Documentation

uInt casacore::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 324 of file RecordDesc.h.

References desc_p.

uInt casacore::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 329 of file RecordDesc.h.

References desc_p.

uInt casacore::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 336 of file RecordDesc.h.

References desc_p.

uInt casacore::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 342 of file RecordDesc.h.

References desc_p.

const String & casacore::RecordDesc::comment ( Int whichField ) const

inline

Get the comment for this field.

Definition at line 348 of file RecordDesc.h.

References desc_p.

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

Bool casacore::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 466 of file RecordDesc.h.

References desc_p.

Int casacore::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 387 of file RecordDesc.h.

References desc_p.

AipsIO& casacore::RecordDesc::get ( AipsIO & os )

private

Referenced by casacore::operator>>().

Bool casacore::RecordDesc::isArray ( Int whichField ) const

inline

Returns True if whichField is an array.

Definition at line 417 of file RecordDesc.h.

References desc_p.

Bool casacore::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 496 of file RecordDesc.h.

References desc_p.

Bool casacore::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 471 of file RecordDesc.h.

References desc_p.

Bool casacore::RecordDesc::isScalar ( Int whichField ) const

inline

Returns True if whichField is a scalar.

Definition at line 422 of file RecordDesc.h.

References desc_p.

Bool casacore::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 481 of file RecordDesc.h.

References desc_p.

Bool casacore::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 491 of file RecordDesc.h.

References desc_p.

Bool casacore::RecordDesc::isSubRecord ( Int whichField ) const

inline

Returns True if whichField is a sub-record.

Definition at line 427 of file RecordDesc.h.

References desc_p.

Bool casacore::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 476 of file RecordDesc.h.

References desc_p.

Bool casacore::RecordDesc::isSuperset	(	const RecordDesc &	other,
		Bool &	equalDataTypes
	)		const

inline

Test if this description is a superset of another one.

Definition at line 486 of file RecordDesc.h.

References desc_p.

Bool casacore::RecordDesc::isTable ( Int whichField ) const

inline

Returns True if whichField is a table.

Definition at line 432 of file RecordDesc.h.

References desc_p.

String casacore::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 407 of file RecordDesc.h.

References desc_p.

uInt casacore::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 371 of file RecordDesc.h.

References desc_p.

uInt casacore::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 363 of file RecordDesc.h.

References desc_p.

const String & casacore::RecordDesc::name ( Int whichField ) const

inline

What is the name of the given field.

Definition at line 412 of file RecordDesc.h.

References desc_p.

uInt casacore::RecordDesc::nfields ( ) const

inline

Number of fields in the description.

Definition at line 392 of file RecordDesc.h.

References desc_p.

Bool casacore::RecordDesc::operator!= ( const RecordDesc & other ) const

inline

Definition at line 462 of file RecordDesc.h.

References desc_p.

RecordDesc & casacore::RecordDesc::operator= ( const RecordDesc & other )

inline

Replace this description with other.

Definition at line 313 of file RecordDesc.h.

References desc_p.

Bool casacore::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 457 of file RecordDesc.h.

References desc_p.

ostream& casacore::RecordDesc::put ( ostream & os ) const

private

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

Referenced by casacore::operator<<().

AipsIO& casacore::RecordDesc::put ( AipsIO & os ) const

private

uInt casacore::RecordDesc::removeField ( Int whichField )

inline

Remove the given field from the description.

It returns the new number of fields.

Definition at line 377 of file RecordDesc.h.

References desc_p.

void casacore::RecordDesc::renameField	(	const String &	newName,
		Int	whichField
	)

inline

Rename the given field.

Definition at line 382 of file RecordDesc.h.

References desc_p.

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

RecordDesc & casacore::RecordDesc::rwSubRecord ( Int whichField )

inline

Definition at line 452 of file RecordDesc.h.

References desc_p.

void casacore::RecordDesc::setComment	(	Int	whichField,
		const String &	comment
	)

inline

Set the comment for this field.

Definition at line 353 of file RecordDesc.h.

References desc_p.

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

void casacore::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 358 of file RecordDesc.h.

References desc_p.

const IPosition & casacore::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 437 of file RecordDesc.h.

References desc_p.

const RecordDesc & casacore::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 447 of file RecordDesc.h.

References desc_p.

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

const String & casacore::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 442 of file RecordDesc.h.

References desc_p.

DataType casacore::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 397 of file RecordDesc.h.

References desc_p.

String casacore::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 402 of file RecordDesc.h.

References desc_p.

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 502 of file RecordDesc.h.

AipsIO& operator<<	(	AipsIO &	os,
		const RecordDesc &	desc
	)

friend

Definition at line 506 of file RecordDesc.h.

AipsIO& operator>>	(	AipsIO &	os,
		RecordDesc &	desc
	)

friend

Definition at line 510 of file RecordDesc.h.

Member Data Documentation

COWPtr<RecordDescRep> casacore::RecordDesc::desc_p

private

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

Definition at line 300 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:

casa/Containers/RecordDesc.h

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

To Do

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation