A hierarchical collection of named fields of various types. More...

#include <Record.h>

Inheritance diagram for casacore::Record:

Public Member Functions
	Record ()
	Create a record with no fields. More...

	Record (RecordType type, CheckFieldFunction =0, const void checkArgument=0)
	Create a record with no fields. More...

	Record (const RecordDesc &description, RecordType type=Fixed, CheckFieldFunction =0, const void checkArgument=0)
	Create a record with the given description. More...

	Record (const Record &other)
	Create a copy of other using copy semantics. More...

	Record (const RecordInterface &other)
	Create a Record from another type of record using copy semantics. More...

Record &	operator= (const Record &other)
	Copy the data in the other record to this record. More...

virtual	~Record ()
	Release resources associated with this object. More...

virtual RecordInterface *	clone () const
	Make a copy of this object. More...

virtual void	assign (const RecordInterface &that)
	Assign that RecordInterface object to this one. More...

virtual const String &	comment (const RecordFieldId &) const
	Get the comment for this field. More...

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

const RecordDesc &	description () const
	Describes the current structure of this Record. More...

virtual void	restructure (const RecordDesc &newDescription, Bool recursive=True)
	Change the structure of this Record to contain the fields in newDescription. More...

Bool	conform (const Record &other) const
	Returns True if this and other have the same RecordDesc, other than different names for the fields. More...

virtual uInt	nfields () const
	How many fields does this structure have? A convenient synonym for `description().nfields()`. More...

virtual Int	fieldNumber (const String &fieldName) const
	Get the field number from the field name. More...

virtual DataType	type (Int whichField) const
	Get the data type of this field. More...

void	removeField (const RecordFieldId &)
	Remove a field from the record. More...

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

void	defineRecord (const RecordFieldId &, const Record &value, RecordType type=Variable)
	Define a value for the given field containing a subrecord. More...

virtual void	defineRecord (const RecordFieldId &, const RecordInterface &value, RecordType=Variable)

const Record &	subRecord (const RecordFieldId &) const
	Get the subrecord from the given field. More...

Record &	rwSubRecord (const RecordFieldId &)

virtual const RecordInterface &	asRecord (const RecordFieldId &) const

virtual RecordInterface &	asrwRecord (const RecordFieldId &)

virtual ValueHolder	asValueHolder (const RecordFieldId &) const
	Get or define the value as a ValueHolder. More...

virtual void	defineFromValueHolder (const RecordFieldId &, const ValueHolder &)

void	mergeField (const Record &other, const RecordFieldId &, DuplicatesFlag=ThrowOnDuplicates)
	Merge a field from another record into this record. More...

void	merge (const Record &other, DuplicatesFlag=ThrowOnDuplicates)
	Merge all fields from the other record into this record. More...

void	putRecord (AipsIO &os) const
	Write the Record to an output stream. More...

void	getRecord (AipsIO &os)
	Read the Record from an input stream. More...

void	putData (AipsIO &os) const
	Put the data of a record. More...

void	getData (AipsIO &os, uInt version)
	Read the data of a record. More...

virtual void	makeUnique ()
	Make a unique record representation (to do copy-on-write in RecordFieldPtr). More...

virtual void	print (std::ostream &, Int maxNrValues=25, const String &indent="") const
	Print the contents of the record. More...

Public Member Functions inherited from casacore::RecordInterface
	RecordInterface ()
	The default constructor creates an empty record with a variable structure. More...

	RecordInterface (RecordType type, CheckFieldFunction funcPtr, const void checkArgument)
	Create a record with no fields. More...

	RecordInterface (const RecordInterface &other)
	Copy constructor (copy semantics). More...

RecordInterface &	operator= (const RecordInterface &other)
	Assignment (copy semantics). More...

virtual	~RecordInterface ()
	Destruct the record. More...

