Loading...
Searching...
No Matches
casacore::RecordDesc Class Reference
casa package (libcasa_casa) » Containers_module

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

- DataType
- Record

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

## Constructor & Destructor Documentation

## RecordDesc() [1/2]

casacore::RecordDesc::RecordDesc | ( |  | ) |

inline

Create a description with no fields.

Definition at line 302 of file RecordDesc.h.

References desc_p.

Referenced by addField(), conform(), isDisjoint(), isEqual(), isStrictSubset(), isStrictSuperset(), isSubset(), isSuperset(), merge(), mergeField(), operator!=(), operator<<, operator<<, operator=(), operator==(), operator>>, RecordDesc(), rwSubRecord(), and subRecord().

## RecordDesc() [2/2]

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

inline

Create a description which is a copy of other.

Definition at line 306 of file RecordDesc.h.

References desc_p, and RecordDesc().

## ~RecordDesc()

casacore::RecordDesc::~RecordDesc | ( |  | ) |

inline

Definition at line 318 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 333 of file RecordDesc.h.

References desc_p, and RecordDesc().

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

References casacore::dataType(), and 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 326 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 339 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 345 of file RecordDesc.h.

References desc_p.

Referenced by 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 463 of file RecordDesc.h.

References desc_p, and RecordDesc().

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

References desc_p.

## get()

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

private

Referenced by operator>>.

## isArray()

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

inline

Returns True if whichField is an array.

Definition at line 414 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 493 of file RecordDesc.h.

References desc_p, and RecordDesc().

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

References desc_p, and RecordDesc().

## isScalar()

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

inline

Returns True if whichField is a scalar.

Definition at line 419 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 478 of file RecordDesc.h.

References desc_p, and RecordDesc().

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

References desc_p, and RecordDesc().

## isSubRecord()

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

inline

Returns True if whichField is a sub-record.

Definition at line 424 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 473 of file RecordDesc.h.

References desc_p, and RecordDesc().

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

References desc_p, and RecordDesc().

## isTable()

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

inline

Returns True if whichField is a table.

Definition at line 429 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 404 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 368 of file RecordDesc.h.

References desc_p, and RecordDesc().

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

References desc_p, and RecordDesc().

## name()

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

inline

What is the name of the given field.

Definition at line 409 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 389 of file RecordDesc.h.

References desc_p.

## operator!=()

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

inline

Definition at line 459 of file RecordDesc.h.

References desc_p, and RecordDesc().

## operator=()

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

inline

Replace this description with other.

Definition at line 310 of file RecordDesc.h.

References desc_p, and RecordDesc().

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

References desc_p, and RecordDesc().

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

Referenced by operator<<, and operator<<.

## 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 374 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 379 of file RecordDesc.h.

References desc_p.

## rwSubRecord()

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

inline

Definition at line 449 of file RecordDesc.h.

References desc_p, and RecordDesc().

## setComment()

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

inline

Set the comment for this field.

Definition at line 350 of file RecordDesc.h.

References comment(), and desc_p.

## 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 355 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 434 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 444 of file RecordDesc.h.

References desc_p, and RecordDesc().

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 439 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 394 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 399 of file RecordDesc.h.

References desc_p, and name().

## Friends And Related Symbol Documentation

## operator<< [1/2]

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

friend

Definition at line 503 of file RecordDesc.h.

References put(), and RecordDesc().

## operator<< [2/2]

ostream & operator<< | ( | ostream & | os,
|  | const RecordDesc & | desc )

friend

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

Definition at line 499 of file RecordDesc.h.

References put(), and RecordDesc().

## operator>>

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

friend

Definition at line 507 of file RecordDesc.h.

References get(), and RecordDesc().

## Member Data Documentation

## desc_p

COWPtr<RecordDescRep> casacore::RecordDesc::desc_p

private

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

Definition at line 297 of file RecordDesc.h.

Referenced by addField(), addField(), addField(), addTable(), comment(), conform(), fieldNumber(), isArray(), isDisjoint(), isEqual(), isScalar(), isStrictSubset(), isStrictSuperset(), isSubRecord(), isSubset(), isSuperset(), isTable(), makeName(), merge(), mergeField(), name(), nfields(), operator!=(), operator=(), operator==(), RecordDesc(), RecordDesc(), 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