NRAOCASA: casa::TableRecord Class Reference

Class RecordInterface describes the fundamental properties of records.
The TableRecord class is a particular type of a record class. The fields in TableRecord may be of scalar type, array type, a Table or a TableRecord. The types are chosen to be compatible with the native types of the Table system, viz: Bool, uChar, Short, Int, uInt, Float, Double, Complex, DComplex, String. Arrays of all these types are also available. Note that a TableRecord is not a space-efficient way of storing small objects.

The structure of a TableRecord is defined by the RecordDesc class. The structure of the TableRecord can be defined at construction time. It can thereafter be restructured. This has the effect, however, that any existing RecordFieldPtr objects become invalid (using the (see Notice (file="Notice.h")) classes).
It is possible to add or remove fields once a TableRecord is constructed. However, this is not possible when the TableRecord is constructed with a fixed structure (i.e. with the fixedStructure flag set).

A TableRecord is an hierarchical structure, because it can have fields containing TableRecord's (as layed out in the RecordDesc). A subrecord has a variable structure, when its RecordDesc is empty (i.e. contains no fields). It is fixed when its RecordDesc contains fields.

A TableRecord may be assigned to another only if they conform; that is if their fields have the identical type in the identical order. The field names do not need to be identical however, only the types. That is, the structure needs to be identical, but not the labels. Note that field order is significant, [ifield(type=Int),ffield(type=Float)] is not the same as [ffield(type=Float),ifield(type=Int)]
Conformance is checked recursively for fixed subrecords. That is, a variable structured subrecord is not checked, because any record can be assigned to it. A fixed structured subrecord has to conform the corresponding subrecord in the source.
A Table field is conforming when the name of the table description of the source table matches the table description name defined in the RecordDesc field. When that name is blank, every table matches. In fact, defining a table description name is identical to defining an array shape.\.

When a TableRecord is read back, possible Tables contained in fields are only opended and read back when they are accessed for the first time. In that way no needless table opens are done. When a table has been opened, it is possible to close it. This can be useful to save memory usage.

TableRecord uses copy-on-write semantics. This means that when a TableRecord is copied, only the pointer to the underlying TableRecordRep object is copied. Only when the TableRecord gets changed (i.e. when a non-const TableRecord member function is called), the TableRecordRep object is copied. This results in a cheap copy behaviour.

