Attributes like fixed structure flag and check function will not
be copied.
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 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.
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
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).
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).
Create a copy of other using copy semantics.
Create a Record from another type of record using copy semantics. Subrecords are also converted to a Record.
Copy the data in the other record to this record. It can operate in 2 ways depending on the Record structure flag.
Release resources associated with this object.
Make a copy of this object.
Assign that RecordInterface object to this one. Unlike operator= it copies all data in the derived class.
Get the comment for this field.
Set the comment for this field.
Describes the current structure of this Record.
Change the structure of this Record to contain the fields in
newDescription. After calling restructure, description() ==
newDescription. Any existing RecordFieldPtr objects are
invalidated (their isAttached() members return False) after
this call.
When the new description contains subrecords, those subrecords
will be restructured if recursive=True is given.
Otherwise the subrecord is a variable empty record.
Subrecords will be variable if their description is empty (i.e. does
not contain any field), otherwise they are fixed. The 2nd form of
the restructure function will overwrite those implicit
record types with the given record type. The new type will also
be given to this top record.
Restructuring is not possible and an exception is thrown
if the Record has a fixed structure.
Returns True if this and other have the same RecordDesc, other than different names for the fields. That is, the number, type and the order of the fields must be identical (recursively for fixed structured sub-Records in this).
thisRecord.conform(thatRecord) == True does not imply
thatRecord.conform(thisRecord) == True, because a variable record in one conforms a fixed record in that, but not vice-versa.
How many fields does this structure have? A convenient synonym for description().nfields().
Get the field number from the field name. -1 is returned if the field name is unknown.
Get the data type of this field.
Remove a field from the record.
Rename the given field.
Define a value for the given field containing a subrecord. When the field is unknown, it will be added to the record. The second version is meant for any type of record (e.g. Record, TableRecord, GlishRecord). It is converted to a Record using the Record constructor taking a RecordInterface object.
Get the subrecord from the given field.
Get or define the value as a ValueHolder. This is useful to pass around a value of any supported type.
Merge a field from another record into this record. The DuplicatesFlag (as described in RecordInterface) determines what will be done in case the field name already exists.
Merge all fields from the other record into this record. The DuplicatesFlag (as described in RecordInterface) determines what will be done in case a field name already exists. An exception will be thrown if other is the same as this (i.e. if merging the record itself).
Write the Record to an output stream.
Read the Record from an input stream.
Write the Record to an output stream. This is used to write a subrecord, whose description has not been written.
Read the Record from an input stream. This is used to read a subrecord, whose description has not been read.
Put the data of a record. This is used to write a subrecord, whose description has already been written.
Read the data of a record. This is used to read a subrecord, whose description has already been read.
Make a unique record representation (to do copy-on-write in RecordFieldPtr).
Return a const reference to the underlying RecordRep.
Return a non-const reference to the underlying RecordRep. When needed, the RecordRep will be copied and all RecordField objects will be notified.
Add a field to the record.
Define a value in the given field.
Create Record as a subrecord. When the description is empty, the record has a variable structure. Otherwise it is fixed.