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 
37 namespace 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 
77  class HDF5Record
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  {
195  Array<T> value;
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.