Example

     {
       TableDesc td ("td", TableDesc::Scratch);
       td.addColumn (ScalarColumnDesc<Int> ("col1"));
       td.addColumn (ScalarColumnDesc<float> ("col2"));
       SetupNewTable newtab ("tTableRecord_tmp.tab1", td1, Table::New);
       Table tab (newtab, 10);
       RecordDesc rd;
       rd.addTable ("tab1", "td");            // with description name
       rd.addField ("tab2", TpTable);         // without description name
       TableRecord rec (rd, RecordInterface::Variable);
       // Both define's are possible.
       // The first one because the table description name matches.
       // The second one because that field has no table description name,
       // thus every table description matches.
       rec.defineTable (rec.fieldNumber("tab1"), tab1);
       rec.defineTable (rec.fieldNumber("tab2"), tab1);
       Table t1 = rec.asTable ("tab1");
       AlwaysAssertExit (t1.nrow() == 10  &&  t1.tableDesc().ncolumn() == 2);
       Table t2 = rec.asTable ("tab2");
       AlwaysAssertExit (t2.nrow() == 10  &&  t2.tableDesc().ncolumn() == 2);
       AipsIO aos ("file.name", ByteIO::New);
       aos << rec;
     }
       // Note that he above is put in a separate scope to be sure that
       // all objects are deleted and tables are written.
     {
       TableRecord rec;
       AipsIO aos ("file.name");
       aos >> rec;
       // At this point the record is read back, but the tables are not opened.
       // The next statement accesses the table resulting in its open.
       Table t1 = rec.asTable ("tab1");
       // The following statement closes it again.
       rec.closeTable ("tab1");

Motivation

In principle the class Record could also support data type Table. However, this would have had the big disadvantage that all the Table code would have be linked in when only a simple Record is needed. It was decided that for that reason it was better to support tables in a separate class.

To Do

Constructor & Destructor Documentation

casa::TableRecord::TableRecord	(	RecordType	type,
		CheckFieldFunction *	= `0`,
		const void *	checkArgument = `0`
	)			`[explicit]`

Create a record with no fields.

The type determines if the record has a fixed or variable structure. The callback function is called when a field is added to the Record. That function can check the name and of data type of the new field (for instance, the Table system uses it to ensure that table columns and keywords have different names).

casa::TableRecord::TableRecord	(	const RecordDesc &	description,
		RecordType	type = `Fixed`,
		CheckFieldFunction *	= `0`,
		const void *	checkArgument = `0`
	)			`[explicit]`

Create a record with the given description.

If it is not possible to create all fields (for example, if a field with an unsupported data type is requested), an exception is thrown. The type determines if the record has a fixed or variable structure. All fields are checked by the field checking function (if defined) (for instance, the Table system uses it to ensure that table columns and keywords have different names).

casa::TableRecord::TableRecord ( const RecordInterface & other )

Create a TableRecord from another type of record.

It uses copy-on-write semantics if possible (i.e. if other is a TableRecord), otherwise each field is copied. Subrecords are also copied and converted to TableRecords if needed.

casa::TableRecord::TableRecord	(	TableRecordRep *	parent,
		const RecordDesc &	description
	)			`[private]`

Create TableRecord as a subrecord.

When the description is empty, the record has a variable structure. Otherwise it is fixed.

Member Function Documentation

TableRecord& casa::TableRecord::operator= ( const TableRecord & other )

Copy the data in the other record to this record.

It can operate in 2 ways depending on the TableRecord structure flag.

For variable structured records the existing fields are thrown away and replaced by the new fields. This means that RecordFieldPtr's using this record get invalidated. Because copy-on-write semantics are used, this kind of assignment is a very efficient operation.
For fixed structured records the existing values are replaced by the new values. This means that RecordFieldPtr's using this record remain valid. The structure of the other record has to conform this record or this record has to be empty, otherwise an exception is thrown. This assignment is less efficient, because it has to check the conformance and because each value has to be copied.

Warning: Attributes like fixed structure flag and check function will not be copied.

virtual RecordInterface* casa::TableRecord::clone ( ) const [virtual]

Make a copy of this object.


Public Member Functions
	TableRecord ()
	Create a record with no fields.
	TableRecord (RecordType type, CheckFieldFunction =0, const void checkArgument=0)
	Create a record with no fields.
	TableRecord (const RecordDesc &description, RecordType type=Fixed, CheckFieldFunction =0, const void checkArgument=0)
	Create a record with the given description.
	TableRecord (const TableRecord &other)
	Create a copy of other using copy semantics.
	TableRecord (const RecordInterface &other)
	Create a TableRecord from another type of record.
TableRecord &	operator= (const TableRecord &other)
	Copy the data in the other record to this record.
	~TableRecord ()
	Release resources associated with this object.
virtual RecordInterface *	clone () const
	Make a copy of this object.
virtual void	assign (const RecordInterface &that)
	Assign that RecordInterface object to this one.
virtual const String &	comment (const RecordFieldId &) const
	Get the comment for this field.
virtual void	setComment (const RecordFieldId &, const String &comment)
	Set the comment for this field.
const RecordDesc &	description () const
	Describes the current structure of this TableRecord.
virtual void	restructure (const RecordDesc &newDescription, Bool recursive=True)
	Change the structure of this TableRecord to contain the fields in newDescription.
Bool	conform (const TableRecord &other) const
	Returns True if this and other have the same RecordDesc, other than different names for the fields.
virtual uInt	nfields () const
	How many fields does this structure have? A convenient synonym for `description().nfields()`.
virtual Int	fieldNumber (const String &fieldName) const
	Get the field number from the field name.
virtual DataType	type (Int whichField) const
	Get the data type of this field.
void	removeField (const RecordFieldId &)
	Remove a field from the record.
void	renameField (const String &newName, const RecordFieldId &)
	Rename the given field.
const TableAttr &	tableAttributes (const RecordFieldId &) const
	Get the attributes of a table field.
void	mergeField (const TableRecord &other, const RecordFieldId &, DuplicatesFlag=ThrowOnDuplicates)
	Merge a field from another record into this record.
void	merge (const TableRecord &other, DuplicatesFlag=ThrowOnDuplicates)
	Merge all fields from the other record into this record.
void	closeTable (const RecordFieldId &) const
	Close the table in the given field.
void	closeTables () const
	Close all open tables.
void	flushTables (Bool fsync=False) const
	Flush all open subtables.
void	renameTables (const String &newParentName, const String &oldParentName)
	Rename the subtables with a path containing the old parent table name.
Bool	areTablesMultiUsed () const
	Are subtables used in other processes.
void	putRecord (AipsIO &os, const TableAttr &) const
	Put the data of a record.
void	getRecord (AipsIO &os, const TableAttr &)
	Read a record.
void	putData (AipsIO &os, const TableAttr &) const
	Put the data of a record.
void	getData (AipsIO &os, uInt version, const TableAttr &)
	Read the data of a record.
virtual void	print (std::ostream &, Int maxNrValues=25, const String &indent="") const
	Print the contents of the record.
void	reopenRW ()
	Reopen possible tables in keywords as read/write.
void	setTableAttr (const TableRecord &other, const TableAttr &defaultAttr)
	Set the attributes of subtables to te ones in the other record.
virtual void	makeUnique ()
	Make a unique record representation (to do copy-on-write in RecordFieldPtr).

void	defineRecord (const RecordFieldId &, const TableRecord &value, RecordType type=Variable)
	Define a value for the given field.
virtual void	defineRecord (const RecordFieldId &, const RecordInterface &value, RecordType=Variable)
void	defineTable (const RecordFieldId &, const Table &value, RecordType type=Variable)

const TableRecord &	subRecord (const RecordFieldId &) const
	Get the subrecord or table from the given field.
TableRecord &	rwSubRecord (const RecordFieldId &)
virtual const RecordInterface &	asRecord (const RecordFieldId &) const
virtual RecordInterface &	asrwRecord (const RecordFieldId &)

Table	asTable (const RecordFieldId &) const
	Get the table from the given field.
Table	asTable (const RecordFieldId &, const TableLock &lockOptions) const
Protected Member Functions
const TableRecordRep &	ref () const
	Return a const reference to the underlying TableRecordRep.
TableRecordRep &	rwRef ()
	Return a non-const reference to the underlying TableRecordRep.
virtual void	addDataField (const String &name, DataType type, const IPosition &shape, Bool fixedShape, const void *value)
	Add a field to the record.
virtual void	defineDataField (Int whichField, DataType type, const void *value)
	Define a value in the given field.

virtual void *	get_pointer (Int whichField, DataType type) const
	Used by the RecordField classes to attach in a type-safe way to the correct field.
virtual void *	get_pointer (Int whichField, DataType type, const String &recordType) const
Private Member Functions
virtual RecordDesc	getDescription () const
	Get the description of this record.
void	setRecordType (RecordType type)
	Set the recordtype of this record and all its subrecords (recursively).

	TableRecord (TableRecordRep *parent, const RecordDesc &description)
	Create TableRecord as a subrecord.
	TableRecord (TableRecordRep *parent, RecordType type)
Private Attributes
COWPtr< TableRecordRep >	rep_p
	The TableRecord representation.
TableRecordRep *	parent_p
	The parent TableRecord.
Friends
class	TableRecordRep
AipsIO &	operator<< (AipsIO &os, const TableRecord &rec)
	Write the TableRecord to an output stream.
AipsIO &	operator>> (AipsIO &os, TableRecord &rec)
	Read the TableRecord from an input stream.

virtual void casa::TableRecord::setComment	(	const RecordFieldId &	,
		const String &	comment
	)			`[virtual]`

virtual void casa::TableRecord::restructure	(	const RecordDesc &	newDescription,
		Bool	recursive = `True`
	)			`[virtual]`

void casa::TableRecord::renameField	(	const String &	newName,
		const RecordFieldId &
	)

void casa::TableRecord::defineRecord	(	const RecordFieldId &	,
		const TableRecord &	value,
		RecordType	type = `Variable`
	)

virtual void casa::TableRecord::defineRecord	(	const RecordFieldId &	,
		const RecordInterface &	value,
		RecordType	= `Variable`
	)			`[virtual]`

void casa::TableRecord::defineTable	(	const RecordFieldId &	,
		const Table &	value,
		RecordType	type = `Variable`
	)

Table casa::TableRecord::asTable	(	const RecordFieldId &	,
		const TableLock &	lockOptions
	)			const

void casa::TableRecord::mergeField	(	const TableRecord &	other,
		const RecordFieldId &	,
		DuplicatesFlag	= `ThrowOnDuplicates`
	)

void casa::TableRecord::merge	(	const TableRecord &	other,
		DuplicatesFlag	= `ThrowOnDuplicates`
	)

void casa::TableRecord::renameTables	(	const String &	newParentName,
		const String &	oldParentName
	)			`[inline]`

void casa::TableRecord::putRecord	(	AipsIO &	os,
		const TableAttr &
	)			const

void casa::TableRecord::getRecord	(	AipsIO &	os,
		const TableAttr &
	)

void casa::TableRecord::putData	(	AipsIO &	os,
		const TableAttr &
	)			const `[inline]`

void casa::TableRecord::getData	(	AipsIO &	os,
		uInt	version,
		const TableAttr &
	)			`[inline]`

virtual void casa::TableRecord::print	(	std::ostream &	,
		Int	maxNrValues = `25`,
		const String &	indent = `""`
	)			const `[virtual]`

void casa::TableRecord::setTableAttr	(	const TableRecord &	other,
		const TableAttr &	defaultAttr
	)

virtual void* casa::TableRecord::get_pointer	(	Int	whichField,
		DataType	type
	)			const `[protected, virtual]`

virtual void casa::TableRecord::addDataField	(	const String &	name,
		DataType	type,
		const IPosition &	shape,
		Bool	fixedShape,
		const void *	value
	)			`[protected, virtual]`

virtual void casa::TableRecord::defineDataField	(	Int	whichField,
		DataType	type,
		const void *	value
	)			`[protected, virtual]`

casa::TableRecord Class Reference [Tables]

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

To Do

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

casa::TableRecord Class Reference
[Tables]

AipsIO& operator<<	(	AipsIO &	os,
		const TableRecord &	rec
	)			`[friend]`