casacore
HDF5.h
Go to the documentation of this file.
1 //# HDF5.h: Classes binding casacore 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 casacore 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 casacore data types (scalars and arrays) are supported.
70 // Because HDF5 does not support empty strings, they are transparantly
71 // replaced by the value '__empty__'.
72 // Also HDF5 does not support empty arrays, thus they are stored
73 // in a special way using a special compound value.
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 casacore 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 interface 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> HDF5DataType defines the HDF5 memory and file data type. It supports
92 // the basic data types, complex, string, arrays and compounds.
93 // <li> HDF5Record reads or writes a Record as a group in an HDF5 object.
94 // <li> HDF5DataSet opens or creates a possible tiled data set in an HDF5
95 // object. The array can be read or written in parts.
96 // It can be created of any HDF5DataType.
97 // <li> HDF5Group opens, creates, or removes a group in an HDF5 object.
98 // </ul>
99 // Note that HDF5Object forms the base class of HDF5File, HDF5Group, and
100 // HDF5DataSet. Most interfaces use HDF5Object, thus are applicable to
101 // all these object types.
102 // <br>An HDF5Object has a conversion operator to <src>hid_t</src>, thus
103 // can be used directly in any HDF5 function.
104 //
105 // Because of HDF5 resource management the objects (e.g. HDF5File) cannot
106 // be copied. However, they can be used in shared pointers (like casacore's
107 // CountedPtr or std::shared_ptr).
108 // <br>
109 // Internally the classes use HDF5HidMeta.h which does the resource management
110 // for HDF5 meta data like attributes, property lists, etc..
111 //
112 // <note>
113 // All HDF5 classes and all their functions are compiled, but it depends on
114 // the setting of HAVE_HDF5 how. If not set, all these functions are merely
115 // stubs and the class constructors throw an exception when used.
116 // The function <src>HDF5Object::hasHDF5Support()</src> tells if HDF5 is used.
117 // See the casacore build instructions at github.com/casacore/casacore
118 // for more information.
119 // </note>
120 // </synopsis>
121 
122 // <example>
123 // See the various test programs.
124 // </example>
125 //
126 // <motivation>
127 // HDF5 offers a C++ interface. However, this interface is still quite complex
128 // and is too much C-oriented.
129 // Furthermore there was the need to support the casacore data types,
130 // in particular complex. The reversal of array axes was also needed.
131 // </motivation>
132 
133 // <todo asof="2008/03/13">
134 // <li> Set the optimal data set chunk cache size from a given access pattern.
135 // The current problem is that setting the cache size requires that
136 // the file is closed first.
137 // For the time being a fixed cache size of 16 MB is used instead of
138 // the default 1 MB.
139 // </todo>
140 
141 // </module>
142 
143 
144 } //# NAMESPACE CASACORE - END
145 
146 #endif
this file contains all the compiler specific defines
Definition: mainpage.dox:28