Bool	isFixed () const
	Is the Record structure fixed (i.e. More...

uInt	size () const

bool	empty () const
	Is the record empty? More...

Int	idToNumber (const RecordFieldId &) const
	Get the field number for the given field id. More...

Bool	isDefined (const String &fieldName) const
	Test if a field name exists. More...

DataType	dataType (const RecordFieldId &) const

String	name (const RecordFieldId &) const
	Get the name of this field. More...

IPosition	shape (const RecordFieldId &) const
	Get the actual shape of this field. More...

RecordDesc	description () const
	Get the description of this record. More...

void	define (const RecordFieldId &, Bool value)
	Define a value for the given field. More...

void	define (const RecordFieldId &, uChar value)

void	define (const RecordFieldId &, Short value)

void	define (const RecordFieldId &, Int value)

void	define (const RecordFieldId &, uInt value)

void	define (const RecordFieldId &, Int64 value)

void	define (const RecordFieldId &, Float value)

void	define (const RecordFieldId &, Double value)

void	define (const RecordFieldId &, const Complex &value)

void	define (const RecordFieldId &, const DComplex &value)

void	define (const RecordFieldId &, const Char *value)

void	define (const RecordFieldId &, const String &value)

void	define (const RecordFieldId &, const Array< Bool > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< uChar > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< Short > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< Int > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< uInt > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< Int64 > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< Float > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< Double > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< Complex > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< DComplex > &value, Bool FixedShape=False)

void	define (const RecordFieldId &, const Array< String > &value, Bool FixedShape=False)

void	get (const RecordFieldId &, Bool &value) const
	Get the value of the given field. More...

void	get (const RecordFieldId &, uChar &value) const

void	get (const RecordFieldId &, Short &value) const

void	get (const RecordFieldId &, Int &value) const

void	get (const RecordFieldId &, uInt &value) const

void	get (const RecordFieldId &, Int64 &value) const

void	get (const RecordFieldId &, Float &value) const

void	get (const RecordFieldId &, Double &value) const

void	get (const RecordFieldId &, Complex &value) const

void	get (const RecordFieldId &, DComplex &value) const

void	get (const RecordFieldId &, String &value) const

void	get (const RecordFieldId &, Array< Bool > &value) const

void	get (const RecordFieldId &, Array< uChar > &value) const

void	get (const RecordFieldId &, Array< Short > &value) const

void	get (const RecordFieldId &, Array< Int > &value) const

void	get (const RecordFieldId &, Array< uInt > &value) const

void	get (const RecordFieldId &, Array< Int64 > &value) const

void	get (const RecordFieldId &, Array< Float > &value) const

void	get (const RecordFieldId &, Array< Double > &value) const

void	get (const RecordFieldId &, Array< Complex > &value) const

void	get (const RecordFieldId &, Array< DComplex > &value) const

void	get (const RecordFieldId &, Array< String > &value) const

Bool	asBool (const RecordFieldId &) const
	The following functions get the value based on field name or number. More...

uChar	asuChar (const RecordFieldId &) const

Short	asShort (const RecordFieldId &) const

Int	asInt (const RecordFieldId &) const

uInt	asuInt (const RecordFieldId &) const

Int64	asInt64 (const RecordFieldId &) const

Float	asFloat (const RecordFieldId &) const

Double	asDouble (const RecordFieldId &) const

Complex	asComplex (const RecordFieldId &) const

DComplex	asDComplex (const RecordFieldId &) const

const String &	asString (const RecordFieldId &) const

const Array< Bool > &	asArrayBool (const RecordFieldId &) const

const Array< uChar > &	asArrayuChar (const RecordFieldId &) const

const Array< Short > &	asArrayShort (const RecordFieldId &) const

const Array< Int > &	asArrayInt (const RecordFieldId &) const

const Array< uInt > &	asArrayuInt (const RecordFieldId &) const

const Array< Int64 > &	asArrayInt64 (const RecordFieldId &) const

const Array< Float > &	asArrayFloat (const RecordFieldId &) const

const Array< Double > &	asArrayDouble (const RecordFieldId &) const

const Array< Complex > &	asArrayComplex (const RecordFieldId &) const

const Array< DComplex > &	asArrayDComplex (const RecordFieldId &) const

const Array< String > &	asArrayString (const RecordFieldId &) const

Array< Bool >	toArrayBool (const RecordFieldId &) const
	Get an array while promoting the data as needed. More...

Array< uChar >	toArrayuChar (const RecordFieldId &) const

Array< Short >	toArrayShort (const RecordFieldId &) const

Array< Int >	toArrayInt (const RecordFieldId &) const

Array< uInt >	toArrayuInt (const RecordFieldId &) const

Array< Int64 >	toArrayInt64 (const RecordFieldId &) const

Array< Float >	toArrayFloat (const RecordFieldId &) const

Array< Double >	toArrayDouble (const RecordFieldId &) const

Array< Complex >	toArrayComplex (const RecordFieldId &) const

Array< DComplex >	toArrayDComplex (const RecordFieldId &) const

Array< String >	toArrayString (const RecordFieldId &) const

void	toArray (const RecordFieldId &id, Array< Bool > &array) const

void	toArray (const RecordFieldId &id, Array< uChar > &array) const

void	toArray (const RecordFieldId &id, Array< Short > &array) const

void	toArray (const RecordFieldId &id, Array< Int > &array) const

void	toArray (const RecordFieldId &id, Array< uInt > &array) const

void	toArray (const RecordFieldId &id, Array< Int64 > &array) const

void	toArray (const RecordFieldId &id, Array< Float > &array) const

void	toArray (const RecordFieldId &id, Array< Double > &array) const

void	toArray (const RecordFieldId &id, Array< Complex > &array) const

void	toArray (const RecordFieldId &id, Array< DComplex > &array) const

void	toArray (const RecordFieldId &id, Array< String > &array) const

Float	asfloat (const RecordFieldId &) const
	Get value based on field name or number. More...

Double	asdouble (const RecordFieldId &) const

const Array< Float > &	asArrayfloat (const RecordFieldId &) const

const Array< Double > &	asArraydouble (const RecordFieldId &) const

Public Member Functions inherited from casacore::NoticeSource
	NoticeSource ()

virtual	~NoticeSource ()

void	notify (const Notice &note)
	Sends the `note` to all `NoticeTarget`s in the target list. More...

Protected Member Functions
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. More...

virtual void *	get_pointer (Int whichField, DataType type, const String &recordType) const

const RecordRep &	ref () const
	Return a const reference to the underlying RecordRep. More...

RecordRep &	rwRef ()
	Return a non-const reference to the underlying RecordRep. More...

virtual void	addDataField (const String &name, DataType type, const IPosition &shape, Bool fixedShape, const void *value)
	Add a field to the record. More...

virtual void	defineDataField (Int whichField, DataType type, const void *value)
	Define a value in the given field. More...

Protected Member Functions inherited from casacore::RecordInterface
void	throwIfFixed () const
	Check if the Record has a non-fixed structure. More...

void	checkName (const String &fieldName, DataType type) const
	Check if the new field name is correct. More...

RecordType &	recordType ()
	Give access to the RecordType flag (write-access is needed when a record is read back). More...

RecordType	recordType () const

Int	newIdToNumber (const RecordFieldId &) const
	Get the field number for the given field id. More...

void	defineField (const RecordFieldId &, DataType type, const void *value)
	Add a scalar field with the given type and value. More...

void	defineField (const RecordFieldId &, DataType type, const IPosition &shape, Bool fixedShape, const void *value)
	Add an array field with the given type, shape and value. More...

Private Member Functions
virtual RecordDesc	getDescription () const
	Get the description of this record. More...

	Record (RecordRep *parent, const RecordDesc &description)
	Create Record as a subrecord. More...

	Record (RecordRep *parent, RecordType type)

Private Attributes
COWPtr< RecordRep >	rep_p
	The Record representation. More...

RecordRep *	parent_p
	The parent Record. More...

Friends
class	RecordRep

AipsIO &	operator<< (AipsIO &os, const Record &rec)
	Write the Record to an output stream. More...

AipsIO &	operator>> (AipsIO &os, Record &rec)
	Read the Record from an input stream. More...

Additional Inherited Members
Public Types inherited from casacore::RecordInterface
enum	RecordType { Fixed, Variable }
	Define the flag telling if a Record has a fixed or variable structure. More...

enum	DuplicatesFlag { RenameDuplicates, SkipDuplicates, OverwriteDuplicates, ThrowOnDuplicates }
	Define the Duplicates flag for the function merge in the various record classes. More...

typedef Bool	CheckFieldFunction (const String &fieldName, DataType dataType, const void *extraArgument, String &message)
	Define the signature of the add callback function. More...

Detailed Description

A hierarchical collection of named fields of various types.

Intended use:

Public interface

Review Status

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

Prerequisite

Etymology

``Record'' is a widely used term in both programming languages and data structures to denote an imhogeneous set of fields. An alternative would have been to name it structure, which would have perhaps been a clearer name for C++ programmers.

Synopsis

Class RecordInterface decribes the fundamental properties of records.
The Record class is a particular type of a record class. The fields in Record may be of scalar type, array type, or a Record. 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 Record is not a space-efficient way of storing small objects.

The structure of a Record is defined by the RecordDesc class. The structure of the Record 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 (file="Notice.h"))Notice classes).
It is possible to add or remove fields once a Record is constructed. However, this is not possible when the Record is constructed with a fixed structure (i.e. with the fixedStructure flag set).

