RecordField.h

Classes

RecordFieldPtr -- Access to an individual field in a record. (full description)

RORecordFieldPtr -- Read-Only access to an individual field from a Record. (full description)

template<class T> class RecordFieldPtr : public NoticeTarget

Interface

Public Members

RecordFieldPtr()

RecordFieldPtr (RecordInterface& record, Int whichField)

RecordFieldPtr (RecordInterface& record, const RecordFieldId&)

RecordFieldPtr (const RecordFieldPtr<T>& other)

RecordFieldPtr<T>& operator= (const RecordFieldPtr<T>& other)

~RecordFieldPtr()

void attachToRecord (RecordInterface& record, Int whichField)

void attachToRecord (RecordInterface& record, const RecordFieldId&)

void detach()

T& operator*()

const T& operator*() const

const T& get() const

void define (const T& value)

const String& comment() const

void setComment (const String& comment)

Int fieldNumber() const

Bool isAttached() const

Private Members

virtual void notify (const Notice& message)

Description

Review Status

Reviewed By:

Mark Wieringa

Date Reviewed:

1996/04/15

Programs:

Tests:

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.

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

RecordFieldPtr is derived from NoticeTarget to get messages from the mother record class when it changes. For example, when the record is destructed, all RecordFieldPtr's pointing to that record will automatically be detached.

Example

See the example in the Record class.

Motivation

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

Member Description

RecordFieldPtr()

This object does not point to any field, i.e. this->isAttached() == False;

RecordFieldPtr (RecordInterface& record, Int whichField)
RecordFieldPtr (RecordInterface& record, const RecordFieldId&)

Attach this field pointer to the given field. If it does not exist an exception is thrown.

RecordFieldPtr (const RecordFieldPtr<T>& other)
RecordFieldPtr<T>& operator= (const RecordFieldPtr<T>& other)

After calling, this and other point to the same field, i.e. it uses reference semantics.

~RecordFieldPtr()

void attachToRecord (RecordInterface& record, Int whichField)
void attachToRecord (RecordInterface& record, const RecordFieldId&)

Change our pointer to the supplied field. If it doesn't exist an exception is thrown.

void detach()

Point to no field in any Record.

T& operator()
const T& operator() const
const T& get() const

Provide access to the field's value. To be sure a const function is called, it is best to use get(). For a non-const object, a non-const function is called, even if used as an rvalue.

void define (const T& value)

Store a value in the field using redefinition. Define differs from assignment w.r.t. arrays. For define a variable shaped array is deleted first with the effect that array conformance rules are not applied for them.

const String& comment() const

Get the comment of this field.

void setComment (const String& comment)

Set the comment for this field.

Int fieldNumber() const

Return the fieldnumber of this field.

Bool isAttached() const

Is this field pointer attached to a valid record? Operations which might cause it to become detached are:

Destruction of the Record
Restructuring of the record.
Explicit call of the detach() member.

virtual void notify (const Notice& message)

Not important for users - the mechanism by which field pointers are notified when there is a change in the record.

template<class T> class RORecordFieldPtr

Interface

Public Members

RORecordFieldPtr()

RORecordFieldPtr (const RecordInterface& record, Int whichField) : fieldPtr_p((RecordInterface&)record, whichField)

RORecordFieldPtr (const RecordInterface& record, const record& id) : fieldPtr_p((RecordInterface&)record, id)

RORecordFieldPtr (const RecordFieldPtr<T>& other) : fieldPtr_p(other)

RORecordFieldPtr (const RORecordFieldPtr<T>& other) : fieldPtr_p(other.fieldPtr_p)

RORecordFieldPtr<T>& operator= (const RORecordFieldPtr<T>& other)

~RORecordFieldPtr()

void attachToRecord (const RecordInterface& record, Int whichField)

void attachToRecord (const RecordInterface& record, const RecordFieldId& id)

const T& operator*() const

const T& get() const

const String& comment() const

Int fieldNumber() const

void detach()

Bool isAttached() const

Description

Review Status

Reviewed By:

Mark Wieringa

Date Reviewed:

1996/04/15

Programs:

Tests:

tRecord

Prerequisite

RecordRecordFieldPtr.

Synopsis

This class is entirely like RecordFieldPtr, except that it only allows Read-Only access to fields in a Record. The documentation for that class should be consulted.

Note that RecordFieldPtr is not inherited from RORecordFieldPtr, because that would give problems with the function attachToRecord. It would allow RecordFieldPtr to attach to a const RecordInterface object.