casacore
casa
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
casacore
this file contains all the compiler specific defines
Definition:
mainpage.dox:28
Generated by
1.8.17