casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
HDF5.h
Go to the documentation of this file.
00001 //# HDF5.h: Classes binding casa to the HDF5 C API
00002 //# Copyright (C) 2008
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: HDF5.h 20739 2009-09-29 01:15:15Z Malte.Marquarding $
00027 
00028 #ifndef CASA_HDF5_H
00029 #define CASA_HDF5_H
00030 
00031 //# Includes
00032 #include <casa/HDF5/HDF5File.h>
00033 #include <casa/HDF5/HDF5Group.h>
00034 #include <casa/HDF5/HDF5DataSet.h>
00035 #include <casa/HDF5/HDF5Record.h>
00036 #include <casa/HDF5/HDF5Error.h>
00037 
00038 
00039 namespace casa { //# NAMESPACE CASA - BEGIN
00040 
00041 // <module>
00042 //
00043 // <summary>
00044 // Classes binding casa to the HDF5 C API
00045 // </summary>
00046 
00047 // <prerequisite>
00048 //   <li> HDF5 (see http://www.hdfgroup.uiuc.edu/HDF5/doc_dev_snapshot)
00049 // </prerequisite>
00050 
00051 // <reviewed reviewer="" date="" demos="">
00052 // </reviewed>
00053 
00054 // <etymology>
00055 // 'HDF5' is version 5 of the Hierarchical Data Format.
00056 // </etymology>
00057 //
00058 // <synopsis>
00059 // This module's main purpose is to provide limited, but convenient
00060 // access to the HDF5 C API.
00061 // The classes offer the following services:
00062 // <ul>
00063 //  <li> The burden of allocating and releasing the HDF5 resources
00064 //       (the so-called hid-s) is handled in an automatic and
00065 //       exception-safe way.
00066 //  <li> The overwhelming and rather hard to use HDF5 C API is hidden.
00067 //  <li> The standard casa data types (scalars and arrays) are fully supported.
00068 //       Because HDF5 does not support empty strings, they are transparantly
00069 //       replaced by the value '__empty__'.
00070 //       Unfortunately HDF5 does not support empty arrays, thus they cannot
00071 //       be stored.
00072 //  <li> A Record is stored as a group. Its values (scalars and arrays)
00073 //       are stored as attributes, while nested records are stored as
00074 //       nested groups.
00075 //  <li> Bool values are stored as chars.
00076 //  <li> Complex values are stored as compounds of two real values.
00077 //  <li> Large arrays can be stored in HDF5 DataSets with an optional tile size
00078 //       (chunk size in HDF5 terminology). The array axes are reversed (fully
00079 //       transparantly) because HDF5 uses C-order, while casa Arrays use
00080 //       Fortran-order.
00081 //  <li> Automatic printing of HDF5 messages is disabled. All errors are
00082 //       thrown as exceptions (AipsError or derived from it).
00083 // </ul>
00084 //
00085 // The following classes are available:
00086 // <ul>
00087 //  <li> HDF5File opens or creates an HDF5 file and closes it automatically.
00088 //       Furthermore it has a function to test if a file is in HDF5 format.
00089 //  <li> HDF5Record reads or writes a Record as a group in an HDF5 object.
00090 //  <li> HDF5DataSet opens or creates a possible tiled data set in an HDF5
00091 //       object. The array can be read or written in parts.
00092 //       Currently the only data types supported are Bool, Int, Float, Double,
00093 //       Complex, and DComplex.
00094 //  <li> HDF5Group opens, creates, or removes a group in an HDF5 object.
00095 // </ul>
00096 // Note that HDF5Object forms the base class of HDF5File, HDF5Group, and
00097 // HDF5DataSet. Most interfaces use HDF5Object, thus are applicable to
00098 // all these object types.
00099 // <br>An HDF5Object has a conversion operator to <src>hid_t</src>, thus
00100 // can be used directly in any HDF5 function.
00101 //
00102 // Because of HDF5 resource management the objects (e.g. HDF5File) cannot
00103 // be copied. However, they can be used in shared pointers (like casa's
00104 // CountedPtr or boost's shared_ptr).
00105 // <br>
00106 // Internally the classes use HDF5HidMeta.h which does the resource management
00107 // for HDF5 meta data like attributes, property lists, etc..
00108 //
00109 // <note>
00110 // All HDF5 classes and all their functions are compiled, but it depends on
00111 // the setting of HAVE_HDF5 how. If not set, all these functions are merely stubs
00112 // and the class constructors throw an exception when used.
00113 // The function <src>HDF5Object::hasHDF5Support()</src> tells if HDF5 is used.
00114 // See the casacore build instructions at casacore.googlecode.com
00115 // for more information.
00116 // </note>
00117 // </synopsis>
00118 
00119 // <example>
00120 // See the various test programs.
00121 // </example>
00122 //
00123 // <motivation>
00124 // HDF5 offers a C++ interface. However, this interface is still quite complex
00125 // and is too much C-oriented.
00126 // Furthermore there was the need to support the casa data types, in particular
00127 // reversal of array axes was needed.
00128 // </motivation>
00129 
00130 // <todo asof="2008/03/13">
00131 //  <li> Make it possible to store empty arrays (e.g. as a compound of a
00132 //       scalar (defining its type) and a vector (defining its shape).
00133 //  <li> Set the optimal data set chunk cache size from a given access pattern.
00134 //       The current problem is that you can only set the cache size at the
00135 //       HDF5 file level, not at the data set level. Furthermore, setting
00136 //       the cache size requires that the file is closed first.
00137 //       For the time being a fixed cache size of 16 MB is used instead of
00138 //       the default 1 MB.
00139 // </todo>
00140 
00141 // </module>
00142 
00143 
00144 } //# NAMESPACE CASA - END
00145 
00146 #endif