Loading...
Searching...
No Matches
HDF5.h
Go to the documentation of this file.
//# HDF5.h: Classes binding casacore to the HDF5 C API
//# Copyright (C) 2008
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef CASA_HDF5_H
#define CASA_HDF5_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/HDF5/HDF5File.h>
#include <casacore/casa/HDF5/HDF5Group.h>
#include <casacore/casa/HDF5/HDF5DataSet.h>
#include <casacore/casa/HDF5/HDF5Record.h>
#include <casacore/casa/HDF5/HDF5Error.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
// <module>
//
// <summary>
// Classes binding casacore to the HDF5 C API
// </summary>
// <prerequisite>
// <li> HDF5 (see http://www.hdfgroup.uiuc.edu/HDF5/doc_dev_snapshot)
// </prerequisite>
// <reviewed reviewer="" date="" demos="">
// </reviewed>
// <etymology>
// 'HDF5' is version 5 of the Hierarchical Data Format.
// </etymology>
//
// <synopsis>
// This module's main purpose is to provide limited, but convenient
// access to the HDF5 C API.
// The classes offer the following services:
// <ul>
// <li> The burden of allocating and releasing the HDF5 resources
// (the so-called hid-s) is handled in an automatic and
// exception-safe way.
// <li> The overwhelming and rather hard to use HDF5 C API is hidden.
// <li> The standard casacore data types (scalars and arrays) are supported.
// Because HDF5 does not support empty strings, they are transparantly
// replaced by the value '__empty__'.
// Also HDF5 does not support empty arrays, thus they are stored
// in a special way using a special compound value.
// <li> A Record is stored as a group. Its values (scalars and arrays)
// are stored as attributes, while nested records are stored as
// nested groups.
// <li> Bool values are stored as chars.
// <li> Complex values are stored as compounds of two real values.
// <li> Large arrays can be stored in HDF5 DataSets with an optional tile size
// (chunk size in HDF5 terminology). The array axes are reversed (fully
// transparantly) because HDF5 uses C-order, while casacore Arrays use
// Fortran-order.
// <li> Automatic printing of HDF5 messages is disabled. All errors are
// thrown as exceptions (AipsError or derived from it).
// </ul>
//
// The following interface classes are available:
// <ul>
// <li> HDF5File opens or creates an HDF5 file and closes it automatically.
// Furthermore it has a function to test if a file is in HDF5 format.
// <li> HDF5DataType defines the HDF5 memory and file data type. It supports
// the basic data types, complex, string, arrays and compounds.
// <li> HDF5Record reads or writes a Record as a group in an HDF5 object.
// <li> HDF5DataSet opens or creates a possible tiled data set in an HDF5
// object. The array can be read or written in parts.
// It can be created of any HDF5DataType.
// <li> HDF5Group opens, creates, or removes a group in an HDF5 object.
// </ul>
// Note that HDF5Object forms the base class of HDF5File, HDF5Group, and
// HDF5DataSet. Most interfaces use HDF5Object, thus are applicable to
// all these object types.
// <br>An HDF5Object has a conversion operator to <src>hid_t</src>, thus
// can be used directly in any HDF5 function.
//
// Because of HDF5 resource management the objects (e.g. HDF5File) cannot be
// copied. However, they can be used in shared pointers such as std::shared_ptr.
// <br>
// Internally the classes use HDF5HidMeta.h which does the resource management
// for HDF5 meta data like attributes, property lists, etc..
//
// <note>
// All HDF5 classes and all their functions are compiled, but it depends on
// the setting of HAVE_HDF5 how. If not set, all these functions are merely
// stubs and the class constructors throw an exception when used.
// The function <src>HDF5Object::hasHDF5Support()</src> tells if HDF5 is used.
// See the casacore build instructions at github.com/casacore/casacore
// for more information.
// </note>
// </synopsis>
// <example>
// See the various test programs.
// </example>
//
// <motivation>
// HDF5 offers a C++ interface. However, this interface is still quite complex
// and is too much C-oriented.
// Furthermore there was the need to support the casacore data types,
// in particular complex. The reversal of array axes was also needed.
// </motivation>
// <todo asof="2008/03/13">
// <li> Set the optimal data set chunk cache size from a given access pattern.
// The current problem is that setting the cache size requires that
// the file is closed first.
// For the time being a fixed cache size of 16 MB is used instead of
// the default 1 MB.
// </todo>
// </module>
} //# NAMESPACE CASACORE - END
#endif
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28