casacore
HDF5.h
Go to the documentation of this file.
1 //# HDF5.h: Classes binding casa to the HDF5 C API
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_HDF5_H
29 #define CASA_HDF5_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 
34 #include <casacore/casa/HDF5/HDF5File.h>
35 #include <casacore/casa/HDF5/HDF5Group.h>
36 #include <casacore/casa/HDF5/HDF5DataSet.h>
37 #include <casacore/casa/HDF5/HDF5Record.h>
38 #include <casacore/casa/HDF5/HDF5Error.h>
39 
40 
41 namespace casacore { //# NAMESPACE CASACORE - BEGIN
42 
43 // <module>
44 //
45 // <summary>
46 // Classes binding casa to the HDF5 C API
47 // </summary>
48 
49 // <prerequisite>
50 // <li> HDF5 (see http://www.hdfgroup.uiuc.edu/HDF5/doc_dev_snapshot)
51 // </prerequisite>
52 
53 // <reviewed reviewer="" date="" demos="">
54 // </reviewed>
55 
56 // <etymology>
57 // 'HDF5' is version 5 of the Hierarchical Data Format.
58 // </etymology>
59 //
60 // <synopsis>
61 // This module's main purpose is to provide limited, but convenient
62 // access to the HDF5 C API.
63 // The classes offer the following services:
64 // <ul>
65 // <li> The burden of allocating and releasing the HDF5 resources
66 // (the so-called hid-s) is handled in an automatic and
67 // exception-safe way.
68 // <li> The overwhelming and rather hard to use HDF5 C API is hidden.
69 // <li> The standard casa data types (scalars and arrays) are fully supported.
70 // Because HDF5 does not support empty strings, they are transparantly
71 // replaced by the value '__empty__'.
72 // Unfortunately HDF5 does not support empty arrays, thus they cannot
73 // be stored.
74 // <li> A Record is stored as a group. Its values (scalars and arrays)
75 // are stored as attributes, while nested records are stored as
76 // nested groups.
77 // <li> Bool values are stored as chars.
78 // <li> Complex values are stored as compounds of two real values.
79 // <li> Large arrays can be stored in HDF5 DataSets with an optional tile size
80 // (chunk size in HDF5 terminology). The array axes are reversed (fully
81 // transparantly) because HDF5 uses C-order, while casa Arrays use
82 // Fortran-order.
83 // <li> Automatic printing of HDF5 messages is disabled. All errors are
84 // thrown as exceptions (AipsError or derived from it).
85 // </ul>
86 //
87 // The following classes are available:
88 // <ul>
89 // <li> HDF5File opens or creates an HDF5 file and closes it automatically.
90 // Furthermore it has a function to test if a file is in HDF5 format.
91 // <li> HDF5Record reads or writes a Record as a group in an HDF5 object.
92 // <li> HDF5DataSet opens or creates a possible tiled data set in an HDF5
93 // object. The array can be read or written in parts.
94 // Currently the only data types supported are Bool, Int, Float, Double,
95 // Complex, and DComplex.
96 // <li> HDF5Group opens, creates, or removes a group in an HDF5 object.
97 // </ul>
98 // Note that HDF5Object forms the base class of HDF5File, HDF5Group, and
99 // HDF5DataSet. Most interfaces use HDF5Object, thus are applicable to
100 // all these object types.
101 // <br>An HDF5Object has a conversion operator to <src>hid_t</src>, thus
102 // can be used directly in any HDF5 function.
103 //
104 // Because of HDF5 resource management the objects (e.g. HDF5File) cannot
105 // be copied. However, they can be used in shared pointers (like casa's
106 // CountedPtr or boost's shared_ptr).
107 // <br>
108 // Internally the classes use HDF5HidMeta.h which does the resource management
109 // for HDF5 meta data like attributes, property lists, etc..
110 //
111 // <note>
112 // All HDF5 classes and all their functions are compiled, but it depends on
113 // the setting of HAVE_HDF5 how. If not set, all these functions are merely stubs
114 // and the class constructors throw an exception when used.
115 // The function <src>HDF5Object::hasHDF5Support()</src> tells if HDF5 is used.
116 // See the casacore build instructions at casacore.googlecode.com
117 // for more information.
118 // </note>
119 // </synopsis>
120 
121 // <example>
122 // See the various test programs.
123 // </example>
124 //
125 // <motivation>
126 // HDF5 offers a C++ interface. However, this interface is still quite complex
127 // and is too much C-oriented.
128 // Furthermore there was the need to support the casa data types, in particular
129 // reversal of array axes was needed.
130 // </motivation>
131 
132 // <todo asof="2008/03/13">
133 // <li> Make it possible to store empty arrays (e.g. as a compound of a
134 // scalar (defining its type) and a vector (defining its shape).
135 // <li> Set the optimal data set chunk cache size from a given access pattern.
136 // The current problem is that you can only set the cache size at the
137 // HDF5 file level, not at the data set level. Furthermore, setting
138 // the cache size requires that the file is closed first.
139 // For the time being a fixed cache size of 16 MB is used instead of
140 // the default 1 MB.
141 // </todo>
142 
143 // </module>
144 
145 
146 } //# NAMESPACE CASACORE - END
147 
148 #endif
this file contains all the compiler specific defines
Definition: mainpage.dox:28