A Record is an hierarchical structure, because it can have fields containing Record'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 Record 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.

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

Example

Suppose we wanted to create a records that describe the favorite example of the OO world - an employee:

RecordDesc employeeDesc;
employeeDesc.addField ("name", TpString);
employeeDesc.addField ("salary", TpDouble);

The above creates the description (structure) for some record objects.

Record employeeA(employeeDesc);

Record employeeB(employeeDesc, False);

And these two lines create Record objects which share this common structure. The first Record has a fixed structure, the 2nd variable.

RecordFieldPtr<String> nameA(employeeA, 0);
RecordFieldPtr<String> nameB(employeeB, 0);
RecordFieldPtr<double> salaryA(employeeA, 1);
RecordFieldPtr<double> salaryB(employeeB, "salary");

This shows how we can get access to the individual fields. The fields are fundamentally identified by number, but the number can be looked up through the use of the fieldNumber member function.

nameA.define ("Tim");
nameB.define ("Brian");
salaryA.define (1.0e+8);
salaryB.define (1.0 / *salaryA);

Once obtained, the fields are readily manipulated, as shown above. Note that the field values are obtained through the dereference (*) operator. This is to identify that the field objects are pointers to the values in the underlying Record; that is

salaryA = salaryB;

*salaryA = *salaryB;

