casacore
Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
casacore::RecordDesc Class Reference

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...
 
RecordDescoperator= (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 Stringcomment (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 Stringname (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 IPositionshape (Int whichField) const
 What is the shape of the given field. More...
 
const StringtableDescName (Int whichField) const
 What is the name of the table description. More...
 
const RecordDescsubRecord (Int whichField) const
 If whichField is a sub-record return its description. More...
 
RecordDescrwSubRecord (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...
 
AipsIOput (AipsIO &os) const
 
AipsIOget (AipsIO &os)
 

Private Attributes

COWPtr< RecordDescRepdesc_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...
 
AipsIOoperator<< (AipsIO &os, const RecordDesc &desc)
 
AipsIOoperator>> (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:

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

Definition at line 105 of file RecordDesc.h.

Constructor & Destructor Documentation

◆ RecordDesc() [1/2]

casacore::RecordDesc::RecordDesc ( )
inline

Create a description with no fields.

Definition at line 305 of file RecordDesc.h.

◆ RecordDesc() [2/2]

casacore::RecordDesc::RecordDesc ( const RecordDesc other)
inline

Create a description which is a copy of other.

Definition at line 309 of file RecordDesc.h.

◆ ~RecordDesc()

casacore::RecordDesc::~RecordDesc ( )
inline

Definition at line 321 of file RecordDesc.h.

Member Function Documentation

◆ addField() [1/3]

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.

◆ addField() [2/3]

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.

◆ addField() [3/3]

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, and shape().

◆ addTable()

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, and tableDescName().

◆ comment()

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::RecordRep::comment(), casacore::TableRecordRep::comment(), and setComment().

◆ conform()

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.

◆ fieldNumber()

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.

◆ get()

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

◆ isArray()

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.

◆ isDisjoint()

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.

◆ isEqual()

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.

◆ isScalar()

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.

◆ isStrictSubset()

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.

◆ isStrictSuperset()

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.

◆ isSubRecord()

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.

◆ isSubset()

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.

◆ isSuperset()

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.

◆ isTable()

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.

◆ makeName()

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.

◆ merge()

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.

◆ mergeField()

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.

◆ name()

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.

Referenced by uniqueName().

◆ nfields()

uInt casacore::RecordDesc::nfields ( ) const
inline

Number of fields in the description.

Definition at line 392 of file RecordDesc.h.

References desc_p.

◆ operator!=()

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

Definition at line 462 of file RecordDesc.h.

References desc_p.

◆ operator=()

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

Replace this description with other.

Definition at line 313 of file RecordDesc.h.

References desc_p.

◆ operator==()

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.

◆ put() [1/2]

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

◆ put() [2/2]

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

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

◆ removeField()

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.

◆ renameField()

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::RecordRep::renameField(), and casacore::TableRecordRep::renameField().

◆ rwSubRecord()

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

Definition at line 452 of file RecordDesc.h.

References desc_p.

◆ setComment()

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 comment(), and desc_p.

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

◆ setShape()

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, and shape().

◆ shape()

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.

Referenced by addField(), and setShape().

◆ subRecord()

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

◆ tableDescName()

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.

Referenced by addTable().

◆ type()

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.

◆ uniqueName()

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, and name().

Friends And Related Function Documentation

◆ operator<< [1/2]

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

Definition at line 506 of file RecordDesc.h.

◆ operator<< [2/2]

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.

◆ operator>>

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

Definition at line 510 of file RecordDesc.h.

Member Data Documentation

◆ desc_p

COWPtr<RecordDescRep> casacore::RecordDesc::desc_p
private

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