casacore
RecordRep.h
Go to the documentation of this file.
1 //# RecordRep.h: The representation of a Record
2 //# Copyright (C) 1996,1997,2000,2001,2005
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //#
27 //# $Id$
28 
29 
30 #ifndef CASA_RECORDREP_H
31 #define CASA_RECORDREP_H
32 
33 //# Includes
34 #include <casacore/casa/aips.h>
35 #include <casacore/casa/Containers/Block.h>
36 #include <casacore/casa/Containers/RecordDesc.h>
37 #include <casacore/casa/Containers/RecordInterface.h>
38 
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 //# Forward Declarations
42 class AipsIO;
43 class IPosition;
44 class String;
45 
46 
47 // <summary>
48 // The representation of a Record
49 // </summary>
50 
51 // <use visibility=local>
52 // <reviewed reviewer="Mark Wieringa" date="1996/04/15" tests="tRecord">
53 // </reviewed>
54 
55 // <prerequisite>
56 // <li> <linkto class="Record">Record</linkto>.
57 // </prerequisite>
58 //
59 // <etymology>
60 // RecordRep is the REPresentation of a Record.
61 // </etymology>
62 //
63 // <synopsis>
64 // RecordRep is the actual implementation of a Record object.
65 // It contains the description and the data. The data is stored as
66 // a collection of void* pointers to the actual data. By storing
67 // it in this indirect way, it is easier to extend the data block.
68 // It also means that RecordFieldPtr objects always have the correct
69 // pointer and do not need to be adjusted when the data block is extended.
70 // <p>
71 // Despite the fact that the data pointers have type void*, the
72 // functions are completely type safe. This is done by passing the
73 // type around using the DataType enumeration. The downpart is that
74 // only types from that enumeration are supported (but that is also
75 // required by the RecordDesc mechanics).
76 // <p>
77 // Note that RecordRep does not know anything about RecordFieldPtr
78 // objects pointing to its data. Only its mother class Record
79 // knows about them and handles all cases where the RecordFieldPtr's
80 // have to be notified.
81 // </synopsis>
82 //
83 // <example>
84 // RecordRep mirrors all functions in Record.
85 // </example>
86 //
87 // <motivation>
88 // Having a separate RecordRep class makes copy-on-write possible.
89 // It also allows derivation of other RecordRep classes (like TableRecordRep),
90 // while their mother classes are not derived from each other.
91 // </motivation>
92 //
93 // <todo asof="1996/03/12">
94 // <li> An implementation where arrays are stored as T*'s would cut down on
95 // instantiations (the Arrayness would come back through the creation
96 // of the <src>RecordFieldPtr<Array<T> ></src>).
97 // </todo>
98 
99 
101 {
102 public:
103  // Create a record with no fields.
105 
106  // Create a record with the given description. If it is not possible to
107  // create all fields (for example, if a field of an unsupported type is
108  // requested), an exception is thrown.
109  // All fields are checked by the field checking function (if defined).
111 
112  // Create a copy of other using copy semantics.
113  RecordRep (const RecordRep& other);
114 
115  // Copy all the data over.
117 
118  // Delete all data.
119  virtual ~RecordRep();
120 
121  // Get the comment for this field.
122  const String& comment (Int whichField) const;
123 
124  // Set the comment for this field.
125  void setComment (Int whichField, const String& comment);
126 
127  // Describes the current structure of this Record.
128  const RecordDesc& description() const;
129 
130  // Change the structure of this Record to contain the fields in
131  // newDescription. After calling restructure, <src>description() ==
132  // newDescription</src>.
133  void restructure (const RecordDesc& newDescription, Bool recursive);
134 
135  // Returns True if this and other have the same RecordDesc, other
136  // than different names for the fields. That is, the number, type and the
137  // order of the fields must be identical (recursively for fixed
138  // structured sub-Records in this).
139  // <note role=caution>
140  // <src>thisRecord.conform(thatRecord) == True</src> does not imply
141  // <br><src>thatRecord.conform(thisRecord) == True</src>, because
142  // a variable record in one conforms a fixed record in that, but
143  // not vice-versa.
144  // </note>
145  Bool conform (const RecordRep& other) const;
146 
147  // Copy all data of the Record.
148  void copyData (const RecordRep& other);
149 
150  // Copy a data field.
151  // This can only handle scalars and arrays.
152  void copyDataField (DataType type, Int whichField, const void* that) const;
153 
154  // Remove a field from the record.
155  void removeField (Int whichField);
156 
157  // Rename the given field.
158  void renameField (const String& newName, Int whichField);
159 
160  // Add a field with the given name and value to the record.
161  // The data type of the field is determined by the data type of the value.
162  // For arrays it is possible to define if the shape is fixed.
163  // <group>
164  void addDataField (const String& name, DataType type,
165  const IPosition& shape, Bool fixedShape,
166  const void* data);
167  void addField (const String& name, const Record& value,
169  // </group>
170 
171  // Define a value for the given field.
172  // Array conformance rules will not be applied for variable shaped arrays.
173  // When the field and value data type mismatch, type promotion
174  // of scalars will be done if possible. If not possible, an exception
175  // is thrown.
176  void defineDataField (Int whichField, DataType type, const void* value);
177 
178  // Put the description and data of the Record.
179  // It also puts the fixedFlag attribute (of the mother object).
180  void putRecord (AipsIO& os, int recordType) const;
181 
182  // Get the description and data of the Record.
183  // It also gets the fixedFlag attribute (of the mother object).
184  void getRecord (AipsIO& os, Int& recordType);
185 
186  // Put the data of a record.
187  // This is used to write a subrecord, whose description has
188  // already been written.
189  void putData (AipsIO& os) const;
190 
191  // Read the data of a record.
192  // This is used to read a subrecord, whose description has
193  // already been read.
194  void getData (AipsIO& os, uInt version);
195 
196  // Used by the RecordFieldPtr classes to attach in a type-safe way to the
197  // correct field.
198  // <group>
199  void* get_pointer (Int whichField, DataType type) const;
200  void* get_pointer (Int whichField, DataType type,
201  const String& recordType) const;
202  // </group>
203 
204  // Merge a field from another record into this record.
205  void mergeField (const RecordRep& other, Int whichFieldFromOther,
207 
208  // Merge all fields from the other record into this record.
210 
211  // Print a record.
212  // Print the contents of the record.
213  // Only the first <src>maxNrValues</src> of an array will be printed.
214  // A value < 0 means the entire array.
215  void print (std::ostream&,
216  Int maxNrValues = 25,
217  const String& indent="") const;
218 
219 protected:
220  // Utility functions to avoid code duplication in the public member
221  // functions.
222  // <group>
223  void delete_myself (uInt nfields);
224  void copy_other (const RecordRep& other);
225  // </group>
226 
227  // Get the field number for a given name.
228  virtual Int fieldNumber (const String& name) const;
229 
230  // Add the data pointer to the data block.
231  // The block is extended when needed.
232  void addDataPtr (void* ptr);
233 
234  // Remove a data pointer add the given index.
235  void removeDataPtr (Int index);
236 
237  // Check if the shape of the data array matches the shape of a
238  // fixed-shaped array in the description.
239  void checkShape (DataType type, const IPosition& shape,
240  const void* value, const String& fieldName);
241 
242  // Add a field to the description.
243  virtual void addFieldToDesc (const String& name, DataType type,
244  const IPosition& shape, Bool fixedShape);
245 
246  // Remove a data field.
247  virtual void removeData (Int whichField, void* ptr, void* vecptr);
248 
249  // Remove a field from the description.
250  virtual void removeFieldFromDesc (Int whichField);
251 
252  // Create a data field for the given type and shape.
253  // This can only handle scalars and arrays.
254  void* createDataField (DataType type, const IPosition& shape);
255 
256  // Delete a data field.
257  // This can only handle scalars and arrays.
258  void deleteDataField (DataType type, void* ptr, void* vecptr);
259 
260  // Copy a data field.
261  // This can only handle scalars and arrays.
262  void copyDataField (DataType type, void* ptr, const void* that) const;
263 
264  // Print a data field.
265  // This can only handle scalars and arrays.
266  void printDataField (std::ostream& os, DataType type,
267  const String& indent, Int maxNrValues,
268  const void* ptr) const;
269 
270  // Put a data field.
271  // This can only handle scalars and arrays.
272  void putDataField (AipsIO& os, DataType type, const void* ptr) const;
273 
274  // Get a data field.
275  // This can only handle scalars and arrays.
276  void getDataField (AipsIO& os, DataType type, void* ptr);
277 
278  // Make an array for a scalar data field.
279  // It shares the data, so a change in the data is reflected in the array.
280  // It is used to be able to access a scalar as an 1D array.
281  void makeDataVec (Int whichField, DataType type);
282 
283  // Get a Scalar/ArrayKeywordSet object as a Record.
284  // (type 0 = ScalarKeywordSet; type 1 = ArrayKeywordSet).
285  void getKeySet (AipsIO& os, uInt version, uInt type);
286 
287  // Get the description of a keyword set as a RecordDesc.
288  void getKeyDesc (AipsIO& os, RecordDesc& desc);
289 
290  // Get the scalar values of a keyword set.
291  void getScalarKeys (AipsIO& os);
292 
293  // Get the array values of a keyword set.
294  void getArrayKeys (AipsIO& os);
295 
296 
297  // Holds the structure of this Record.
299  // Pointers to data values.
301  // Pointers to a vector of a scalar (to access a scalar as an array).
303  // #Entries used in data_p.
305 };
306 
307 
308 inline const RecordDesc& RecordRep::description() const
309 {
310  return desc_p;
311 }
312 
313 inline const String& RecordRep::comment (Int whichField) const
314 {
315  return desc_p.comment (whichField);
316 }
317 
318 inline void RecordRep::setComment (Int whichField, const String& comment)
319 {
320  desc_p.setComment (whichField, comment);
321 }
322 
323 inline void RecordRep::renameField (const String& newName, Int whichField)
324 {
325  desc_p.renameField (newName, whichField);
326 }
327 
328 
329 
330 } //# NAMESPACE CASACORE - END
331 
332 #endif
void renameField(const String &newName, Int whichField)
Rename the given field.
Definition: RecordDesc.h:382
const String & comment(Int whichField) const
Get the comment for this field.
Definition: RecordDesc.h:348
void setComment(Int whichField, const String &comment)
Set the comment for this field.
Definition: RecordDesc.h:353
RecordType
Define the flag telling if a Record has a fixed or variable structure.
DuplicatesFlag
Define the Duplicates flag for the function merge in the various record classes.
void merge(const RecordRep &other, RecordInterface::DuplicatesFlag)
Merge all fields from the other record into this record.
Block< void * > datavec_p
Pointers to a vector of a scalar (to access a scalar as an array).
Definition: RecordRep.h:302
void getRecord(AipsIO &os, Int &recordType)
Get the description and data of the Record.
void delete_myself(uInt nfields)
Utility functions to avoid code duplication in the public member functions.
void deleteDataField(DataType type, void *ptr, void *vecptr)
Delete a data field.
void copyDataField(DataType type, void *ptr, const void *that) const
Copy a data field.
void renameField(const String &newName, Int whichField)
Rename the given field.
Definition: RecordRep.h:323
void printDataField(std::ostream &os, DataType type, const String &indent, Int maxNrValues, const void *ptr) const
Print a data field.
void copyDataField(DataType type, Int whichField, const void *that) const
Copy a data field.
Bool conform(const RecordRep &other) const
Returns True if this and other have the same RecordDesc, other than different names for the fields.
virtual ~RecordRep()
Delete all data.
void addField(const String &name, const Record &value, RecordInterface::RecordType type)
void print(std::ostream &, Int maxNrValues=25, const String &indent="") const
Print a record.
void defineDataField(Int whichField, DataType type, const void *value)
Define a value for the given field.
void putDataField(AipsIO &os, DataType type, const void *ptr) const
Put a data field.
void removeDataPtr(Int index)
Remove a data pointer add the given index.
void getDataField(AipsIO &os, DataType type, void *ptr)
Get a data field.
void * createDataField(DataType type, const IPosition &shape)
Create a data field for the given type and shape.
void mergeField(const RecordRep &other, Int whichFieldFromOther, RecordInterface::DuplicatesFlag)
Merge a field from another record into this record.
const RecordDesc & description() const
Describes the current structure of this Record.
Definition: RecordRep.h:308
void getScalarKeys(AipsIO &os)
Get the scalar values of a keyword set.
void removeField(Int whichField)
Remove a field from the record.
RecordRep()
Create a record with no fields.
void getArrayKeys(AipsIO &os)
Get the array values of a keyword set.
void checkShape(DataType type, const IPosition &shape, const void *value, const String &fieldName)
Check if the shape of the data array matches the shape of a fixed-shaped array in the description.
void makeDataVec(Int whichField, DataType type)
Make an array for a scalar data field.
void copy_other(const RecordRep &other)
RecordRep & operator=(const RecordRep &other)
Copy all the data over.
virtual void removeFieldFromDesc(Int whichField)
Remove a field from the description.
const String & comment(Int whichField) const
Get the comment for this field.
Definition: RecordRep.h:313
void getData(AipsIO &os, uInt version)
Read the data of a record.
RecordRep(const RecordRep &other)
Create a copy of other using copy semantics.
void copyData(const RecordRep &other)
Copy all data of the Record.
void restructure(const RecordDesc &newDescription, Bool recursive)
Change the structure of this Record to contain the fields in newDescription.
virtual Int fieldNumber(const String &name) const
Get the field number for a given name.
void getKeyDesc(AipsIO &os, RecordDesc &desc)
Get the description of a keyword set as a RecordDesc.
void * get_pointer(Int whichField, DataType type) const
Used by the RecordFieldPtr classes to attach in a type-safe way to the correct field.
void putRecord(AipsIO &os, int recordType) const
Put the description and data of the Record.
Block< void * > data_p
Pointers to data values.
Definition: RecordRep.h:300
void setComment(Int whichField, const String &comment)
Set the comment for this field.
Definition: RecordRep.h:318
RecordDesc desc_p
Holds the structure of this Record.
Definition: RecordRep.h:298
void addDataPtr(void *ptr)
Add the data pointer to the data block.
void addDataField(const String &name, DataType type, const IPosition &shape, Bool fixedShape, const void *data)
Add a field with the given name and value to the record.
uInt nused_p
#Entries used in data_p.
Definition: RecordRep.h:304
void getKeySet(AipsIO &os, uInt version, uInt type)
Get a Scalar/ArrayKeywordSet object as a Record.
virtual void addFieldToDesc(const String &name, DataType type, const IPosition &shape, Bool fixedShape)
Add a field to the description.
void * get_pointer(Int whichField, DataType type, const String &recordType) const
virtual void removeData(Int whichField, void *ptr, void *vecptr)
Remove a data field.
void putData(AipsIO &os) const
Put the data of a record.
RecordRep(const RecordDesc &description)
Create a record with the given description.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition: ExprNode.h:1987
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.