Do very different things; the first line is a pointer copy; salaryA and salaryB now point to the same field in salaryB. The second line is a value copy.

Whole records can be copied as long as their structures are compatible, so that employeeA = employeeB is a legal statement. However, if the structure is changed, assignment is no longer possible, and all of the field pointers are invalidated:

employeeB.define ("age", (Int)40);

employeeA = employeeB; // exception - no longer conformant

Motivation

Collections of data with different types are frequently needed. Record makes it possible to hold such data in a flexible way.

To Do

A record reference class, which contains some fields from another record, would likely be useful. This would be analagous to a subarray sliced from an existing array.

Definition at line 180 of file Record.h.

Constructor & Destructor Documentation

casacore::Record::Record ( )

Create a record with no fields.

The record has a variable structure.

casacore::Record::Record	(	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).

casacore::Record::Record	(	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).

casacore::Record::Record ( const Record & other )

Create a copy of other using copy semantics.

casacore::Record::Record ( const RecordInterface & other )

Create a Record from another type of record using copy semantics.

Subrecords are also converted to a Record.

virtual casacore::Record::~Record ( )

virtual

Release resources associated with this object.

casacore::Record::Record	(	RecordRep *	parent,
		const RecordDesc &	description
	)

private

Create Record as a subrecord.

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

casacore::Record::Record	(	RecordRep *	parent,
		RecordType	type
	)

private

Member Function Documentation

virtual void casacore::Record::addDataField	(	const String &	name,
		DataType	type,
		const IPosition &	shape,
		Bool	fixedShape,
		const void *	value
	)

protectedvirtual

Add a field to the record.

void casacore::Record::defineRecord	(	const RecordFieldId &	,
		const Record &	value,
		RecordType	type = `Variable`
	)

void casacore::Record::merge	(	const Record &	other,
		DuplicatesFlag	= `ThrowOnDuplicates`
	)

void casacore::Record::mergeField	(	const Record &	other,
		const RecordFieldId &	,
		DuplicatesFlag	= `ThrowOnDuplicates`
	)

void casacore::Record::renameField	(	const String &	newName,
		const RecordFieldId &
	)

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Friends

Additional Inherited Members