File I/O with HDF5
==================

:ref:`O2scl <o2scl>`

The class :ref:`hdf_file <hdf_file>` facilitates I/O of data to hdf
files. This class implements a simple way to read and write basic data
types and O₂scl data types. All files created by the
:cpp:class:`o2scl_hdf::hdf_file` class are normal HDF5 files, and can
be manipulated in the usual way, for example with ``h5dump``
command-line tool. Users can easily mix code which performs I/O with
:cpp:class:`o2scl_hdf::hdf_file` and other O₂scl functions
with their own HDF code. The caveat is that O₂scl
cannot parse generic HDF5 files, so that HDF files which contain data
not output through O₂scl cannot always be read by O₂scl.

HDF5 files which are written by O₂scl can be viewed and
manipulated on the command line using the ``acol`` utility. See
:ref:`The acol Command Line Utility` for more information.

Objects are stored by referring to their dataset name. I/O for basic
objects is provided directly in the :ref:`hdf_file <hdf_file>` class.
Some classes also provide their own I/O functions named ``hdf_output``
and ``hdf_input`` based on the :ref:`hdf_file <hdf_file>` class. Some
of the current classes which provide I/O are :ref:`table <table>`,
:ref:`table_units <table_units>`, :ref:`table3d <table3d>`,
:ref:`tensor_grid <tensor_grid>`, :ref:`hist <hist>`, and
:ref:`hist_2d <hist_2d>`.
    
O₂scl formats complicated data types for HDF I/O by
combining basic data into groups. For that reason, one cannot use
O₂scl to read or write HDF files where groups have the same
name as a dataset in the current HDF id. All O₂scl groups
in HDF files come with a fixed-length string named
``o2scl_type``, which refers to the type of object which has been
written to the HDF file as a group.

.. note:: Vector I/O from HDF5 files can be performed directly only if
	  the vector object provides a pointer to a contiguous chunk
	  of memory. This works for ``std::vector`` objects, because
	  the C++ standard guarantees this. It is not necessarily
	  possible for uBlas vector objects (nor desirable for vectors
	  built upon slices of matrices or tensors), and thus HDF5 I/O
	  with uBlas vectors or matrices requires an extra copy.

.. note:: There are some current limitations regarding the matching of
	  error handling policies between O₂scl and the HDF
	  library. HDF functions do not always call the O₂scl error
          handler and thus do not always throw O₂scl exceptions.
    
.. todo:: (Future) Create an HDF file I/O example

