casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
HDF5DataType.h
Go to the documentation of this file.
1 //# HDF5DataType.h: An class representing an HDF5 data type
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_HDF5DATATYPE_H
29 #define CASA_HDF5DATATYPE_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
38 #include <vector>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42  //# Forward Declarations
43  class IPosition;
44  template<typename T> class Block;
45 
46  // <summary>
47  // A class representing an HDF5 data type.
48  // </summary>
49 
50  // <use visibility=local>
51 
52  // <reviewed reviewer="" date="" tests="tHDF5DataType.cc">
53  // </reviewed>
54 
55  // <prerequisite>
56  // <li> <a href="http://hdf.ncsa.uiuc.edu">HDF5 system</a>
57  // </prerequisite>
58 
59  // <synopsis>
60  // This class wraps the HDF5 functions to create a data type
61  // for the data in memory and for the file.
62  // The HDF5 file data type order is set to LittleEndian.
63  // <br>
64  // The basic constructors define a scalar of a basic data type or
65  // data type Complex and DComplex. Strings are also supported.
66  // However, it is also possible to define a fixed shaped array for any
67  // HDF5DataType. Furthermore, it is possible to define a compound data
68  // type consisting of named fields of any HDF5DataType with a fixed size.
69  // Arrays and/or compounds can be nested at will.
70  // <br>
71  // Variable length strings are supported, but cannot be used in compounds.
72  // <br>
73  // Older HDF5 versions did not support empty arrays. Therefore they are
74  // represented as a compound with 3 fields. Also they did not support
75  // boolean values; they are represented as a signed char.
76  // HDF5 does not support complex values either. They are represented
77  // as a compound with fields 're' and 'im'.
78  // </synopsis>
79 
80  // <motivation>
81  // The HDF5 C++ interface only supports the HDF5 C functionality and
82  // resembles that to much. For instance, it does not use STL containers.
83  // It does not support non-basic data types, in particular Complex.
84  // </motivation>
85 
87  {
88  public:
89  // The default constructor makes an invalid object.
90  // It is needed to make a vector of objects.
92  : itsSize(0)
93  {}
94 
95  // Create an HDF5 datatype object for the given fixed length type.
96  // It uses the corresponding native HDF5 data type. Only for Bool it
97  // uses a uchar, because the HDF5 bool type is a uint.
98  // For the complex types it makes a compound HDF5 data type.
99  // The String type is meant for an array of strings.
100  // <group>
101  explicit HDF5DataType (const Bool*);
102  explicit HDF5DataType (const uChar*);
103  explicit HDF5DataType (const Short*);
104  explicit HDF5DataType (const uShort*);
105  explicit HDF5DataType (const Int*);
106  explicit HDF5DataType (const uInt*);
107  explicit HDF5DataType (const Int64*);
108  explicit HDF5DataType (const Float*);
109  explicit HDF5DataType (const Double*);
110  explicit HDF5DataType (const Complex*);
111  explicit HDF5DataType (const DComplex*);
112  explicit HDF5DataType (const String*);
113  // </group>
114 
115  // Create an HDF5 datatype object for a scalar string.
116  // The length of the string is part of the type.
117  explicit HDF5DataType (const String& value);
118 
119  // Create an HDF5 datatype object for an empty array.
120  // Both arguments are dummy (needed to distinguish the constructor).
121  // An empty array as represented as a compound data type with integer
122  // field names emptyarray, rank and casatype.
123  HDF5DataType (Int, Int);
124 
125  // Define a compound data type consisting of the given fields and types.
126  // An exception is thrown if the vectors are empty or have mismatching
127  // sizes.
128  HDF5DataType (const std::vector<String>& names,
129  const std::vector<HDF5DataType>& types);
130 
131  // Create an array of the given data type.
132  // An exception is thrown if the shape is empty.
133  HDF5DataType (const HDF5DataType&, const IPosition& shape);
134 
135  // The copy constructor makes a deep copy.
136  HDF5DataType (const HDF5DataType& that);
137 
138  // The destructor closes the HDF5 data type object.
139  ~HDF5DataType();
140 
141  // Assignment makes a deep copy.
142  HDF5DataType& operator= (const HDF5DataType& that);
143 
144  // Get the Casacore data type for the given HDF5 data type.
145  // TpRecord is returned for a compound data type.
146  static DataType getDataType (hid_t);
147 
148  // Get the HID for the data type in memory.
149  hid_t getHidMem() const
150  { return itsHidMem; }
151 
152  // Get the HID for the data type in the file.
153  hid_t getHidFile() const
154  { return itsHidFile; }
155 
156  // Get the size in bytes of the data type (in memory).
157  // Note that the size of a string is variable, thus 0.
158  uInt size() const
159  { return itsSize; }
160 
161  // Test if the data type is Complex or DComplex.
162  static Bool isComplex (hid_t dtid);
163 
164  // Test if the data type is an empty array.
165  static Bool isEmptyArray (hid_t dtid);
166 
167  // Get the shape of an array data type.
168  // It returns an empty IPosition for non-arrays.
169  static IPosition getShape (hid_t dtid);
170 
171  // Helper functions to convert shapes.
172  // It reverses the axes, because HDF5 uses C-order.
173  // <group>
174  static Block<hsize_t> fromShape (const IPosition& shape);
175  static IPosition toShape (const Block<hsize_t>& b);
176  // </group>
177 
178  private:
179  // Add a field to a compound data type.
180  // It does it for the memory and file data type.
181  void addToCompound (const char* name,
182  uInt offset,
183  const HDF5DataType& dtype);
184 
185  //# Data members
189  };
190 
191 }
192 
193 #endif
A Vector of integers, for indexing into Array&lt;T&gt; objects.
Definition: IPosition.h:118
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
int Int
Definition: aipstype.h:50
static IPosition getShape(hid_t dtid)
Get the shape of an array data type.
HDF5HidDataType itsHidFile
Definition: HDF5DataType.h:187
void addToCompound(const char *name, uInt offset, const HDF5DataType &dtype)
Add a field to a compound data type.
HDF5DataType()
The default constructor makes an invalid object.
Definition: HDF5DataType.h:91
A class representing an HDF5 data type.
Definition: HDF5DataType.h:86
unsigned char uChar
Definition: aipstype.h:47
HDF5HidDataType itsHidMem
Definition: HDF5DataType.h:186
static Block< hsize_t > fromShape(const IPosition &shape)
Helper functions to convert shapes.
short Short
Definition: aipstype.h:48
~HDF5DataType()
The destructor closes the HDF5 data type object.
uInt size() const
Get the size in bytes of the data type (in memory).
Definition: HDF5DataType.h:158
HDF5DataType & operator=(const HDF5DataType &that)
Assignment makes a deep copy.
static Bool isComplex(hid_t dtid)
Test if the data type is Complex or DComplex.
double Double
Definition: aipstype.h:55
static IPosition toShape(const Block< hsize_t > &b)
hid_t getHidFile() const
Get the HID for the data type in the file.
Definition: HDF5DataType.h:153
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
A class representing an HDF5 datatype hid.
Definition: HDF5HidMeta.h:102
static DataType getDataType(hid_t)
Get the Casacore data type for the given HDF5 data type.
float Float
Definition: aipstype.h:54
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:1987
simple 1-D array
Definition: Allocator.h:210
hid_t getHidMem() const
Get the HID for the data type in memory.
Definition: HDF5DataType.h:149
String: the storage and methods of handling collections of characters.
Definition: String.h:225
static Bool isEmptyArray(hid_t dtid)
Test if the data type is an empty array.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
unsigned int uInt
Definition: aipstype.h:51
unsigned short uShort
Definition: aipstype.h:49