Topics
	Containers_module_internal_classes
	Internal Containers_module classes and functions.

Classes
class	casacore::ArrayInitPolicy
	More...
struct	casacore::Allocator_private::AllocSpec< T >
	Allocator specifier. More...
struct	casacore::AllocSpec< T >
	Allocator specifier. More...
class	casacore::BlockTrace
	More...
class	casacore::Block< T >
	simple 1-D array More...
class	casacore::PtrBlock< T >
	A drop-in replacement for Block<T*>. More...
struct	casacore::BlockIO_global_functions_BlockIO
	More...
class	casacore::IterError
	More...
class	casacore::IterBoundaryError
	Iteration Boundary error class. More...
class	casacore::IterInitError
	Iteration initialization error. More...
class	casacore::InvalidIterError
	Invalide iteration error class. More...
class	casacore::ObjectStack< T >
	More...
class	casacore::RecordDesc
	More...
class	casacore::RORecordFieldPtr< T >
	Read-Only access to an individual field from a Record. More...
class	casacore::RecordFieldId
	More...
class	casacore::ValueHolder
	More...

Enumerations
enum	casacore::RecordType { casacore::Fixed , casacore::Variable }
	More...

Functions
	casacore::Record ()

	casacore::RecordFieldPtr ()

Detailed Description

Non-mathematical Containers

See below for an overview of the classes in this module.

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25

Synopsis

This module provides non-mathematical containers. These containers are the prototypical computer science types of containers – records and simple arrays. These classes are useful for all of the various types of low level data management. In general, these classes will have familiar semantics and an unsurprising interface. Note that Casacore used to have classes such as Map and List, but they became obsolete when the Standard C++ Library was introduced. Therefore these classes have been removed.

Most of the important classes in this module also have IO shift operators, e.g. for writing out a Block (simple array). These operators typically allow the container (and the objects it contains) to be written out to both AipsIO and the standard ostream.

The class Block has the option to trace (de)allocations for Blocks with a size above a given threshold. It uses class MemoryTrace to log the trace messages. Unlike MemoryTrace, it also works on non-Linux systems. Since class Array uses Block underneath, it makes it possible to trace Array usage.

Enumeration Type Documentation

◆ RecordType

enum casacore::RecordType

Abstract base class for Record classes

Intended use:

Public interface

Review Status

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

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.
RecordInterface denotes that this class defines the common interface to possible Record classes.

Synopsis

A Record is an heterogeneous, hierarchical, collection of named fields. The fields may be of scalar type, array type, a Table or a Record. This latter feature is what makes the Record a (potentially) hierarchical type.

RecordInterface is the abstract base class for various Record classes. At the moment three Record classes exist:

Presently, the scalar types are chosen to be compatible with the native types of the Table system, viz: Bool, uChar, Short, Int, uInt, Int64, Float, Double, Complex, DComplex, String. Arrays of all these types are also available. It is fairly straightforward to extend this set if necessary, although it will result in more template instantiations with the current implementation.

Each field has an integral index, which ranges between 0 and nfields() - 1. The values of a field can be manipulated in two ways:

Through the get and put functions in this class. They are easy to use and support type promotion. However, they are a bit less efficient than the second way.
Through the class RecordFieldPtr. This is a bit less convenient. However, it is more efficient if the same field is accessed multiple times.

The structure of a record can be fixed or variable. If fixed, it is not possible to change the structure once the record has been instantiated. If variable, the record can be restructured or fields can be added/removed.
When a field gets added, it is possible to check if its name and type are valid by means of the CheckFunction callback. This is for instance used by the table system to assure that keywords and columns in a table do not have the same name.

Arrays in a record description can be fixed or variable shaped. If fixed shaped, only arrays with that shape can be stored in that field in the record. If variable shaped, any array can be stored.
However, note there is a difference between assign and define. Assign invokes the array assignment operator which checks for conformance. Thus even for variable shaped arrays, the new array must conform the exisitng one when using assign. Define simply replaces the array, thus for variable shaped arrays ay array shape will do.

RecordFieldPtr objects attached to a Record have to be notified when the Record is deleted or changed. The RecordInterface class provides the hooks for this via the Notice system. It is derived from NoticeSource. The class RecordNotice is for the messages.

Motivation

This common base class provides a common interface to the various Record classes. Furthermore it is needed for the class RecordFieldPtr. Finally it provides the hooks for the notification in case the record structure changes.

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.

*/ class RecordInterface { public: /** Define the flag telling if a Record has a fixed or variable structure.

Enumerator
Fixed	Record has a fixed structure; that is, no fields can be added or removed once the Record is created.
Variable	Record has a variable structure; after Record creation fields can be added or removed at will.

Definition at line 145 of file RecordInterface.h.

Function Documentation

◆ Record()

casacore::Record ( )

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.
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 a 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);

casacore::Record

Record()

casacore::False

const Bool False

Definition aipstype.h:42

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

casacore::Int

int Int

Definition aipstype.h:48

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.

*/ class Record : public RecordInterface { friend class RecordRep;

public: /** Create a record with no fields. The record has a variable structure.

◆ RecordFieldPtr()

casacore::RecordFieldPtr ( )

Access to an individual field in a record.

Intended use:

Public interface

Review Status

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

Prerequisite

RecordInterface.

Etymology

RecordFieldPtr indicates that an object of this type is pointing to a field in a record.

Synopsis

RecordFieldPtr allows access to the fields in a record object. A record object is an object of a class derived from RecordInterface. RecordFieldPtr<T> objects can only be instantiated for types `T' which are valid fields of a record object (e.g. Int, float, String, Record, TableRecord). It can, however, NOT be instantiated for a Table field, because Table fields are accessed indirectly via a TableKeyword object. Table fields have to be accessed directly through the TableRecord interface.

Internally, a RecordFieldPtr stores a Record pointer and field number. Therefore, if the order of fields in a Record is modified, or if the Record is restructured, a RecordFieldPtr is invalidated and should no longer be used.

The RecordFieldPtr is pointer-like in the sense that it points to an object that is physically inside of another object (the enclosing record object). Access to the value is obtained via the dereference operator (operator*()) to emphasize the pointer like nature of these classes.
An alternative way to get access to the values is using the functions define and get. Note that in

RecordFieldPtr<Array<Int> > field (record, fieldNumber);
Array<Int> value;
*field = value;
field.define (value);

the assignment (in line 3) and define (in line 4) are not equivalent. The assignment uses the normal Array assignment, thus it takes the Array conformance rules into account (an assign is only possible when the new array value conforms the current array value or when the current array value is empty). On the other hand, define does not take the current array value into account. Thus an array value can always be redefined.
However, note that if the field is defined with a non-fixed shape in the record description, a value must always conform that shape (in case of assignment as well as in case of define).

Example

See the example in the Record class.

Motivation

RecordFieldPtr provides a fast way to access the data in a record.

*/ template<class T> class RecordFieldPtr { public: /** This object does not point to any field, i.e. this->isAttached() == False;

Topics

Classes

Enumerations

Functions

Detailed Description

Review Status

Synopsis

Enumeration Type Documentation

◆ RecordType

Intended use:

Review Status

Etymology

Synopsis

Motivation

To Do

Function Documentation

◆ Record()

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

To Do

◆ RecordFieldPtr()

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation