casacore
HDF5Record.h
Go to the documentation of this file.
1//# HDF5Record.h: A class to write/read a record into HDF5
2//# Copyright (C) 2008
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//# $Id$
27
28#ifndef CASA_HDF5RECORD_H
29#define CASA_HDF5RECORD_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/casa/HDF5/HDF5Object.h>
34#include <casacore/casa/HDF5/HDF5DataType.h>
35#include <casacore/casa/Containers/Record.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39 // <summary>
40 // A class to write/read a record into HDF5.
41 // </summary>
42
43 // <use visibility=export>
44
45 // <reviewed reviewer="" date="" tests="tHDF5Record.cc">
46 // </reviewed>
47
48 // <prerequisite>
49 // <li> <a href="http://hdf.ncsa.uiuc.edu">HDF5 system</a>
50 // <li> <linkto class=Record>class Record</linkto>
51 // </prerequisite>
52
53 // <synopsis>
54 // This class has a static function to write a Record (or TableRecord)
55 // into an HDF5 file by storing it as attributes for the given group.
56 // Another static function can read back the Record.
57 // It can handle all types of fields in a record.
58 // <br>
59 // A few remarks:
60 // <ul>
61 // <li> When writing the record, it first deletes all attributes of the group
62 // to be sure that the group's attributes only contain the record.
63 // <li> A Casacore Record is a recursive structure, so it is written as
64 // nested groups. The name of a subgroup is the name of the subrecord.
65 // <li> HDF5 cannot deal with empty arrays. Therefore they are written as
66 // a special compound type holding the rank and type of the empty array.
67 // <li> HDF5 cannot hold empty fixed length strings. This is solved by
68 // storing an empty string with the special value <tt>__empty__</tt>.
69 // </ul>
70 // </synopsis>
71
72 // <motivation>
73 // Record is a very important class in Casacore images, so it has to be
74 // possible to read and write them from/to HDF5.
75 // </motivation>
76
78 {
79 public:
80 // Read a record from the attributes of the given group.
81 // Nested records are read back correctly.
82 // An empty record is returned if the group does not exist.
83 static Record readRecord (const HDF5Object& parentHid,
84 const String& groupName);
85
86 // Write the record as attributes of a group of the given parent.
87 // Nested records are written as nested groups.
88 // The group is deleted first if it already exists.
89 static void writeRecord (const HDF5Object& parentHid,
90 const String& recordName,
91 const RecordInterface& rec);
92
93 // Remove the record (i.e. group) from the given parent.
94 // Nothing is done if the record does not exist.
95 static void remove (const HDF5Object& parentHid,
96 const String& recordName);
97
98 // Read the (possibly nested) record values from the given group hid.
99 static Record doReadRecord (hid_t parentHid);
100
101 // Write the (possibly nested) record values into the given group hid.
102 static void doWriteRecord (const HDF5Object& groupHid,
103 const RecordInterface& rec);
104
105 private:
106 // Read a scalar value and add it to the record.
107 static void readScalar (hid_t attrId, hid_t dtid,
108 const String& name, RecordInterface& rec);
109
110 // Read an array value and add it to the record.
111 static void readArray (hid_t attrId, hid_t dtid, const IPosition&,
112 const String& name, RecordInterface& rec);
113
114 // Read a scalar string from an attribute and add it to the record.
115 static void readScaString (hid_t attrId, Int sz,
116 const String& name, RecordInterface& rec);
117
118 // Read a array of strings from an atrribute and add it to the record.
119 static void readArrString (hid_t attrId, const IPosition&,
120 const String& name, RecordInterface& rec);
121
122 // Read a field containing an empty array.
123 static void readEmptyArray (hid_t attrId,
124 const String& name, RecordInterface& rec);
125
126 // Read a field containing a scalar of fixed length.
127 template<typename T>
128 static void readSca (hid_t attrId, const String& name,
129 RecordInterface& rec)
130 {
131 T value;
132 HDF5DataType dtype((T*)0);
133 read (attrId, &value, dtype);
134 rec.define (name, value);
135 }
136
137 // Read a field containing an array of fixed length elements.
138 template<typename T>
139 static void readArr (hid_t attrId, const IPosition& shape,
140 const String& name,
141 RecordInterface& rec)
142 {
144 HDF5DataType dtype((T*)0);
145 read (attrId, value.data(), dtype);
146 rec.define (name, value);
147 }
148
149 // Read fixed length values from an attribute (scalar and array).
150 static void read (hid_t attrId, void* value,
151 const HDF5DataType& dtype);
152
153 // Write a fixed length scalar value as attribute.
154 static void writeScalar (hid_t parentHid, const String& name,
155 const void* value,
156 const HDF5DataType& dtype);
157
158 // Write an array of fixed length values as attribute.
159 static void writeArray (hid_t parentHid, const String& name,
160 const void* value, const IPosition& shape,
161 const HDF5DataType& dtype);
162
163 // Write a scalar string as attribute.
164 // HDF5 cannot handle empty strings, so for empty strings a special
165 // value is written.
166 static void writeScaString (hid_t parentHid, const String& name,
167 const String& value);
168
169 // Write an array of strings as attribute.
170 // HDF5 cannot handle empty strings, so for empty strings a special
171 // value is written.
172 static void writeArrString (hid_t parentHid, const String& name,
173 const Array<String>& value);
174
175 // Write a field containing an empty array.
176 static void writeEmptyArray (hid_t groupHid, const String& name,
177 Int rank, DataType dtype);
178
179 // Write a field containing a fixed length scalar value.
180 template<typename T>
181 static void writeSca (hid_t parentHid, const String& name,
182 const RecordInterface& rec, Int i)
183 {
184 T value;
185 rec.get (i, value);
186 HDF5DataType dtype((T*)0);
187 writeScalar (parentHid, name, &value, dtype);
188 }
189
190 // Write a field containing an array of fixed length elements.
191 template<typename T>
192 static void writeArr (hid_t parentHid, const String& name,
193 const RecordInterface& rec, Int i)
194 {
196 rec.get (i, value);
197 HDF5DataType dtype((T*)0);
198 writeArray (parentHid, name, value.data(), value.shape(), dtype);
199 }
200
201 };
202
203}
204
205#endif
static void writeArrString(hid_t parentHid, const String &name, const Array< String > &value)
Write an array of strings as attribute.
static void readArrString(hid_t attrId, const IPosition &, const String &name, RecordInterface &rec)
Read a array of strings from an atrribute and add it to the record.
static void writeEmptyArray(hid_t groupHid, const String &name, Int rank, DataType dtype)
Write a field containing an empty array.
static void remove(const HDF5Object &parentHid, const String &recordName)
Remove the record (i.e.
static void readSca(hid_t attrId, const String &name, RecordInterface &rec)
Read a field containing a scalar of fixed length.
Definition: HDF5Record.h:128
static Record readRecord(const HDF5Object &parentHid, const String &groupName)
Read a record from the attributes of the given group.
static void readEmptyArray(hid_t attrId, const String &name, RecordInterface &rec)
Read a field containing an empty array.
static void readArr(hid_t attrId, const IPosition &shape, const String &name, RecordInterface &rec)
Read a field containing an array of fixed length elements.
Definition: HDF5Record.h:139
static void writeRecord(const HDF5Object &parentHid, const String &recordName, const RecordInterface &rec)
Write the record as attributes of a group of the given parent.
static void writeScaString(hid_t parentHid, const String &name, const String &value)
Write a scalar string as attribute.
static Record doReadRecord(hid_t parentHid)
Read the (possibly nested) record values from the given group hid.
static void writeSca(hid_t parentHid, const String &name, const RecordInterface &rec, Int i)
Write a field containing a fixed length scalar value.
Definition: HDF5Record.h:181
static void doWriteRecord(const HDF5Object &groupHid, const RecordInterface &rec)
Write the (possibly nested) record values into the given group hid.
static void readScaString(hid_t attrId, Int sz, const String &name, RecordInterface &rec)
Read a scalar string from an attribute and add it to the record.
static void writeArr(hid_t parentHid, const String &name, const RecordInterface &rec, Int i)
Write a field containing an array of fixed length elements.
Definition: HDF5Record.h:192
static void writeScalar(hid_t parentHid, const String &name, const void *value, const HDF5DataType &dtype)
Write a fixed length scalar value as attribute.
static void readScalar(hid_t attrId, hid_t dtid, const String &name, RecordInterface &rec)
Read a scalar value and add it to the record.
static void read(hid_t attrId, void *value, const HDF5DataType &dtype)
Read fixed length values from an attribute (scalar and array).
static void readArray(hid_t attrId, hid_t dtid, const IPosition &, const String &name, RecordInterface &rec)
Read an array value and add it to the record.
static void writeArray(hid_t parentHid, const String &name, const void *value, const IPosition &shape, const HDF5DataType &dtype)
Write an array of fixed length values as attribute.
const IPosition & shape() const
Return the shape of the Lattice including all degenerate axes (ie.
void define(const RecordFieldId &, Bool value)
Define a value for the given field.
void get(const RecordFieldId &, Bool &value) const
Get the value of the given field.
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
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
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.