summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorAllen Byrne <50328838+byrnHDF@users.noreply.github.com>2022-06-29 22:24:22 (GMT)
committerGitHub <noreply@github.com>2022-06-29 22:24:22 (GMT)
commit4fa879ab4140df94e0edccc258b3d4025dc8616a (patch)
tree32d491d313853b91f4e63565939f9f4e5872139e /src
parent0311d4c00a14ad2268c3b2aaa4a248c423afdbc8 (diff)
downloadhdf5-4fa879ab4140df94e0edccc258b3d4025dc8616a.zip
hdf5-4fa879ab4140df94e0edccc258b3d4025dc8616a.tar.gz
hdf5-4fa879ab4140df94e0edccc258b3d4025dc8616a.tar.bz2
Port of datatypes UG. (#1829)
* Port of datatypes UG. * Formatting fix
Diffstat (limited to 'src')
-rw-r--r--src/H5Dmodule.h3
-rw-r--r--src/H5Fmodule.h3
-rw-r--r--src/H5Gmodule.h3
-rw-r--r--src/H5Imodule.h3
-rw-r--r--src/H5Lmodule.h3
-rw-r--r--src/H5Omodule.h3
-rw-r--r--src/H5PLmodule.h3
-rw-r--r--src/H5Rmodule.h20
-rw-r--r--src/H5Smodule.h6
-rw-r--r--src/H5Tmodule.h3799
-rw-r--r--src/H5Tpublic.h23
-rw-r--r--src/H5Zmodule.h3
-rw-r--r--src/H5module.h3
13 files changed, 3819 insertions, 56 deletions
diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h
index d23d34a..d04310e 100644
--- a/src/H5Dmodule.h
+++ b/src/H5Dmodule.h
@@ -57,7 +57,8 @@
* \subsubsection subsubsec_dataset_filters_szip Szip Filter
*/
-/**\defgroup H5D H5D Datasets
+/**
+ * \defgroup H5D H5D Datasets
*
* Use the functions in this module to manage HDF5 datasets, including the
* transfer of data between memory and disk and the description of dataset
diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h
index 9d06265..ae2f6a1 100644
--- a/src/H5Fmodule.h
+++ b/src/H5Fmodule.h
@@ -68,7 +68,8 @@
*
*/
-/**\defgroup H5F H5F File
+/**
+ * \defgroup H5F H5F File
*
* Use the functions in this module to manage HDF5 files.
*
diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h
index d1aaa28..dcfb6d7 100644
--- a/src/H5Gmodule.h
+++ b/src/H5Gmodule.h
@@ -53,7 +53,8 @@
*
*/
-/** \defgroup H5G H5G Groups
+/**
+ * \defgroup H5G H5G Groups
*
* Use the functions in this module to manage HDF5 groups.
*
diff --git a/src/H5Imodule.h b/src/H5Imodule.h
index 1c5a230..c4bdf7b 100644
--- a/src/H5Imodule.h
+++ b/src/H5Imodule.h
@@ -29,7 +29,8 @@
#define H5_MY_PKG_ERR H5E_ATOM
#define H5_MY_PKG_INIT NO
-/**\defgroup H5I H5I Identifiers
+/**
+ * \defgroup H5I H5I Identifiers
*
* Use the functions in this module to manage identifiers defined by the HDF5
* library. See \ref H5IUD for user-defined identifiers and identifier
diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h
index 54aeae2..cd102f7 100644
--- a/src/H5Lmodule.h
+++ b/src/H5Lmodule.h
@@ -29,7 +29,8 @@
#define H5_MY_PKG_ERR H5E_LINK
#define H5_MY_PKG_INIT YES
-/**\defgroup H5L H5L Links
+/**
+ * \defgroup H5L H5L Links
*
* Use the functions in this module to manage HDF5 links and link types.
*
diff --git a/src/H5Omodule.h b/src/H5Omodule.h
index fe127d6..7a023b9 100644
--- a/src/H5Omodule.h
+++ b/src/H5Omodule.h
@@ -29,7 +29,8 @@
#define H5_MY_PKG_ERR H5E_OHDR
#define H5_MY_PKG_INIT YES
-/**\defgroup H5O H5O Objects
+/**
+ * \defgroup H5O H5O Objects
*
* Use the functions in this module to manage HDF5 objects.
*
diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h
index 9c076fe..24fb93c 100644
--- a/src/H5PLmodule.h
+++ b/src/H5PLmodule.h
@@ -27,7 +27,8 @@
#define H5_MY_PKG_ERR H5E_PLUGIN
#define H5_MY_PKG_INIT YES
-/**\defgroup H5PL H5PL Plugins
+/**
+ * \defgroup H5PL H5PL Plugins
*
* Use the functions in this module to manage the loading behavior of HDF5
* plugins.
diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h
index d444ba9..68deefe 100644
--- a/src/H5Rmodule.h
+++ b/src/H5Rmodule.h
@@ -32,26 +32,6 @@
* be HDF5 objects, attributes, and selections on datasets a.k.a. dataset
* regions.
*
- * <table>
- * <tr><th>Create</th><th>Read</th></tr>
- * <tr valign="top">
- * <td>
- * \snippet{lineno} H5R_examples.c create
- * </td>
- * <td>
- * \snippet{lineno} H5R_examples.c read
- * </td>
- * <tr><th>Update</th><th>Delete</th></tr>
- * <tr valign="top">
- * <td>
- * \snippet{lineno} H5R_examples.c update
- * </td>
- * <td>
- * \snippet{lineno} H5R_examples.c delete
- * </td>
- * </tr>
- * </table>
- *
*/
#endif /* H5Rmodule_H */
diff --git a/src/H5Smodule.h b/src/H5Smodule.h
index 9ccce1b..877af64 100644
--- a/src/H5Smodule.h
+++ b/src/H5Smodule.h
@@ -57,7 +57,7 @@
* sub‐sampling, and scatter‐gather access to datasets.
*
* \subsection subsec_dataspace_function Dataspace Function Summaries
- * The @see H5S reference manual provides a reference list of dataspace functions, the H5S APIs.
+ * @see H5S reference manual provides a reference list of dataspace functions, the H5S APIs.
*
* \subsection subsec_dataspace_program Definition of Dataspace Objects and the Dataspace Programming Model
*
@@ -597,7 +597,6 @@
*
* \subsubsection subsubsec_dataspace_transfer_model Programming Model
*
- *
* <h4>Selecting Hyperslabs</h4>
*
* Suppose we want to read a 3x4 hyperslab from a dataset in a file beginning at the element <1,2> in the
@@ -1516,7 +1515,8 @@
*
*/
-/**\defgroup H5S H5S Dataspaces
+/**
+ * \defgroup H5S H5S Dataspaces
*
* Use the functions in this module to manage HDF5 dataspaces \Emph{and} selections.
*
diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h
index a636dc5..5820393 100644
--- a/src/H5Tmodule.h
+++ b/src/H5Tmodule.h
@@ -32,37 +32,3834 @@
/** \page H5T_UG HDF5 Datatypes
*
* \section sec_datatype HDF5 Datatypes
+ * HDF5 datatypes describe the element type of HDF5 datasets and attributes.
+ * There's a large set of predefined datatypes, but users may find it useful
+ * to define new datatypes through a process called \Emph{derivation}.
+ *
+ * The element type is automatically persisted as part of the HDF5 metadata of
+ * attributes and datasets. Additionally, datatype definitions can be persisted
+ * to HDF5 files and linked to groups as HDF5 datatype objects or so-called
+ * \Emph{committed datatypes}.
+ *
* \subsection subsec_datatype_intro Introduction and Definitions
+ *
+ * An HDF5 dataset is an array of data elements, arranged according to the specifications
+ * of the dataspace. In general, a data element is the smallest addressable unit of storage
+ * in the HDF5 file. (Compound datatypes are the exception to this rule.) The HDF5 datatype
+ * defines the storage format for a single data element. See the figure below.
+ *
+ * The model for HDF5 attributes is extremely similar to datasets: an attribute has a dataspace
+ * and a data type, as shown in the figure below. The information in this chapter applies to both
+ * datasets and attributes.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig1.gif "Datatypes, dataspaces, and datasets"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * Abstractly, each data element within the dataset is a sequence of bits, interpreted as a single
+ * value from a set of values (for example, a number or a character). For a given datatype, there is a
+ * standard or convention for representing the values as bits, and when the bits are represented in a
+ * particular storage the bits are laid out in a specific storage scheme such as 8-bit bytes with a
+ * specific ordering and alignment of bytes within the storage array.
+ *
+ * HDF5 datatypes implement a flexible, extensible, and portable mechanism for specifying and
+ * discovering the storage layout of the data elements, determining how to interpret the elements
+ * (for example, as floating point numbers), and for transferring data from different compatible
+ * layouts.
+ *
+ * An HDF5 datatype describes one specific layout of bits. A dataset has a single datatype which
+ * applies to every data element. When a dataset is created, the storage datatype is defined. After
+ * the dataset or attribute is created, the datatype cannot be changed.
+ * \li The datatype describes the storage layout of a singledata element
+ * \li All elements of the dataset must have the same type
+ * \li The datatype of a dataset is immutable
+ *
+ * When data is transferred (for example, a read or write), each end point of the transfer has a
+ * datatype, which describes the correct storage for the elements. The source and destination may
+ * have different (but compatible) layouts, in which case the data elements are automatically
+ * transformed during the transfer.
+ *
+ * HDF5 datatypes describe commonly used binary formats for numbers (integers
+ * and floating point) and characters (ASCII). A given computing architecture and programming language
+ * supports certain number and character representations. For example, a computer may support 8-,
+ * 16-, 32-, and 64-bit signed integers, stored in memory in little-endian byte order. These would
+ * presumably correspond to the C programming language types \Emph{char}, \Emph{short},
+ * \Emph{int}, and \Emph{long}.
+ *
+ * When reading and writing from memory, the HDF5 library must know the appropriate datatype
+ * that describes the architecture specific layout. The HDF5 library provides the platform
+ * independent \Emph{NATIVE} types, which are mapped to an appropriate datatype for each platform.
+ * So the type #H5T_NATIVE_INT is an alias for the appropriate descriptor for each platform.
+ *
+ * Data in memory has a datatype:
+ * \li The storage layout in memory is architecture-specific
+ * \li The HDF5 \Emph{NATIVE} types are predefined aliases for the architecture-specific memory layout
+ * \li The memory datatype need not be the same as the stored datatype of the dataset
+ *
+ * In addition to numbers and characters, an HDF5 datatype can describe more abstract classes of
+ * types including enumerations, strings, bit strings, and references (pointers to objects in the HDF5
+ * file). HDF5 supports several classes of composite datatypes which are combinations of one or
+ * more other datatypes. In addition to the standard predefined datatypes, users can define new
+ * datatypes within the datatype classes.
+ *
+ * The HDF5 datatype model is very general and flexible:
+ * \li For common simple purposes, only predefined types will be needed
+ * \li Datatypes can be combined to create complex structured datatypes
+ * \li If needed, users can define custom atomic datatypes
+ * \li Committed datatypes can be shared by datasets or attributes
+ *
* \subsection subsec_datatype_model Datatype Model
+ * The HDF5 library implements an object-oriented model of datatypes. HDF5 datatypes are
+ * organized as a logical set of base types, or datatype classes. Each datatype class defines
+ * a format for representing logical values as a sequence of bits. For example the #H5T_INTEGER
+ * class is a format for representing twos complement integers of various sizes.
+ *
+ * A datatype class is defined as a set of one or more datatype properties. A datatype property is
+ * a property of the bit string. The datatype properties are defined by the logical model of the
+ * datatype class. For example, the integer class (twos complement integers) has properties such as
+ * “signed or unsigned”, “length”, and “byte-order”. The float class (IEEE floating point numbers)
+ * has these properties, plus “exponent bits”, “exponent sign”, etc.
+ *
+ * A datatype is derived from one datatype class: a given datatype has a specific value for the
+ * datatype properties defined by the class. For example, for 32-bit signed integers, stored
+ * big-endian, the HDF5 datatype is a sub-type of integer with the properties set to
+ * signed=1, size=4(bytes), and byte-order=BE.
+ *
+ * The HDF5 datatype API (H5T functions) provides methods to create datatypes of different
+ * datatype classes, to set the datatype properties of a new datatype, and to discover the datatype
+ * properties of an existing datatype.
+ *
+ * The datatype for a dataset is stored in the HDF5 file as part of the metadata for the dataset.
+ * A datatype can be shared by more than one dataset in the file if the datatype is saved to the
+ * file with a name. This shareable datatype is known as a committed datatype. In the past,
+ * this kind of datatype was called a named datatype.
+ *
+ * When transferring data (for example, a read or write), the data elements of the source and
+ * destination storage must have compatible types. As a general rule, data elements with the same
+ * datatype class are compatible while elements from different datatype classes are not compatible.
+ * When transferring data of one datatype to another compatible datatype, the HDF5 Library uses
+ * the datatype properties of the source and destination to automatically transform each data
+ * element. For example, when reading from data stored as 32-bit signed integers, big
+ * endian into 32-bit signed integers, little-endian, the HDF5 Library will automatically swap the
+ * bytes.
+ *
+ * Thus, data transfer operations (\ref H5Dread, \ref H5Dwrite, \ref H5Aread, \ref H5Awrite) require
+ * a datatype for both the source and the destination.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig2.gif "The datatype model"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * The HDF5 library defines a set of predefined datatypes, corresponding to commonly used
+ * storage formats, such as twos complement integers, IEEE Floating point numbers, etc., 4-
+ * and 8-byte sizes, big-endian and little-endian byte orders. In addition, a user can derive types with
+ * custom values for the properties. For example, a user program may create a datatype to describe
+ * a 6-bit integer, or a 600-bit floating point number.
+ *
+ * In addition to atomic datatypes, the HDF5 library supports composite datatypes. A composite
+ * datatype is an aggregation of one or more datatypes. Each class of composite datatypes has
+ * properties that describe the organization of the composite datatype. See the figure below.
+ * Composite datatypes include:
+ * \li Compound datatypes: structured records
+ * \li Array: a multidimensional array of a datatype
+ * \li Variable-length: a one-dimensional array of a datatype
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig3.gif "Composite datatypes"
+ * </td>
+ * </tr>
+ * </table>
+ *
* \subsubsection subsubsec_datatype_model_class Datatype Classes and Properties
+ * The figure below shows the HDF5 datatype classes. Each class is defined to have a set of
+ * properties which describe the layout of the data element and the interpretation of the bits. The
+ * table below lists the properties for the datatype classes.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig4.gif "Datatype classes"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Datatype classes and their properties</caption>
+ * <tr>
+ * <th>
+ * Class
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * <th>
+ * Properties
+ * </th>
+ * <th>
+ * Notes
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * Integer
+ * </td>
+ * <td>
+ * Twos complement integers
+ * </td>
+ * <td>
+ * Size (bytes), precision (bits), offset (bits), pad, byte order, signed/unsigned
+ * </td>
+ * <td>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Float
+ * </td>
+ * <td>
+ * Floating Point numbers
+ * </td>
+ * <td>
+ * Size (bytes), precision (bits), offset (bits), pad, byte order, sign position,
+ * exponent position, exponent size (bits), exponent sign, exponent bias, mantissa position,
+ * mantissa (size) bits, mantissa sign, mantissa normalization, internal padding
+ * </td>
+ * <td>
+ * See IEEE 754 for a definition of these properties. These properties describe
+ * non-IEEE 754 floating point formats as well.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Character
+ * </td>
+ * <td>
+ * Array of 1-byte character encoding
+ * </td>
+ * <td>
+ * Size (characters), Character set, byte order, pad/no pad, pad character
+ * </td>
+ * <td>
+ * Currently, ASCII and UTF-8 are supported.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Bitfield
+ * </td>
+ * <td>
+ * String of bits
+ * </td>
+ * <td>
+ * Size (bytes), precision (bits), offset (bits), pad, byte order
+ * </td>
+ * <td>
+ * A sequence of bit values packed into one or more bytes.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Opaque
+ * </td>
+ * <td>
+ * Uninterpreted data
+ * </td>
+ * <td>
+ * Size (bytes), precision (bits), offset (bits), pad, byte order, tag
+ * </td>
+ * <td>
+ * A sequence of bytes, stored and retrieved as a block.
+ * The ‘tag’ is a string that can be used to label the value.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Enumeration
+ * </td>
+ * <td>
+ * A list of discrete values, with symbolic names in the form of strings.
+ * </td>
+ * <td>
+ * Number of elements, element names, element values
+ * </td>
+ * <td>
+ * Enumeration is a list of pairs (name, value). The name is a string; the
+ * value is an unsigned integer.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Reference
+ * </td>
+ * <td>
+ * Reference to object or region within the HDF5 file
+ * </td>
+ * <td>
+ *
+ * </td>
+ * <td>
+ * @see H5R
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Array
+ * </td>
+ * <td>
+ * Array (1-4 dimensions) of data elements
+ * </td>
+ * <td>
+ * Number of dimensions, dimension sizes, base datatype
+ * </td>
+ * <td>
+ * The array is accessed atomically: no selection or sub-setting.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Variable-length
+ * </td>
+ * <td>
+ * A variable-length 1-dimensional array of data elements
+ * </td>
+ * <td>
+ * Current size, base type
+ * </td>
+ * <td>
+ *
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Compound
+ * </td>
+ * <td>
+ * A Datatype of a sequence of Datatypes
+ * </td>
+ * <td>
+ * Number of members, member names, member types, member offset, member class,
+ * member size, byte order
+ * </td>
+ * <td>
+ *
+ * </td>
+ * </tr>
+ * </table>
+ *
* \subsubsection subsubsec_datatype_model_predefine Predefined Datatypes
+ * The HDF5 library predefines a modest number of commonly used datatypes. These types have
+ * standard symbolic names of the form H5T_arch_base where arch is an architecture name and
+ * base is a programming type name <b>Table 2</b>. New types can be derived from the predefined
+ * types by copying the predefined type \ref H5Tcopy() and then modifying the result.
+ *
+ * The base name of most types consists of a letter to indicate the class <b>Table 3</b>, a precision in
+ * bits, and an indication of the byte order <b>Table 4</b>.
+ *
+ * <b>Table 5</b> shows examples of predefined datatypes. The full list can be found in the
+ * \ref PDT section of the HDF5 Reference Manual.
+ *
+ * <table>
+ * <caption align=top>Table 2. Architectures used in predefined datatypes</caption>
+ * <tr>
+ * <th>
+ * Architecture Name
+ * </th>
+ * <th span='3'>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * IEEE
+ * </td>
+ * <td span='3'>
+ * IEEE-754 standard floating point types in various byte orders.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * STD
+ * </td>
+ * <td span='3'>
+ * This is an architecture that contains semi-standard datatypes like signed
+ * two’s complement integers, unsigned integers, and bitfields in various
+ * byte orders.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * C <br \> FORTRAN
+ * </td>
+ * <td span='3'>
+ * Types which are specific to the C or Fortran programming languages
+ * are defined in these architectures. For instance, #H5T_C_S1 defines a
+ * base string type with null termination which can be used to derive string
+ * types of other lengths.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * NATIVE
+ * </td>
+ * <td span='3'>
+ * This architecture contains C-like datatypes for the machine on which
+ * the library was compiled. The types were actually defined by running
+ * the H5detect program when the library was compiled. In order to be
+ * portable, applications should almost always use this architecture
+ * to describe things in memory.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * CRAY
+ * </td>
+ * <td span='3'>
+ * Cray architectures. These are word-addressable, big-endian systems
+ * with non-IEEE floating point.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * INTEL
+ * </td>
+ * <td span='3'>
+ * All Intel and compatible CPU’s.
+ * These are little-endian systems with IEEE floating-point.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * MIPS
+ * </td>
+ * <td span='3'>
+ * All MIPS CPU’s commonly used in SGI systems. These are big-endian
+ * systems with IEEE floating-point.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * ALPHA
+ * </td>
+ * <td span='3'>
+ * All DEC Alpha CPU’s, little-endian systems with IEEE floating-point.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 3. Base types</caption>
+ * <tr>
+ * <th>
+ * Base
+ * </th>
+ * <th span='3'>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * B
+ * </td>
+ * <td span='3'>
+ * Bitfield
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * F
+ * </td>
+ * <td span='3'>
+ * Floating point
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * I
+ * </td>
+ * <td span='3'>
+ * Signed integer
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * R
+ * </td>
+ * <td span='3'>
+ * References
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * S
+ * </td>
+ * <td span='3'>
+ * Character string
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * U
+ * </td>
+ * <td span='3'>
+ * Unsigned integer
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 4. Byte order</caption>
+ * <tr>
+ * <th>
+ * Order
+ * </th>
+ * <th span='3'>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * BE
+ * </td>
+ * <td span='3'>
+ * Big-endian
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * LE
+ * </td>
+ * <td span='3'>
+ * Little-endian
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 5. Some predefined datatypes</caption>
+ * <tr>
+ * <th>
+ * Example
+ * </th>
+ * <th span='3'>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_IEEE_F64LE
+ * </td>
+ * <td span='3'>
+ * Eight-byte, little-endian, IEEE floating-point
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_IEEE_F32BE
+ * </td>
+ * <td span='3'>
+ * Four-byte, big-endian, IEEE floating point
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_STD_I32LE
+ * </td>
+ * <td span='3'>
+ * Four-byte, little-endian, signed two’s complement integer
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_STD_U16BE
+ * </td>
+ * <td span='3'>
+ * Two-byte, big-endian, unsigned integer
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_C_S1
+ * </td>
+ * <td span='3'>
+ * One-byte,null-terminated string of eight-bit characters
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_INTEL_B64
+ * </td>
+ * <td span='3'>
+ * Eight-byte bit field on an Intel CPU
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_STD_REF_OBJ
+ * </td>
+ * <td span='3'>
+ * Reference to an entire object in a file
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * The HDF5 library predefines a set of \Emph{NATIVE} datatypes which are similar to C type names.
+ * The native types are set to be an alias for the appropriate HDF5 datatype for each platform. For
+ * example, #H5T_NATIVE_INT corresponds to a C int type. On an Intel based PC, this type is the same as
+ * #H5T_STD_I32LE, while on a MIPS system this would be equivalent to #H5T_STD_I32BE. Table 6 shows
+ * examples of \Emph{NATIVE} types and corresponding C types for a common 32-bit workstation.
+ *
+ * <table>
+ * <caption align=top>Table 6. Native and 32-bit C datatypes</caption>
+ * <tr>
+ * <th>
+ * Example
+ * </th>
+ * <th span='3'>
+ * Corresponding C Type
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_CHAR
+ * </td>
+ * <td span='3'>
+ * char
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_SCHAR
+ * </td>
+ * <td span='3'>
+ * signed char
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_UCHAR
+ * </td>
+ * <td span='3'>
+ * unsigned char
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_SHORT
+ * </td>
+ * <td span='3'>
+ * short
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_USHORT
+ * </td>
+ * <td span='3'>
+ * unsigned short
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_INT
+ * </td>
+ * <td span='3'>
+ * int
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_UINT
+ * </td>
+ * <td span='3'>
+ * unsigned
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_LONG
+ * </td>
+ * <td span='3'>
+ * long
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_ULONG
+ * </td>
+ * <td span='3'>
+ * unsigned long
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_LLONG
+ * </td>
+ * <td span='3'>
+ * long long
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_ULLONG
+ * </td>
+ * <td span='3'>
+ * unsigned long long
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_FLOAT
+ * </td>
+ * <td span='3'>
+ * float
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_DOUBLE
+ * </td>
+ * <td span='3'>
+ * double
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_LDOUBLE
+ * </td>
+ * <td span='3'>
+ * long double
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_HSIZE
+ * </td>
+ * <td span='3'>
+ * hsize_t
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_HSSIZE
+ * </td>
+ * <td span='3'>
+ * hssize_t
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_HERR
+ * </td>
+ * <td span='3'>
+ * herr_t
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_HBOOL
+ * </td>
+ * <td span='3'>
+ * hbool_t
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_B8
+ * </td>
+ * <td span='3'>
+ * 8-bit unsigned integer or 8-bit buffer in memory
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_B16
+ * </td>
+ * <td span='3'>
+ * 16-bit unsigned integer or 16-bit buffer in memory
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_B32
+ * </td>
+ * <td span='3'>
+ * 32-bit unsigned integer or 32-bit buffer in memory
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * #H5T_NATIVE_B64
+ * </td>
+ * <td span='3'>
+ * 64-bit unsigned integer or 64-bit buffer in memory
+ * </td>
+ * </tr>
+ * </table>
+ *
* \subsection subsec_datatype_usage How Datatypes are Used
+ *
* \subsubsection subsubsec_datatype_usage_object The Datatype Object and the HDF5 Datatype API
+ * The HDF5 library manages datatypes as objects. The HDF5 datatype API manipulates the
+ * datatype objects through C function calls. New datatypes can be created from scratch or
+ * copied from existing datatypes. When a datatype is no longer needed its resources should be released by
+ * calling \ref H5Tclose().
+ *
+ * The datatype object is used in several roles in the HDF5 data model and library. Essentially, a
+ * datatype is used whenever the form at of data elements is needed. There are four major uses of
+ * datatypes in the HDF5 library: at dataset creation, during data transfers, when discovering the
+ * contents of a file, and for specifying user-defined datatypes. See the table below.
+ *
+ * <table>
+ * <caption align=top>Table 7. Datatype uses</caption>
+ * <tr>
+ * <th>
+ * Use
+ * </th>
+ * <th span='2'>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * Dataset creation
+ * </td>
+ * <td span='2'>
+ * The datatype of the data elements must be declared when the dataset is created.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Dataset transfer
+ * </td>
+ * <td span='2'>
+ * The datatype (format) of the data elements must be defined for both the source and destination.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Discovery
+ * </td>
+ * <td span='2'>
+ * The datatype of a dataset can be interrogated to retrieve a complete description of the storage layout.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Creating user-defined datatypes
+ * </td>
+ * <td span='2'>
+ * Users can define their own datatypes by creating datatype objects and setting their properties.
+ * </td>
+ * </tr>
+ * </table>
+ *
* \subsubsection subsubsec_datatype_usage_create Dataset Creation
+ * All the data elements of a dataset have the same datatype. When a dataset is created, the datatype
+ * for the data elements must be specified. The datatype of a dataset can never be changed. The
+ * example below shows the use of a datatype to create a dataset called “/dset”. In this example, the
+ * dataset will be stored as 32-bit signed integers in big-endian order.
+ *
+ * <em> Using a datatype to create a dataset </em>
+ * \code
+ * hid_t dt;
+ *
+ * dt = H5Tcopy(H5T_STD_I32BE);
+ * dataset_id = H5Dcreate(file_id, “/dset”, dt, dataspace_id, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * \endcode
+ *
* \subsubsection subsubsec_datatype_usage_transfer Data Transfer (Read and Write)
+ * Probably the most common use of datatypes is to write or read data from a dataset or attribute. In
+ * these operations, each data element is transferred from the source to the destination (possibly
+ * rearranging the order of the elements). Since the source and destination do not need to be
+ * identical (in other words, one is disk and the other is memory), the transfer requires
+ * both the format of the source element and the destination element. Therefore, data transfers use two
+ * datatype objects, for the source and destination.
+ *
+ * When data is written, the source is memory and the destination is disk (file). The memory
+ * datatype describes the format of the data element in the machine memory, and the file datatype
+ * describes the desired format of the data element on disk. Similarly, when reading, the source
+ * datatype describes the format of the data element on disk, and the destination datatype describes
+ * the format in memory.
+ *
+ * In the most common cases, the file datatype is the datatype specified when
+ * the dataset was
+ * created, and the memory datatype should be the appropriate \Emph{NATIVE} type.
+ * The examples below show samples of writing data to and reading data from a dataset. The data
+ * in memory is declared C type ‘int’, and the datatype #H5T_NATIVE_INT corresponds to this
+ * type. The datatype of the dataset should be of datatype class #H5T_INTEGER.
+ *
+ * <em> Writing to a dataset </em>
+ * \code
+ * int dset_data[DATA_SIZE];
+ *
+ * status = H5Dwrite(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_data);
+ * \endcode
+ *
+ * <em> Reading from a dataset </em>
+ * \code
+ * int dset_data[DATA_SIZE];
+ *
+ * status = H5Dread(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_data);
+ * \endcode
+ *
* \subsubsection subsubsec_datatype_usage_discover Discovery of Data Format
+ * The HDF5 Library enables a program to
+ * determine the datatype class and properties for any
+ * datatype. In order to discover the storage format of data in a dataset, the datatype is obtained, and
+ * the properties are determined by queries to the datatype object. The example below shows code
+ * that analyzes the datatype for an integer and prints out a description of its storage properties
+ * (byte order, signed, size).
+ *
+ * <em> Discovering datatype properties </em>
+ * \code
+ * switch (H5Tget_class(type)) {
+ * case H5T_INTEGER:
+ * ord = H5Tget_order(type);
+ * sgn = H5Tget_sign(type);
+ * printf(“Integer ByteOrder= ”);
+ * switch (ord) {
+ * case H5T_ORDER_LE:
+ * printf(“LE”);
+ * break;
+ * case H5T_ORDER_BE:
+ * printf(“BE”);
+ * break;
+ * }
+ * printf(“ Sign= ”);
+ * switch (sgn) {
+ * case H5T_SGN_NONE:
+ * printf(“false”);
+ * break;
+ * case H5T_SGN_2:
+ * printf(“true”);
+ * break;
+ * }
+ * printf(“ Size= ”);
+ * sz = H5Tget_size(type);
+ * printf(“%d”, sz);
+ * printf(“\n”);
+ * break;
+ * case H5T_????
+ * ...
+ * break;
+ * }
+ * \endcode
+ *
* \subsubsection subsubsec_datatype_usage_user Creating and Using User‐defined Datatypes
+ * Most programs will primarily use the predefined datatypes described above, possibly in
+ * composite data types such as compound or array datatypes. However, the HDF5 datatype model
+ * is extremely general; a user program can define a great variety of atomic datatypes (storage
+ * layouts). In particular, the datatype properties can define signed and unsigned integers of any
+ * size and byte order, and floating point numbers with different formats, size, and byte order. The
+ * HDF5 datatype API provides methods to set these properties.
+ *
+ * User-defined types can be used to define the layout of data in memory; examples might match
+ * some platform specific number format or application defined bit-field. The user-defined type can
+ * also describe data in the file such as an application-defined format. The user-defined types can be
+ * translated to and from standard types of the same class, as described above.
+ *
* \subsection subsec_datatype_function Datatype Function Summaries
+ * @see H5T reference manual provides a reference list of datatype functions, the H5T APIs.
+ *
* \subsection subsec_datatype_program Programming Model for Datatypes
+ * The HDF5 Library implements an object-oriented model of datatypes. HDF5 datatypes are
+ * organized as a logical set of base types, or datatype classes. The HDF5 Library manages
+ * datatypes as objects. The HDF5 datatype API manipulates the datatype objects through C
+ * function calls. The figure below shows the abstract view of the datatype object. The table below
+ * shows the methods (C functions) that operate on datatype objects. New datatypes can be created
+ * from scratch or copied from existing datatypes.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig5.gif "The datatype object"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 8. General operations on datatype objects</caption>
+ * <tr>
+ * <th>
+ * API Function
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref hid_t \ref H5Tcreate (\ref H5T_class_t class, size_t size)
+ * </td>
+ * <td>
+ * Create a new datatype object of datatype class . The following datatype classes care supported
+ * with this function:
+ * \li #H5T_COMPOUND
+ * \li #H5T_OPAQUE
+ * \li #H5T_ENUM
+ * \li Other datatypes are created with \ref H5Tcopy().
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref hid_t \ref H5Tcopy (\ref hid_t type)
+ * </td>
+ * <td>
+ * Obtain a modifiable transient datatype which is a copy of type. If type is a dataset identifier
+ * then the type returned is a modifiable transient copy of the datatype of the specified dataset.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref hid_t \ref H5Topen (\ref hid_t location, const char *name, #H5P_DEFAULT)
+ * </td>
+ * <td>
+ * Open a committed datatype. The committed datatype returned by this function is read-only.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref htri_t \ref H5Tequal (\ref hid_t type1, \ref hid_t type2)
+ * </td>
+ * <td>
+ * Determines if two types are equal.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tclose (\ref hid_t type)
+ * </td>
+ * <td>
+ * Releases resources associated with a datatype obtained from \ref H5Tcopy, \ref H5Topen, or
+ * \ref H5Tcreate. It is illegal to close an immutable transient datatype (for example, predefined types).
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tcommit (\ref hid_t location, const char *name, hid_t type,
+ * #H5P_DEFAULT, #H5P_DEFAULT, #H5P_DEFAULT)
+ * </td>
+ * <td>
+ * Commit a transient datatype (not immutable) to a file to become a committed datatype. Committed
+ * datatypes can be shared.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref htri_t \ref H5Tcommitted (\ref hid_t type)
+ * </td>
+ * <td>
+ * Test whether the datatype is transient or committed (named).
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tlock (\ref hid_t type)
+ * </td>
+ * <td>
+ * Make a transient datatype immutable (read-only and not closable). Predefined types are locked.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * In order to use a datatype, the object must be created (\ref H5Tcreate), or a reference obtained by
+ * cloning from an existing type (\ref H5Tcopy), or opened (\ref H5Topen). In addition, a reference to the
+ * datatype of a dataset or attribute can be obtained with \ref H5Dget_type or \ref H5Aget_type. For
+ * composite datatypes a reference to the datatype for members or base types can be obtained
+ * (\ref H5Tget_member_type, \ref H5Tget_super). When the datatype object is no longer needed, the
+ * reference is discarded with \ref H5Tclose.
+ *
+ * Two datatype objects can be tested to see if they are the same with \ref H5Tequal. This function
+ * returns true if the two datatype references refer to the same datatype object. However, if two
+ * datatype objects define equivalent datatypes (the same datatype class and datatype properties),
+ * they will not be considered ‘equal’.
+ *
+ * A datatype can be written to the file as a first class object (\ref H5Tcommit). This is a committed
+ * datatype and can be used in thesame way as any other datatype.
+ *
* \subsubsection subsubsec_datatype_program_discover Discovery of Datatype Properties
+ * Any HDF5 datatype object can be queried to discover all of its datatype properties. For each
+ * datatype class, there are a set of API functions to retrieve the datatype properties for this class.
+ *
+ * <h4>Properties of Atomic Datatypes</h4>
+ * Table 9 lists the functions to discover the properties of atomic datatypes. Table 10 lists the
+ * queries relevant to specific numeric types. Table 11 gives the properties for atomic string
+ * datatype, and Table 12 gives the property of the opaque datatype.
+ *
+ * <table>
+ * <caption align=top>Table 9. Functions to discover properties of atomic datatypes</caption>
+ * <tr>
+ * <th>
+ * API Function
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref H5T_class_t \ref H5Tget_class (\ref hid_t type)
+ * </td>
+ * <td>
+ * The datatype class: #H5T_INTEGER, #H5T_FLOAT, #H5T_STRING, #H5T_BITFIELD, #H5T_OPAQUE, #H5T_COMPOUND,
+ * #H5T_REFERENCE, #H5T_ENUM, #H5T_VLEN, #H5T_ARRAY
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * size_t \ref H5Tget_size (\ref hid_t type)
+ * </td>
+ * <td>
+ * The total size of the element in bytes, including padding which may appear on either side of the
+ * actual value.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref H5T_order_t \ref H5Tget_order (\ref hid_t type)
+ * </td>
+ * <td>
+ * The byte order describes how the bytes of the datatype are laid out in memory. If the lowest memory
+ * address contains the least significant byte of the datum then it is said to be little-endian or
+ * #H5T_ORDER_LE. If the bytes are in the opposite order then they are said to be big-endianor #H5T_ORDER_BE.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * size_t \ref H5Tget_precision (\ref hid_t type)
+ * </td>
+ * <td>
+ * The precision property identifies the number of significant bits of a datatype and the offset property
+ * (defined below) identifies its location. Some datatypes occupy more bytes than what is needed to store
+ * the value. For instance, a short on a Cray is 32 significant bits in an eight-byte field.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * int \ref H5Tget_offset (\ref hid_t type)
+ * </td>
+ * <td>
+ * The offset property defines the bit location of the least significant bit of a bit field whose length
+ * is precision.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tget_pad (\ref hid_t type, \ref H5T_pad_t *lsb, \ref H5T_pad_t *msb)
+ * </td>
+ * <td>
+ * Padding is the bits of a data element which are not significant as defined by the precision and offset
+ * properties. Padding in the low-numbered bits is lsb padding and padding in the high-numbered bits is msb
+ * padding. Padding bits can be set to zero (#H5T_PAD_ZERO) or one (#H5T_PAD_ONE).
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 10. Functions to discover properties of atomic datatypes</caption>
+ * <tr>
+ * <th>
+ * API Function
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref H5T_sign_t \ref H5Tget_sign (\ref hid_t type)
+ * </td>
+ * <td>
+ * (INTEGER)Integer data can be signed two’s complement (#H5T_SGN_2) or unsigned (#H5T_SGN_NONE).
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tget_fields (\ref hid_t type, size_t *spos, size_t *epos, size_t *esize,
+ * size_t*mpos, size_t *msize)
+ * </td>
+ * <td>
+ * (FLOAT)A floating-point data element has bit fields which are the exponent and mantissa as well as a
+ * mantissa sign bit. These properties define the location (bit position of least significant bit of the
+ * field) and size (in bits) of each field. The sign bit is always of length one and none of the fields
+ * are allowed to overlap.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * size_t \ref H5Tget_ebias (\ref hid_t type)
+ * </td>
+ * <td>
+ * (FLOAT)A floating-point data element has bit fields which are the exponent and
+ * mantissa as well as a mantissa sign bit. These properties define the location (bit
+ * position of least significant bit of the field) and size (in bits) of
+ * each field. The sign bit is always of length one and none of the
+ * fields are allowed to overlap.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref H5T_norm_t \ref H5Tget_norm (\ref hid_t type)
+ * </td>
+ * <td>
+ * (FLOAT)This property describes the normalization method of the mantissa.
+ * <ul><li>#H5T_NORM_MSBSET: the mantissa is shifted left (if non-zero) until the first bit
+ * after the radix point is set and the exponent is adjusted accordingly. All bits of the
+ * mantissa after the radix point are stored. </li>
+ * <li>#H5T_NORM_IMPLIED: the mantissa is shifted left \(if non-zero) until the first
+ * bit after the radix point is set and the exponent is adjusted accordingly. The first
+ * bit after the radix point is not stored since it’s always set. </li>
+ * <li>#H5T_NORM_NONE: the fractional part of the mantissa is stored without normalizing it.</li></ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref H5T_pad_t \ref H5Tget_inpad (\ref hid_t type)
+ * </td>
+ * <td>
+ * (FLOAT)If any internal bits (that is, bits between the sign bit, the mantissa field,
+ * and the exponent field but within the precision field) are unused, then they will be
+ * filled according to the value of this property. The padding can be:
+ * #H5T_PAD_BACKGROUND, #H5T_PAD_ZERO,or #H5T_PAD_ONE.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 11. Functions to discover properties of atomic string datatypes</caption>
+ * <tr>
+ * <th>
+ * API Function
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref H5T_cset_t \ref H5Tget_cset (\ref hid_t type)
+ * </td>
+ * <td>
+ * Two character sets are currently supported:
+ * ASCII (#H5T_CSET_ASCII) and UTF-8 (#H5T_CSET_UTF8).
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref H5T_str_t \ref H5Tget_strpad (\ref hid_t type)
+ * </td>
+ * <td>
+ * The string datatype has a fixed length, but the string may be shorter than the length.
+ * This property defines the storage mechanism for the left over bytes. The options are:
+ * \li #H5T_STR_NULLTERM
+ * \li #H5T_STR_NULLPAD
+ * \li #H5T_STR_SPACEPAD.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 12. Functions to discover properties of atomic opaque datatypes</caption>
+ * <tr>
+ * <th>
+ * API Function
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * char* \ref H5Tget_tag(\ref hid_t type_id)
+ * </td>
+ * <td>
+ * A user-defined string.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <h4>Properties of Composite Datatypes</h4>
+ * The composite datatype classes can also be analyzed to discover their datatype properties and the
+ * datatypes that are members or base types of the composite datatype. The member or base type
+ * can, in turn, be analyzed. The table below lists the functions that can access the datatype
+ * properties of the different composite datatypes.
+ *
+ * <table>
+ * <caption align=top>Table 13. Functions to discover properties of composite datatypes</caption>
+ * <tr>
+ * <th>
+ * API Function
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * int \ref H5Tget_nmembers(\ref hid_t type_id)
+ * </td>
+ * <td>
+ * (COMPOUND)The number of fields in the compound datatype.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref H5T_class_t \ref H5Tget_member_class (\ref hid_t cdtype_id, unsigned member_no)
+ * </td>
+ * <td>
+ * (COMPOUND)The datatype class of compound datatype member member_no.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * char* \ref H5Tget_member_name (\ref hid_t type_id, unsigned field_idx)
+ * </td>
+ * <td>
+ * (COMPOUND)The name of field field_idx of a compound datatype.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * size_t \ref H5Tget_member_offset (\ref hid_t type_id, unsigned memb_no)
+ * </td>
+ * <td>
+ * (COMPOUND)The byte offset of the beginning of a field within a compound datatype.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref hid_t \ref H5Tget_member_type (\ref hid_t type_id, unsigned field_idx)
+ * </td>
+ * <td>
+ * (COMPOUND)The datatype of the specified member.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * int \ref H5Tget_array_ndims (\ref hid_t adtype_id)
+ * </td>
+ * <td>
+ * (ARRAY)The number of dimensions (rank) of the array datatype object.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * int \ref H5Tget_array_dims (\ref hid_t adtype_id, hsize_t *dims[])
+ * </td>
+ * <td>
+ * (ARRAY)The sizes of the dimensions and the dimension permutations of the array datatype object.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref hid_t \ref H5Tget_super(\ref hid_t type)
+ * </td>
+ * <td>
+ * (ARRAY, VL, ENUM)The base datatype from which the datatype type is derived.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tenum_nameof(\ref hid_t type, const void *value, char *name, size_t size)
+ * </td>
+ * <td>
+ * (ENUM)The symbol name that corresponds to the specified value of the enumeration datatype.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tenum_valueof(\ref hid_t type, const char *name, void *value)
+ * </td>
+ * <td>
+ * (ENUM)The value that corresponds to the specified name of the enumeration datatype.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tget_member_value (\ref hid_t type unsigned memb_no, void *value)
+ * </td>
+ * <td>
+ * (ENUM)The value of the enumeration datatype member memb_no.
+ * </td>
+ * </tr>
+ * </table>
+ *
* \subsubsection subsubsec_datatype_program_define Definition of Datatypes
+ * The HDF5 library enables user programs to create and modify datatypes. The essential steps are:
+ * <ul><li>1. Create a new datatype object of a specific composite datatype class, or copy an existing
+ * atomic datatype object</li>
+ * <li>2. Set properties of the datatype object</li>
+ * <li>3. Use the datatype object</li>
+ * <li>4. Close the datatype object</li></ul>
+ *
+ * To create a user-defined atomic datatype, the procedure is to clone a predefined datatype of the
+ * appropriate datatype class (\ref H5Tcopy), and then set the datatype properties appropriate to the
+ * datatype class. The table below shows how to create a datatype to describe a 1024-bit unsigned
+ * integer.
+ *
+ * <em>Create a new datatype</em>
+ * \code
+ * hid_t new_type = H5Tcopy (H5T_NATIVE_INT);
+ *
+ * H5Tset_precision(new_type, 1024);
+ * H5Tset_sign(new_type, H5T_SGN_NONE);
+ * \endcode
+ *
+ * Composite datatypes are created with a specific API call for each datatype class. The table below
+ * shows the creation method for each datatype class. A newly created datatype cannot be used until the
+ * datatype properties are set. For example, a newly created compound datatype has no members and cannot
+ * be used.
+ *
+ * <table>
+ * <caption align=top>Table 14. Functions to create each datatype class</caption>
+ * <tr>
+ * <th>
+ * Datatype Class
+ * </th>
+ * <th>
+ * Function to Create
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * COMPOUND
+ * </td>
+ * <td>
+ * #H5Tcreate
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * OPAQUE
+ * </td>
+ * <td>
+ * #H5Tcreate
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * ENUM
+ * </td>
+ * <td>
+ * #H5Tenum_create
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * ARRAY
+ * </td>
+ * <td>
+ * #H5Tarray_create
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * VL
+ * </td>
+ * <td>
+ * #H5Tvlen_create
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * Once the datatype is created and the datatype properties set, the datatype object can be used.
+ *
+ * Predefined datatypes are defined by the library during initialization using the same mechanisms
+ * as described here. Each predefined datatype is locked (\ref H5Tlock), so that it cannot be changed or
+ * destroyed. User-defined datatypes may also be locked using \ref H5Tlock.
+ *
+ * <h4>User-defined Atomic Datatypes</h4>
+ * Table 15 summarizes the API methods that set properties of atomic types. Table 16 shows
+ * properties specific to numeric types, Table 17 shows properties specific to the string datatype
+ * class. Note that offset, pad, etc. do not apply to strings. Table 18 shows the specific property of
+ * the OPAQUE datatype class.
+ *
+ * <table>
+ * <caption align=top>Table 15. API methods that set properties of atomic datatypes</caption>
+ * <tr>
+ * <th>
+ * Functions
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_size (\ref hid_t type, size_t size)
+ * </td>
+ * <td>
+ * Set the total size of the element in bytes. This includes padding which may appear on either
+ * side of the actual value. If this property is reset to a smaller value which would cause the
+ * significant part of the data to extend beyond the edge of the datatype, then the offset property
+ * is decremented a bit at a time. If the offset reaches zero and the significant part of the data
+ * still extends beyond the edge of the datatype then the precision property is decremented a bit at
+ * a time. Decreasing the size of a datatype may fail if the #H5T_FLOAT bit fields would extend beyond
+ * the significant part of the type.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_order (\ref hid_t type, \ref H5T_order_t order)
+ * </td>
+ * <td>
+ * Set the byte order to little-endian (#H5T_ORDER_LE) or big-endian (#H5T_ORDER_BE).
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_precision (\ref hid_t type, size_t precision)
+ * </td>
+ * <td>
+ * Set the number of significant bits of a datatype. The offset property (defined below) identifies
+ * its location. The size property defined above represents the entire size (in bytes) of the datatype.
+ * If the precision is decreased then padding bits are inserted on the MSB side of the significant
+ * bits (this will fail for #H5T_FLOAT types if it results in the sign,mantissa, or exponent bit field
+ * extending beyond the edge of the significant bit field). On the other hand, if the precision is
+ * increased so that it “hangs over” the edge of the total size then the offset property is decremented
+ * a bit at a time. If the offset reaches zero and the significant bits still hang over the edge, then
+ * the total size is increased a byte at a time.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_offset (\ref hid_t type, size_t offset)
+ * </td>
+ * <td>
+ * Set the bit location of the least significant bit of a bit field whose length is precision. The
+ * bits of the entire data are numbered beginning at zero at the least significant bit of the least
+ * significant byte (the byte at the lowest memory address for a little-endian type or the byte at
+ * the highest address for a big-endian type). The offset property defines the bit location of the
+ * least significant bit of a bit field whose length is precision. If the offset is increased so the
+ * significant bits “hang over” the edge of the datum, then the size property is automatically incremented.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_pad (\ref hid_t type, \ref H5T_pad_t lsb, \ref H5T_pad_t msb)
+ * </td>
+ * <td>
+ * Set the padding to zeros (#H5T_PAD_ZERO) or ones (#H5T_PAD_ONE). Padding is the bits of a
+ * data element which are not significant as defined by the precision and offset properties. Padding
+ * in the low-numbered bits is lsb padding and padding in the high-numbered bits is msb padding.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 16. API methods that set properties of numeric datatypes</caption>
+ * <tr>
+ * <th>
+ * Functions
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_sign (\ref hid_t type, \ref H5T_sign_t sign)
+ * </td>
+ * <td>
+ * (INTEGER)Integer data can be signed two’s complement (#H5T_SGN_2) or unsigned (#H5T_SGN_NONE).
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_fields (\ref hid_t type, size_t spos, size_t epos, size_t esize,
+ * size_t mpos, size_t msize)
+ * </td>
+ * <td>
+ * (FLOAT)Set the properties define the location (bit position of least significant bit of the field)
+ * and size (in bits) of each field. The sign bit is always of length one and none of the fields are
+ * allowed to overlap.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_ebias (\ref hid_t type, size_t ebias)
+ * </td>
+ * <td>
+ * (FLOAT)The exponent is stored as a non-negative value which is ebias larger than the true exponent.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_norm (\ref hid_t type, \ref H5T_norm_t norm)
+ * </td>
+ * <td>
+ * (FLOAT)This property describes the normalization method of the mantissa.
+ * <ul><li>#H5T_NORM_MSBSET: the mantissa is shifted left (if non-zero) until the first bit
+ * after theradix point is set and the exponent is adjusted accordingly. All bits of the
+ * mantissa after the radix point are stored. </li>
+ * <li>#H5T_NORM_IMPLIED: the mantissa is shifted left (if non-zero) until the first bit
+ * after the radix point is set and the exponent is adjusted accordingly. The first bit after
+ * the radix point is not stored since it is always set. </li>
+ * <li>#H5T_NORM_NONE: the fractional part of the mantissa is stored without normalizing it.</li></ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_inpad (\ref hid_t type, \ref H5T_pad_t inpad)
+ * </td>
+ * <td>
+ * (FLOAT)
+If any internal bits (that is, bits between the sign bit, the mantissa field,
+and the exponent field but within the precision field) are unused, then they will be
+filled according to the value of this property. The padding can be:
+ * \li #H5T_PAD_BACKGROUND
+ * \li #H5T_PAD_ZERO
+ * \li #H5T_PAD_ONE
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 17. API methods that set properties of string datatypes</caption>
+ * <tr>
+ * <th>
+ * Functions
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_size (\ref hid_t type, size_t size)
+ * </td>
+ * <td>
+ * Set the length of the string, in bytes. The precision is automatically set to 8*size.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_precision (\ref hid_t type, size_t precision)
+ * </td>
+ * <td>
+ * The precision must be a multiple of 8.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_cset (\ref hid_t type_id, \ref H5T_cset_t cset)
+ * </td>
+ * <td>
+ * Two character sets are currently supported:
+ * \li ASCII (#H5T_CSET_ASCII)
+ * \li UTF-8 (#H5T_CSET_UTF8).
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_strpad (\ref hid_t type_id, H5T_str_t strpad)
+ * </td>
+ * <td>
+ * The string datatype has a fixed length, but the string may be shorter than the length. This
+ * property defines the storage mechanism for the left over bytes. The method used to store
+ * character strings differs with the programming language:
+ * \li C usually null terminates strings
+ * \li Fortran left-justifies and space-pads strings
+ *
+ * Valid string padding values, as passed in the parameter strpad, are as follows:
+ * \li #H5T_STR_NULLTERM: Null terminate (as C does)
+ * \li #H5T_STR_NULLPAD: Pad with zeros
+ * \li #H5T_STR_SPACEPAD: Pad with spaces (as FORTRAN does)
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption align=top>Table 18. API methods that set properties of opaque datatypes</caption>
+ * <tr>
+ * <th>
+ * Functions
+ * </th>
+ * <th>
+ * Description
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * \ref herr_t \ref H5Tset_tag (\ref hid_t type_id, const char *tag)
+ * </td>
+ * <td>
+ * Tags the opaque datatype type_id with an ASCII identifier tag.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <h4>Examples</h4>
+ * The example below shows how to create a 128-bit little-endian signed integer type. Increasing
+ * the precision of a type automatically increases the total size. Note that the proper
+ * procedure is to begin from a type of the intended datatype class which in this case is a
+ * NATIVE INT.
+ *
+ * <em>Create a new 128-bit little-endian signed integer datatype</em>
+ * \code
+ * hid_t new_type = H5Tcopy (H5T_NATIVE_INT);
+ * H5Tset_precision (new_type, 128);
+ * H5Tset_order (new_type, H5T_ORDER_LE);
+ * \endcode
+ *
+ * The figure below shows the storage layout as the type is defined. The \ref H5Tcopy creates a
+ * datatype that is the same as #H5T_NATIVE_INT. In this example, suppose this is a 32-bit
+ * big-endian number (Figure a). The precision is set to 128 bits, which automatically extends
+ * the size to 8 bytes (Figure b). Finally, the byte order is set to little-endian (Figure c).
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig6.gif "The storage layout for a new 128-bit little-endian signed integer datatype"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * The significant bits of a data element can be offset from the beginning of the memory for that
+ * element by an amount of padding. The offset property specifies the number of bits of padding
+ * that appear to the “right of” the value. The table and figure below show how a 32-bit unsigned
+ * integer with 16-bits of precision having the value 0x1122 will be laid out in memory.
+ *
+ * <table>
+ * <caption align=top>Table 19. Memory Layout for a 32-bit unsigned integer</caption>
+ * <tr>
+ * <th>
+ * Byte Position
+ * </th>
+ * <th>
+ * Big-Endian<br />Offset=0
+ * </th>
+ * <th>
+ * Big-Endian<br />Offset=16
+ * </th>
+ * <th>
+ * Little-Endian<br />Offset=0
+ * </th>
+ * <th>
+ * Little-Endian<br />Offset=16
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * 0:
+ * </td>
+ * <td>
+ * [pad]
+ * </td>
+ * <td>
+ * [0x11]
+ * </td>
+ * <td>
+ * [0x22]
+ * </td>
+ * <td>
+ * [pad]
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * 1:
+ * </td>
+ * <td>
+ * [pad]
+ * </td>
+ * <td>
+ * [0x22]
+ * </td>
+ * <td>
+ * [0x11]
+ * </td>
+ * <td>
+ * [pad]
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * 2:
+ * </td>
+ * <td>
+ * [0x11]
+ * </td>
+ * <td>
+ * [pad]
+ * </td>
+ * <td>
+ * [pad]
+ * </td>
+ * <td>
+ * [0x22]
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * 3:
+ * </td>
+ * <td>
+ * [0x22]
+ * </td>
+ * <td>
+ * [pad]
+ * </td>
+ * <td>
+ * [pad]
+ * </td>
+ * <td>
+ * [0x11]
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig7.gif "Memory Layout for a 32-bit unsigned integer"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * If the offset is incremented then the total size is incremented also if necessary to prevent
+ * significant bits of the value from hanging over the edge of the datatype.
+ *
+ * The bits of the entire data are numbered beginning at zero at the least significant bit of the least
+ * significant byte (the byte at the lowest memory address for a little-endian type or the byte at the
+ * highest address for a big-endian type). The offset property defines the bit location of the least
+ * significant bit of a bit field whose length is precision. If the offset is increased so the significant
+ * bits “hang over” the edge of the datum, then the size property is automatically incremented.
+ *
+ * To illustrate the properties of the integer datatype class, the example below shows how to create
+ * a user-defined datatype that describes a 24-bit signed integer that starts on the third bit of a 32-bit
+ * word. The datatype is specialized from a 32-bit integer, the precision is set to 24 bits, and the
+ * offset is set to 3.
+ *
+ * <em>A user-defined datatype with a 24-bit signed integer</em>
+ * \code
+ * hid_t dt;
+ *
+ * dt = H5Tcopy(H5T_SDT_I32LE);
+ * H5Tset_precision(dt, 24);
+ * H5Tset_offset(dt,3);
+ * H5Tset_pad(dt, H5T_PAD_ZERO, H5T_PAD_ONE);
+ * \endcode
+ *
+ * The figure below shows the storage layout for a data element. Note that the unused bits in the
+ * offset will be set to zero and the unused bits at the end will be set to one, as specified in the
+ * \ref H5Tset_pad call.
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig8.gif "A user-defined integer datatype with a range of -1,048,583 to 1,048,584"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * To illustrate a user-defined floating point number, the example below shows how to create a 24-bit
+ * floating point number that starts 5 bits into a 4 byte word. The floating point number is defined to
+ * have a mantissa of 19 bits (bits 5-23), an exponent of 3 bits (25-27), and the sign bit is bit 28.
+ * (Note that this is an illustration of what can be done and is not necessarily a floating point
+ * format that a user would require.)
+ *
+ * <em>A user-defined datatype with a 24-bit floating point datatype</em>
+ * \code
+ * hid_t dt;
+ *
+ * dt = H5Tcopy(H5T_SDT_F32LE);
+ * H5Tset_precision(dt, 24);
+ * H5Tset_fields (dt, 28, 25, 3, 5, 19);
+ * H5Tset_pad(dt, H5T_PAD_ZERO, H5T_PAD_ONE);
+ * H5Tset_inpad(dt, H5T_PAD_ZERO);
+ * \endcode
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig9.gif "A user-defined floating point datatype"
+ * </td>
+ * </tr>
+ * </table>
+ * The figure above shows the storage layout of a data element for this datatype. Note that there is
+ * an unused bit (24) between the mantissa and the exponent. This bit is filled with the inpad value
+ * which in this case is 0.
+ *
+ * The sign bit is always of length one and none of the fields are allowed to overlap. When
+ * expanding a floating-point type one should set the precision first; when decreasing the size one
+ * should set the field positions and sizes first.
+ *
+ * <h4>Composite Datatypes</h4>
+ * All composite datatypes must be user-defined; there are no predefined composite datatypes.
+ *
+ * <h4>Compound Datatypes</h4>
+ * The subsections below describe how to create a compound datatype and how to write and read
+ * data of a compound datatype.
+ *
+ * <h4>Defining Compound Datatypes</h4>
+ *
+ * Compound datatypes are conceptually similar to a C struct or Fortran derived types. The
+ * compound datatype defines a contiguous sequence of bytes, which are formatted using one up to
+ * 2^16 datatypes (members). A compound datatype may have any number of members, in any
+ * order, and the members may have any datatype, including compound. Thus, complex nested
+ * compound datatypes can be created. The total size of the compound datatype is greater than or
+ * equal to the sum of the size of its members, up to a maximum of 2^32 bytes. HDF5 does not
+ * support datatypes with distinguished records or the equivalent of C unions or Fortran
+ * EQUIVALENCE statements.
+ *
+ * Usually a C struct or Fortran derived type will be defined to hold a data point in memory, and the
+ * offsets of the members in memory will be the offsets of the struct members from the beginning
+ * of an instance of the struct. The HDF5 C library provides a macro #HOFFSET (s,m)to calculate
+ * the member’s offset. The HDF5 Fortran applications have to calculate offsets by using sizes of
+ * members datatypes and by taking in consideration the order of members in the Fortran derived type.
+ * \code
+ * HOFFSET(s,m)
+ * \endcode
+ * This macro computes the offset of member m within a struct s
+ * \code
+ * offsetof(s,m)
+ * \endcode
+ * This macro defined in stddef.h does exactly the same thing as the HOFFSET()macro.
+ *
+ * Note for Fortran users: Offsets of Fortran structure members correspond to the offsets within a
+ * packed datatype (see explanation below) stored in an HDF5 file.
+ *
+ * Each member of a compound datatype must have a descriptive name which is the key used to
+ * uniquely identify the member within the compound datatype. A member name in an HDF5
+ * datatype does not necessarily have to be the same as the name of the member in the C struct or
+ * Fortran derived type, although this is often the case. Nor does one need to define all members of
+ * the C struct or Fortran derived type in the HDF5 compound datatype (or vice versa).
+ *
+ * Unlike atomic datatypes which are derived from other atomic datatypes, compound datatypes are
+ * created from scratch. First, one creates an empty compound datatype and specifies its total size.
+ * Then members are added to the compound datatype in any order. Each member type is inserted
+ * at a designated offset. Each member has a name which is the key used to uniquely identify the
+ * member within the compound datatype.
+ *
+ * The example below shows a way of creating an HDF5 C compound datatype to describe a
+ * complex number. This is a structure with two components, “real” and “imaginary”, and each
+ * component is a double. An equivalent C struct whose type is defined by the complex_tstruct is
+ * shown.
+ *
+ * <em>A compound datatype for complex numbers in C</em>
+ * \code
+ * typedef struct {
+ * double re; //real part
+ * double im; //imaginary part
+ * } complex_t;
+ *
+ * hid_t complex_id = H5Tcreate (H5T_COMPOUND, sizeof (complex_t));
+ * H5Tinsert (complex_id, “real”, HOFFSET(complex_t,re),
+ * H5T_NATIVE_DOUBLE);
+ * H5Tinsert (complex_id, “imaginary”, HOFFSET(complex_t,im),
+ * H5T_NATIVE_DOUBLE);
+ * \endcode
+ *
+ * The example below shows a way of creating an HDF5 Fortran compound datatype to describe a
+ * complex number. This is a Fortran derived type with two components, “real” and “imaginary”,
+ * and each component is DOUBLE PRECISION. An equivalent Fortran TYPE whose type is defined
+ * by the TYPE complex_t is shown.
+ *
+ * <em>A compound datatype for complex numbers in Fortran</em>
+ * \code
+ * TYPE complex_t
+ * DOUBLE PRECISION re ! real part
+ * DOUBLE PRECISION im; ! imaginary part
+ * END TYPE complex_t
+ *
+ * CALL h5tget_size_f(H5T_NATIVE_DOUBLE, re_size, error)
+ * CALL h5tget_size_f(H5T_NATIVE_DOUBLE, im_size, error)
+ * complex_t_size = re_size + im_size
+ * CALL h5tcreate_f(H5T_COMPOUND_F, complex_t_size, type_id)
+ * offset = 0
+ * CALL h5tinsert_f(type_id, “real”, offset, H5T_NATIVE_DOUBLE, error)
+ * offset = offset + re_size
+ * CALL h5tinsert_f(type_id, “imaginary”, offset, H5T_NATIVE_DOUBLE, error)
+ * \endcode
+ *
+ * Important Note: The compound datatype is created with a size sufficient to hold all its members.
+ * In the C example above, the size of the C struct and the #HOFFSET macro are used as a
+ * convenient mechanism to determine the appropriate size and offset. Alternatively, the size and
+ * offset could be manually determined: the size can be set to 16 with “real” at offset 0 and
+ * “imaginary” at offset 8. However, different platforms and compilers have different sizes for
+ * “double” and may have alignment restrictions which require additional padding within the
+ * structure. It is much more portable to use the #HOFFSET macro which assures that the values will
+ * be correct for any platform.
+ *
+ * The figure below shows how the compound datatype would be laid out assuming that
+ * NATIVE_DOUBLE are 64-bit numbers and that there are no alignment requirements. The total
+ * size of the compound datatype will be 16 bytes, the “real” component will start at byte 0, and
+ * “imaginary” will start at byte 8.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig10.gif "Layout of a compound datatype"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * The members of a compound datatype may be any HDF5 datatype including the compound,
+ * array, and variable-length (VL) types. The figure and example below show the memory layout
+ * and code which creates a compound datatype composed of two complex values, and each
+ * complex value is also a compound datatype as in the figure above.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig11.gif "Layout of a compound datatype nested in a compound datatype"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <em>Code for a compound datatype nested in a compound datatype</em>
+ * \code
+ * typedef struct {
+ * complex_t x;
+ * complex_t y;
+ * } surf_t;
+ *
+ * hid_t complex_id, surf_id; // hdf5 datatypes
+ *
+ * complex_id = H5Tcreate (H5T_COMPOUND, sizeof(complex_t));
+ * H5Tinsert (complex_id, “re”, HOFFSET(complex_t, re), H5T_NATIVE_DOUBLE);
+ * H5Tinsert (complex_id, “im”, HOFFSET(complex_t, im), H5T_NATIVE_DOUBLE);
+ *
+ * surf_id = H5Tcreate (H5T_COMPOUND, sizeof(surf_t));
+ * H5Tinsert (surf_id, “x”, HOFFSET(surf_t, x), complex_id);
+ * H5Tinsert (surf_id, “y”, HOFFSET(surf_t, y), complex_id);
+ * \endcode
+ *
+ * Note that a similar result could be accomplished by creating a compound datatype and inserting
+ * four fields. See the figure below. This results in the same layout as the figure above. The difference
+ * would be how the fields are addressed. In the first case, the real part of ‘y’ is called ‘y.re’;
+ * in the second case it is ‘y-re’.
+ *
+ * <em>Another compound datatype nested in a compound datatype</em>
+ * \code
+ * typedef struct {
+ * complex_t x;
+ * complex_t y;
+ * } surf_t;
+ *
+ * hid_t surf_id = H5Tcreate (H5T_COMPOUND, sizeof(surf_t));
+ * H5Tinsert (surf_id, “x-re”, HOFFSET(surf_t, x.re), H5T_NATIVE_DOUBLE);
+ * H5Tinsert (surf_id, “x-im”, HOFFSET(surf_t, x.im), H5T_NATIVE_DOUBLE);
+ * H5Tinsert (surf_id, “y-re”, HOFFSET(surf_t, y.re), H5T_NATIVE_DOUBLE);
+ * H5Tinsert (surf_id, “y-im”, HOFFSET(surf_t, y.im), H5T_NATIVE_DOUBLE);
+ * \endcode
+ *
+ * The members of a compound datatype do not always fill all the bytes. The #HOFFSET macro
+ * assures that the members will be laid out according to the requirements of the platform and
+ * language. The example below shows an example of a C struct which requires extra bytes of
+ * padding on many platforms. The second element, ‘b’, is a 1-byte character followed by an 8 byte
+ * double, ‘c’. On many systems, the 8-byte value must be stored on a 4-or 8-byte boundary. This
+ * requires the struct to be larger than the sum of the size of its elements.
+ *
+ * In the example below, sizeof and #HOFFSET are used to assure that the members are inserted at
+ * the correct offset to match the memory conventions of the platform. The figure below shows how
+ * this data element would be stored in memory, assuming the double must start on a 4-byte
+ * boundary. Notice the extra bytes between ‘b’ and ‘c’.
+ *
+ * <em>A compound datatype that requires padding</em>
+ * \code
+ * typedef struct {
+ * int a;
+ * char b;
+ * double c;
+ * } s1_t;
+ *
+ * hid_t s1_tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
+ * H5Tinsert (s1_tid, “x-im”, HOFFSET(s1_t, a), H5T_NATIVE_INT);
+ * H5Tinsert (s1_tid, “y-re”, HOFFSET(s1_t, b), H5T_NATIVE_CHAR);
+ * H5Tinsert (s1_tid, “y-im”, HOFFSET(s1_t, c), H5T_NATIVE_DOUBLE);
+ * \endcode
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig12.gif "Memory layout of a compound datatype that requires padding"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * However, data stored on disk does not require alignment, so unaligned versions of compound
+ * data structures can be created to improve space efficiency on disk. These unaligned compound
+ * datatypes can be created by computing offsets by hand to eliminate inter-member padding, or the
+ * members can be packed by calling #H5Tpack (which modifies a datatype directly, so it is usually
+ * preceded by a call to #H5Tcopy).
+ *
+ * The example below shows how to create a disk version of the compound datatype from the
+ * figure above in order to store data on disk in as compact a form as possible. Packed compound
+ * datatypes should generally not be used to describe memory as they may violate alignment
+ * constraints for the architecture being used. Note also that using a packed datatype for disk
+ * storage may involve a higher data conversion cost.
+ *
+ * <em>Create a packed compound datatype in C</em>
+ * \code
+ * hid_t s2_tid = H5Tcopy (s1_tid);
+ * H5Tpack (s2_tid);
+ * \endcode
+ *
+ * The example below shows the sequence of Fortran calls to create a packed compound datatype.
+ * An HDF5 Fortran compound datatype never describes a compound datatype in memory and
+ * compound data is ALWAYS written by fields as described in the next section. Therefore packing
+ * is not needed unless the offset of each consecutive member is not equal to the sum of the sizes of
+ * the previous members.
+ *
+ * <em>Create a packed compound datatype in Fortran</em>
+ * \code
+ * CALL h5tcopy_f(s1_id, s2_id, error)
+ * CALL h5tpack_f(s2_id, error)
+ * \endcode
+ *
+ * <h4>Creating and Writing Datasets with Compound Datatypes</h4>
+ *
+ * Creating datasets with compound datatypes is similar to creating datasets with any other HDF5
+ * datatypes. But writing and reading may be different since datasets that have compound datatypes
+ * can be written or read by a field (member) or subsets of fields (members). The compound
+ * datatype is the only composite datatype that supports “sub-setting” by the elements the datatype
+ * is built from.
+ *
+ * The example below shows a C example of creating and writing a dataset with a compound
+ * datatype.
+ *
+ *
+ * <em>Create and write a dataset with a compound datatype in C</em>
+ * \code
+ * typedef struct s1_t {
+ * int a;
+ * float b;
+ * double c;
+ * } s1_t;
+ *
+ * s1_t data[LENGTH];
+ *
+ * // Initialize data
+ * for (i = 0; i < LENGTH; i++) {
+ * data[i].a = i;
+ * data[i].b = i*i;
+ * data[i].c = 1./(i+1);
+ * }
+ *
+ * ...
+ *
+ * s1_tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
+ * H5Tinsert(s1_tid, “a_name”, HOFFSET(s1_t, a), H5T_NATIVE_INT);
+ * H5Tinsert(s1_tid, “b_name”, HOFFSET(s1_t, b), H5T_NATIVE_FLOAT);
+ * H5Tinsert(s1_tid, “c_name”, HOFFSET(s1_t, c), H5T_NATIVE_DOUBLE);
+ *
+ * ...
+ *
+ * dataset_id = H5Dcreate(file_id, “SDScompound.h5”, s1_t,
+ * space_id, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * H5Dwrite (dataset_id, s1_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+ * \endcode
+ *
+ * The example below shows the content of the file written on a little-endian machine.
+ * <em>Create and write a little-endian dataset with a compound datatype in C</em>
+ * \code
+ * HDF5 “SDScompound.h5” {
+ * GROUP “/” {
+ * DATASET “ArrayOfStructures” {
+ * DATATYPE H5T_COMPOUND {
+ * H5T_STD_I32LE “a_name”;
+ * H5T_IEEE_F32LE “b_name”;
+ * H5T_IEEE_F64LE “c_name”;
+ * }
+ * DATASPACE SIMPLE { ( 3 ) / ( 3 ) }
+ * DATA {
+ * (0): {
+ * 0,
+ * 0,
+ * 1
+ * },
+ * (1): {
+ * 0,
+ * 1,
+ * 0.5
+ * },
+ * (2): {
+ * 0,
+ * 4,
+ * 0.333333
+ * }
+ * }
+ * }
+ * }
+ * }
+ * \endcode
+ *
+ * It is not necessary to write the whole data at once. Datasets with compound datatypes can be
+ * written by field or by subsets of fields. In order to do this one has to remember to set the transfer
+ * property of the dataset using the H5Pset_preserve call and to define the memory datatype that
+ * corresponds to a field. The example below shows how float and double fields are written to the
+ * dataset.
+ *
+ * <em>Writing floats and doubles to a dataset</em>
+ * \code
+ * typedef struct sb_t {
+ * float b;
+ * double c;
+ * } sb_t;
+ *
+ * typedef struct sc_t {
+ * float b;
+ * double c;
+ * } sc_t;
+ * sb_t data1[LENGTH];
+ * sc_t data2[LENGTH];
+ *
+ * // Initialize data
+ * for (i = 0; i < LENGTH; i++) {
+ * data1.b = i * i;
+ * data2.c = 1./(i + 1);
+ * }
+ *
+ * ...
+ *
+ * // Create dataset as in example 15
+ *
+ * ...
+ *
+ * // Create memory datatypes corresponding to float
+ * // and double datatype fields
+ *
+ * sb_tid = H5Tcreate (H5T_COMPOUND, sizeof(sb_t));
+ * H5Tinsert(sb_tid, “b_name”, HOFFSET(sb_t, b), H5T_NATIVE_FLOAT);
+ * sc_tid = H5Tcreate (H5T_COMPOUND, sizeof(sc_t));
+ * H5Tinsert(sc_tid, “c_name”, HOFFSET(sc_t, c), H5T_NATIVE_DOUBLE);
+ *
+ * ...
+ *
+ * // Set transfer property
+ * xfer_id = H5Pcreate(H5P_DATASET_XFER);
+ * H5Pset_preserve(xfer_id, 1);
+ * H5Dwrite (dataset_id, sb_tid, H5S_ALL, H5S_ALL, xfer_id, data1);
+ * H5Dwrite (dataset_id, sc_tid, H5S_ALL, H5S_ALL, xfer_id, data2);
+ * \endcode
+ *
+ * The figure below shows the content of the file written on a little-endian machine. Only float and
+ * double fields are written. The default fill value is used to initialize the unwritten integer field.
+ * <em>Writing floats and doubles to a dataset on a little-endian system</em>
+ * \code
+ * HDF5 “SDScompound.h5” {
+ * GROUP “/” {
+ * DATASET “ArrayOfStructures” {
+ * DATATYPE H5T_COMPOUND {
+ * H5T_STD_I32LE “a_name”;
+ * H5T_IEEE_F32LE “b_name”;
+ * H5T_IEEE_F64LE “c_name”;
+ * }
+ * DATASPACE SIMPLE { ( 3 ) / ( 3 ) }
+ * DATA {
+ * (0): {
+ * 0,
+ * 0,
+ * 1
+ * },
+ * (1): {
+ * 0,
+ * 1,
+ * 0.5
+ * },
+ * (2): {
+ * 0,
+ * 4,
+ * 0.333333
+ * }
+ * }
+ * }
+ * }
+ * }
+ * \endcode
+ *
+ * The example below contains a Fortran example that creates and writes a dataset with a
+ * compound datatype. As this example illustrates, writing and reading compound datatypes in
+ * Fortran is always done by fields. The content of the written file is the same as shown in the
+ * example above.
+ * <em>Create and write a dataset with a compound datatype in Fortran</em>
+ * \code
+ * ! One cannot write an array of a derived datatype in
+ * ! Fortran.
+ * TYPE s1_t
+ * INTEGER a
+ * REAL b
+ * DOUBLE PRECISION c
+ * END TYPE s1_t
+ * TYPE(s1_t) d(LENGTH)
+ * ! Therefore, the following code initializes an array
+ * ! corresponding to each field in the derived datatype
+ * ! and writesthose arrays to the dataset
+ *
+ * INTEGER, DIMENSION(LENGTH) :: a
+ * REAL, DIMENSION(LENGTH) :: b
+ * DOUBLE PRECISION, DIMENSION(LENGTH) :: c
+ *
+ * ! Initialize data
+ * do i = 1, LENGTH
+ * a(i) = i-1
+ * b(i) = (i-1) * (i-1)
+ * c(i) = 1./i
+ * enddo
+ *
+ * ...
+ *
+ * ! Set dataset transfer property to preserve partially
+ * ! initialized fields during write/read to/from dataset
+ * ! with compound datatype.
+ * !
+ * CALL h5pcreate_f(H5P_DATASET_XFER_F, plist_id, error)
+ * CALL h5pset_preserve_f(plist_id, .TRUE., error)
+ *
+ * ...
+ *
+ * !
+ * ! Create compound datatype.
+ * !
+ * ! First calculate total size by calculating sizes of
+ * ! each member
+ * !
+ * CALL h5tget_size_f(H5T_NATIVE_INTEGER, type_sizei, error)
+ * CALL h5tget_size_f(H5T_NATIVE_REAL, type_sizer, error)
+ * CALL h5tget_size_f(H5T_NATIVE_DOUBLE, type_sized, error)
+ * type_size = type_sizei + type_sizer + type_sized
+ * CALL h5tcreate_f(H5T_COMPOUND_F, type_size, dtype_id, error)
+ * !
+ * ! Insert members
+ * !
+ * !
+ * ! INTEGER member
+ * !
+ * offset = 0
+ * CALL h5tinsert_f(dtype_id, “a_name”, offset, H5T_NATIVE_INTEGER, error)
+ * !
+ * ! REAL member
+ * !
+ * offset = offset + type_sizei
+ * CALL h5tinsert_f(dtype_id, “b_name”, offset, H5T_NATIVE_REAL, error)
+ * !
+ * ! DOUBLE PRECISION member
+ * !
+ * offset = offset + type_sizer
+ * CALL h5tinsert_f(dtype_id, “c_name”, offset, H5T_NATIVE_DOUBLE, error)
+ * !
+ * ! Create the dataset with compound datatype.
+ * !
+ * CALL h5dcreate_f(file_id, dsetname, dtype_id, dspace_id, &dset_id, error, H5P_DEFAULT_F,
+ * H5P_DEFAULT_F, H5P_DEFAULT_F)
+ * !
+ *
+ * ...
+ *
+ * ! Create memory types. We have to create a compound
+ * ! datatype for each member we want to write.
+ * !
+ * CALL h5tcreate_f(H5T_COMPOUND_F, type_sizei, dt1_id, error)
+ * offset = 0
+ * CALL h5tinsert_f(dt1_id, “a_name”, offset, H5T_NATIVE_INTEGER, error)
+ * !
+ * CALL h5tcreate_f(H5T_COMPOUND_F, type_sizer, dt2_id, error)
+ * offset = 0
+ * CALL h5tinsert_f(dt2_id, “b_name”, offset, H5T_NATIVE_REAL, error)
+ * !
+ * CALL h5tcreate_f(H5T_COMPOUND_F, type_sized, dt3_id, error)
+ * offset = 0
+ * CALL h5tinsert_f(dt3_id, “c_name”, offset, H5T_NATIVE_DOUBLE, error)
+ * !
+ * ! Write data by fields in the datatype. Fields order
+ * ! is not important.
+ * !
+ * CALL h5dwrite_f(dset_id, dt3_id, c, data_dims, error, xfer_prp = plist_id)
+ * CALL h5dwrite_f(dset_id, dt2_id, b, data_dims, error, xfer_prp = plist_id)
+ * CALL h5dwrite_f(dset_id, dt1_id, a, data_dims, error, xfer_prp = plist_id)
+ * \endcode
+ *
+ * <h4>Reading Datasets with Compound Datatypes</h4>
+ *
+ * Reading datasets with compound datatypes may be a challenge. For general applications there is
+ * no way to know a priori the corresponding C structure. Also, C structures cannot be allocated on
+ * the fly during discovery of the dataset’s datatype. For general C, C++, Fortran and Java
+ * application the following steps will be required to read and to interpret data from the dataset with
+ * compound datatype:
+ * \li 1. Get the identifier of the compound datatype in the file with the #H5Dget_type call
+ * \li 2. Find the number of the compound datatype members with the #H5Tget_nmembers call
+ * \li 3. Iterate through compound datatype members
+ * <ul><li>Get member class with the #H5Tget_member_class call</li>
+ * <li>Get member name with the #H5Tget_member_name call</li>
+ * <li>Check class type against predefined classes
+ * <ul><li>#H5T_INTEGER</li>
+ * <li>#H5T_FLOAT</li>
+ * <li>#H5T_STRING</li>
+ * <li>#H5T_BITFIELD</li>
+ * <li>#H5T_OPAQUE</li>
+ * <li>#H5T_COMPOUND</li>
+ * <li>#H5T_REFERENCE</li>
+ * <li>#H5T_ENUM</li>
+ * <li>#H5T_VLEN</li>
+ * <li>#H5T_ARRAY</li></ul>
+ * </li>
+ * <li>If class is #H5T_COMPOUND, then go to step 2 and repeat all steps under step 3. If
+ * class is not #H5T_COMPOUND, then a member is of an atomic class and can be read
+ * to a corresponding buffer after discovering all necessary information specific to each
+ * atomic type (for example, size of the integer or floats, super class for enumerated and
+ * array datatype, and its sizes)</li></ul>
+ *
+ * The examples below show how to read a dataset with a known compound datatype.
+ *
+ * The first example below shows the steps needed to read data of a known structure. First, build a
+ * memory datatype the same way it was built when the dataset was created, and then second use
+ * the datatype in an #H5Dread call.
+ *
+ * <em>Read a dataset using a memory datatype</em>
+ * \code
+ * typedef struct s1_t {
+ * int a;
+ * float b;
+ * double c;
+ * } s1_t;
+ *
+ * s1_t *data;
+ *
+ * ...
+ *
+ * s1_tid = H5Tcreate(H5T_COMPOUND, sizeof(s1_t));
+ * H5Tinsert(s1_tid, “a_name”, HOFFSET(s1_t, a), H5T_NATIVE_INT);
+ * H5Tinsert(s1_tid, “b_name”, HOFFSET(s1_t, b), H5T_NATIVE_FLOAT);
+ * H5Tinsert(s1_tid, “c_name”, HOFFSET(s1_t, c), H5T_NATIVE_DOUBLE);
+ *
+ * ...
+ *
+ * dataset_id = H5Dopen(file_id, “SDScompound.h5”, H5P_DEFAULT);
+ *
+ * ...
+ *
+ * data = (s1_t *) malloc (sizeof(s1_t)*LENGTH);
+ * H5Dread(dataset_id, s1_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+ * \endcode
+ *
+ * Instead of building a memory datatype, the application could use the
+ * #H5Tget_native_type function. See the example below.
+ *
+ * <em>Read a dataset using H5Tget_native_type</em>
+ * \code
+ * typedef struct s1_t {
+ * int a;
+ * float b;
+ * double c;
+ * } s1_t;
+ *
+ * s1_t *data;
+ * hid_t file_s1_t, mem_s1_t;
+ *
+ * ...
+ *
+ * dataset_id = H5Dopen(file_id, “SDScompound.h5”, H5P_DEFAULT);
+ * // Discover datatype in the file
+ * file_s1_t = H5Dget_type(dataset_id);
+ * // Find corresponding memory datatype
+ * mem_s1_t = H5Tget_native_type(file_s1_t, H5T_DIR_DEFAULT);
+ *
+ * ...
+ *
+ * data = (s1_t *) malloc (sizeof(s1_t)*LENGTH);
+ * H5Dread (dataset_id,mem_s1_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+ * \endcode
+ *
+ * The example below shows how to read just one float member of a compound datatype.
+ *
+ * <em>Read one floating point member of a compound datatype</em>
+ * \code
+ * typedef struct sf_t {
+ * float b;
+ * } sf_t;
+ *
+ * sf_t *data;
+ *
+ * ...
+ *
+ * sf_tid = H5Tcreate(H5T_COMPOUND, sizeof(sf_t));
+ * H5Tinsert(sf_tid, “b_name”, HOFFSET(sf_t, b), H5T_NATIVE_FLOAT);
+ *
+ * ...
+ *
+ * dataset_id = H5Dopen(file_id, “SDScompound.h5”, H5P_DEFAULT);
+ *
+ * ...
+ *
+ * data = (sf_t *) malloc (sizeof(sf_t) * LENGTH);
+ * H5Dread(dataset_id, sf_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+ * \endcode
+ *
+ * The example below shows how to read float and double members of a compound datatype into a
+ * structure that has those fields in a different order. Please notice that #H5Tinsert calls can be used
+ * in an order different from the order of the structure’s members.
+ *
+ * <em>Read float and double members of a compound datatype</em>
+ * \code
+ * typedef struct sdf_t {
+ * double c;
+ * float b;
+ * } sdf_t;
+ *
+ * sdf_t *data;
+ *
+ * ...
+ *
+ * sdf_tid = H5Tcreate(H5T_COMPOUND, sizeof(sdf_t));
+ * H5Tinsert(sdf_tid, “b_name”, HOFFSET(sdf_t, b), H5T_NATIVE_FLOAT);
+ * H5Tinsert(sdf_tid, “c_name”, HOFFSET(sdf_t, c), H5T_NATIVE_DOUBLE);
+ *
+ * ...
+ *
+ * dataset_id = H5Dopen(file_id, “SDScompound.h5”, H5P_DEFAULT);
+ *
+ * ...
+ *
+ * data = (sdf_t *) malloc (sizeof(sdf_t) * LENGTH);
+ * H5Dread(dataset_id, sdf_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
+ * \endcode
+ *
+ * <h4>Array</h4>
+ *
+ * Many scientific datasets have multiple measurements for each point in a space. There are several
+ * natural ways to represent this data, depending on the variables and how they are used in
+ * computation. See the table and the figure below.
+ *
+ * <table>
+ * <caption>Representing data with multiple measurements</caption>
+ * <tr>
+ * <th>
+ * <p>Storage Strategy</p>
+ * </th>
+ * <th>
+ * <p>Stored as</p>
+ * </th>
+ * <th>
+ * <p>Remarks</p>
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>Multiple planes
+ * </td>
+ * <td>
+ * Several datasets with identical dataspaces
+ * </td>
+ * <td>
+ * This is optimal when variables are accessed individually, or when often uses only selected
+ * variables.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Additional dimension
+ * </td>
+ * <td>
+ * One dataset, the last “dimension” is a vec-tor of variables
+ * </td>
+ * <td>
+ * This can give good performance, although selecting only a few variables may be slow. This may
+ * not reflect the science.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Record with multiple values
+ * </td>
+ * <td>
+ * One dataset with compound datatype
+ * </td>
+ * <td>
+ * This enables the variables to be read all together or selected. Also handles “vectors” of
+ * heterogeneous data.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Vector or Tensor value
+ * </td>
+ * <td>
+ * One dataset, each data element is a small array of values.
+ * </td>
+ * <td>
+ * This uses the same amount of space as the previous two, and may represent the science model
+ * better.
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <caption>Figure 13 Representing data with multiple measurements</caption>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig13a.gif
+ * </td>
+ * <td>
+ * \image html Dtypes_fig13b.gif
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig13c.gif
+ * </td>
+ * <td>
+ * \image html Dtypes_fig13d.gif
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * The HDF5 #H5T_ARRAY datatype defines the data element to be a homogeneous, multi-dimensional array.
+ * See Figure 13 above. The elements of the array can be any HDF5 datatype
+ * (including compound and array), and the size of the datatype is the total size of the array. A
+ * dataset of array datatype cannot be subdivided for I/O within the data element: the entire array of
+ * the data element must be transferred. If the data elements need to be accessed separately, for
+ * example, by plane, then the array datatype should not be used. The table below shows
+ * advantages and disadvantages of various storage methods.
+ *
+ * <table>
+ * <caption>Storage method advantages and disadvantages</caption>
+ * <tr>
+ * <th>
+ * <p>Method</p>
+ * </th>
+ * <th>
+ * <p>Advantages</p>
+ * </th>
+ * <th>
+ * <p>Disadvantages</p>
+ * </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * Multiple Datasets
+ * </td>
+ * <td>
+ * Easy to access each plane, can select any plane(s)
+ * </td>
+ * <td>
+ * Less efficient to access a ‘column’ through the planes
+ * </td>
+ * </tr>
+ * </tr>
+ * <tr>
+ * <td>
+ * N+1 Dimension
+ * </td>
+ * <td>
+ * All access patterns supported
+ * </td>
+ * <td>
+ * Must be homogeneous datatype<br />
+ * The added dimension may not make sense in the scientific model
+ * </td>
+ * </tr>
+ * </tr>
+ * <tr>
+ * <td>
+ * Compound Datatype
+ * </td>
+ * <td>
+ * Can be heterogeneous datatype
+ * </td>
+ * <td>
+ * Planes must be named, selection is by plane<br />
+ * Not a natural representation for a matrix
+ * </td>
+ * </tr>
+ * </tr>
+ * <tr>
+ * <td>
+ * Array
+ * </td>
+ * <td>
+ * A natural representation for vector or tensor data
+ * </td>
+ * <td>
+ * Cannot access elements separately (no access by plane)
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * An array datatype may be multi-dimensional with 1 to #H5S_MAX_RANK(the maximum rank
+ * of a dataset is currently 32) dimensions. The dimensions can be any size greater than 0, but
+ * unlimited dimensions are not supported (although the datatype can be a variable-length datatype).
+ *
+ * An array datatype is created with the #H5Tarray_create call, which specifies the number of
+ * dimensions, the size of each dimension, and the base type of the array. The array datatype can
+ * then be used in any way that any datatype object is used. The example below shows the creation
+ * of a datatype that is a two-dimensional array of native integers, and this is then used to create a
+ * dataset. Note that the dataset can be a dataspace that is any number and size of dimensions. The figure
+ * below shows the layout in memory assuming that the native integers are 4 bytes. Each
+ * data element has 6 elements, for a total of 24 bytes.
+ *
+ * <em>Create a two-dimensional array datatype</em>
+ * \code
+ * hid_t file, dataset;
+ * hid_t datatype, dataspace;
+ * hsize_t adims[] = {3, 2};
+ *
+ * datatype = H5Tarray_create(H5T_NATIVE_INT, 2, adims, NULL);
+ *
+ * dataset = H5Dcreate(file, datasetname, datatype,
+ * dataspace, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * \endcode
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig14.gif "Memory layout of a two-dimensional array datatype"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <h4>Variable-length Datatypes</h4>
+ *
+ * A variable-length (VL) datatype is a one-dimensional sequence of a datatype which are not fixed
+ * in length from one dataset location to another. In other words, each data element may have a
+ * different number of members. Variable-length datatypes cannot be divided;the entire data
+ * element must be transferred.
+ *
+ * VL datatypes are useful to the scientific community in many different ways, possibly including:
+ * <ul>
+ * <li>Ragged arrays: Multi-dimensional ragged arrays can be implemented with the last (fastest changing)
+ * dimension being ragged by using a VL datatype as the type of the element stored.
+ * </li>
+ * <li>Fractal arrays: A nested VL datatype can be used to implement ragged arrays of ragged arrays, to
+ * whatever nesting depth is required for the user.
+ * </li>
+ * <li>Polygon lists: A common storage requirement is to efficiently store arrays of polygons with
+ * different numbers of vertices. A VL datatype can be used to efficiently and succinctly describe
+ * an array of polygons with different numbers of vertices.
+ * </li>
+ * <li>Character strings: Perhaps the most common use of VL datatypes will be to store C-like VL
+ * character strings in dataset elements or as attributes of objects.
+ * </li>
+ * <li>Indices (for example, of objects within a file): An array of VL object references could be used
+ * as an index to all the objects in a file which contain a particular sequence of dataset values.
+ * </li>
+ * <li>Object Tracking: An array of VL dataset region references can be used as a method of tracking
+ * objects or features appearing in a sequence of datasets.
+ * </li>
+ * </ul>
+ *
+ * A VL datatype is created by calling #H5Tvlen_create which specifies the base datatype. The first
+ * example below shows an example of code that creates a VL datatype of unsigned integers. Each
+ * data element is a one-dimensional array of zero or more members and is stored in the
+ * hvl_t structure. See the second example below.
+ *
+ * <em>Create a variable-length datatype of unsigned integers</em>
+ * \code
+ * tid1 = H5Tvlen_create (H5T_NATIVE_UINT);
+ *
+ * dataset=H5Dcreate(fid1,“Dataset1”, tid1, sid1, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * \endcode
+ *
+ * <em>Data element storage for members of the VL datatype</em>
+ * \code
+ * typedef struct
+ * {
+ * size_t len; // Length of VL data
+ * //(in base type units)
+ * void *p; // Pointer to VL data
+ * } hvl_t;
+ * \endcode
+ *
+ * The first example below shows how the VL data is written. For each of the 10 data elements, a
+ * length and data buffer must be allocated. Below the two examples is a figure that shows how the
+ * data is laid out in memory.
+ *
+ * An analogous procedure must be used to read the data. See the second example below. An
+ * appropriate array of vl_t must be allocated, and the data read. It is then traversed one data
+ * element at a time. The #H5Dvlen_reclaim call frees the data buffer for the buffer. With each
+ * element possibly being of different sequence lengths for a dataset with a VL datatype, the
+ * memory for the VL datatype must be dynamically allocated. Currently there are two methods of
+ * managing the memory for VL datatypes: the standard C malloc/free memory allocation routines
+ * or a method of calling user-defined memory management routines to allocate or free memory
+ * (set with #H5Pset_vlen_mem_manager). Since the memory allocated when reading (or writing)
+ * may be complicated to release, the #H5Dvlen_reclaim function is provided to traverse a memory
+ * buffer and free the VL datatype information without leaking memory.
+ *
+ * <em>Write VL data</em>
+ * \code
+ * hvl_t wdata[10]; // Information to write
+ *
+ * // Allocate and initialize VL data to write
+ * for(i = 0; i < 10; i++) {
+ * wdata[i].p = malloc((i + 1) * sizeof(unsigned int));
+ * wdata[i].len = i + 1;
+ * for(j = 0; j < (i + 1); j++)
+ * ((unsigned int *)wdata[i].p)[j]=i * 10 + j;
+ * }
+ * ret = H5Dwrite(dataset, tid1, H5S_ALL, H5S_ALL, H5P_DEFAULT, wdata);
+ * \endcode
+ *
+ * <em>Read VL data</em>
+ * \code
+ * hvl_t rdata[SPACE1_DIM1];
+ * ret = H5Dread(dataset, tid1, H5S_ALL, H5S_ALL, xfer_pid, rdata);
+ *
+ * for(i = 0; i < SPACE1_DIM1; i++) {
+ * printf(“%d: len %d ”,rdata[i].len);
+ * for(j = 0; j < rdata[i].len; j++) {
+ * printf(“ value: %u\n”,((unsigned int *)rdata[i].p)[j]);
+ * }
+ * }
+ * ret = H5Dvlen_reclaim(tid1, sid1, xfer_pid, rdata);
+ * \endcode
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig15.gif "Memory layout of a VL datatype"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * The user program must carefully manage these relatively complex data structures. The
+ * #H5Dvlen_reclaim function performs a standard traversal, freeing all the data. This function
+ * analyzes the datatype and dataspace objects, and visits each VL data element, recursing through
+ * nested types. By default, the system free is called for the pointer in each vl_t. Obviously, this
+ * call assumes that all of this memory was allocated with the system malloc.
+ *
+ * The user program may specify custom memory manager routines, one for allocating and one for
+ * freeing. These may be set with the #H5Pset_vlen_mem_manager, and must have the following
+ * prototypes:
+ * <ul>
+ * <li>
+ * \code
+ * typedef void *(*H5MM_allocate_t)(size_t size, void *info);
+ * \endcode
+ * </li>
+ * <li>
+ * \code
+ * typedef void (*H5MM_free_t)(void *mem, void *free_info);
+ * \endcode
+ * </li>
+ * </ul>
+ * The utility function #H5Dvlen_get_buf_size checks the number of bytes required to store the VL
+ * data from the dataset. This function analyzes the datatype and dataspace object to visit all the VL
+ * data elements, to determine the number of bytes required to store the data for the in the
+ * destination storage (memory). The size value is adjusted for data conversion and alignment in the
+ * destination.
+ *
* \subsection subsec_datatype_other Other Non-numeric Datatypes
+ * Several datatype classes define special types of objects.
+ *
* \subsubsection subsubsec_datatype_other_strings Strings
+ * Text data is represented by arrays of characters, called strings. Many programming languages
+ * support different conventions for storing strings, which may be fixed or variable-length, and may
+ * have different rules for padding unused storage. HDF5 can represent strings in several ways. See
+ * the figure below.
+ *
+ * The strings to store are “Four score” and “lazy programmers.”
+ * <table>
+ * <caption>A string stored as one-character elements in a one-dimensional array</caption>
+ * <tr>
+ * <td>
+ * a) #H5T_NATIVE_CHAR: The dataset is a one-dimensional array with 29 elements, and each element
+ * is a single character.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig16a.gif
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * b) Fixed-length string: The dataset is a one-dimensional array with two elements, and each
+ * element is 20 characters.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig16b.gif
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * c) Variable-length string: The dataset is a one-dimensional array with two elements, and each
+ * element is a variable-length string. This is the same result when stored as a fixed-length
+ * string except that the first element of the array will need only 11 bytes for storage instead of 20.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig16c.gif
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig16d.gif
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * First, a dataset may have a dataset with datatype #H5T_NATIVE_CHAR with each character of
+ * the string as an element of the dataset. This will store an unstructured block of text data, but
+ * gives little indication of any structure in the text. See item a in the figure above.
+ *
+ * A second alternative is to store the data using the datatype class #H5T_STRING with each
+ * element a fixed length. See item b in the figure above. In this approach, each element might be a
+ * word or a sentence, addressed by the dataspace. The dataset reserves space for the specified
+ * number of characters, although some strings may be shorter. This approach is simple and usually
+ * is fast to access, but can waste storage space if the length of the Strings varies.
+ *
+ * A third alternative is to use a variable-length datatype. See item c in the figure above. This can
+ * be done using the standard mechanisms described above. The program would use vl_t structures
+ * to write and read the data.
+ *
+ * A fourth alternative is to use a special feature of the string datatype class to set the size of the
+ * datatype to #H5T_VARIABLE. See item c in the figure above. The example below shows a
+ * declaration of a datatype of type #H5T_C_S1 which is set to #H5T_VARIABLE. The HDF5
+ * Library automatically translates between this and the vl_t structure. Note: the #H5T_VARIABLE
+ * size can only be used with string datatypes.
+ * <em>Set the string datatype size to H5T_VARIABLE</em>
+ * \code
+ * tid1 = H5Tcopy (H5T_C_S1);
+ * ret = H5Tset_size (tid1, H5T_VARIABLE);
+ * \endcode
+ *
+ * Variable-length strings can be read into C strings (in other words, pointers to zero terminated
+ * arrays of char). See the example below.
+ * <em>Read variable-length strings into C strings</em>
+ * \code
+ * char *rdata[SPACE1_DIM1];
+ *
+ * ret = H5Dread(dataset, tid1, H5S_ALL, H5S_ALL, xfer_pid, rdata);
+ *
+ * for(i = 0; i < SPACE1_DIM1; i++) {
+ * printf(“%d: len: %d, str is: %s\n”, i, strlen(rdata[i]), rdata[i]);
+ * }
+ *
+ * ret = H5Dvlen_reclaim(tid1, sid1, xfer_pid, rdata);
+ * \endcode
+ *
* \subsubsection subsubsec_datatype_other_refs Reference
+ * In HDF5, objects (groups, datasets, and committed datatypes) are usually accessed by name.
+ * There is another way to access stored objects - by reference. There are two reference datatypes:
+ * object reference and region reference. Object reference objects are created with #H5Rcreate and
+ * other calls (cross reference). These objects can be stored and retrieved in a dataset as elements
+ * with reference datatype. The first example below shows an example of code that creates
+ * references to four objects, and then writes the array of object references to a dataset. The second
+ * example below shows a dataset of datatype reference being read and one of the reference objects
+ * being dereferenced to obtain an object pointer.
+ *
+ * In order to store references to regions of a dataset, the datatype should be #H5T_STD_REF_DSETREG.
+ * Note that a data element must be either an object reference or a region reference: these are
+ * different types and cannot be mixed within a single array.
+ *
+ * A reference datatype cannot be divided for I/O: an element is read or written completely.
+ *
+ * <em>Create object references and write to a dataset</em>
+ * \code
+ * dataset= H5Dcreate (fid1, “Dataset3”, H5T_STD_REF_OBJ, sid1, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ *
+ * // Create reference to dataset
+ * ret = H5Rcreate(&wbuf[0], fid1,“/Group1/Dataset1”, H5R_OBJECT, -1);
+ *
+ * // Create reference to dataset
+ * ret = H5Rcreate(&wbuf[1], fid1, “/Group1/Dataset2”, H5R_OBJECT, -1);
+ *
+ * // Create reference to group
+ * ret = H5Rcreate(&wbuf[2], fid1, “/Group1”, H5R_OBJECT, -1);
+ *
+ * // Create reference to committed datatype
+ * ret = H5Rcreate(&wbuf[3], fid1, “/Group1/Datatype1”, H5R_OBJECT, -1);
+ *
+ * // Write selection to disk
+ * ret=H5Dwrite(dataset, H5T_STD_REF_OBJ, H5S_ALL, H5S_ALL, H5P_DEFAULT, wbuf);
+ * \endcode
+ *
+ * <em>Read a dataset with a reference datatype</em>
+ * \code
+ * rbuf = malloc(sizeof(hobj_ref_t)*SPACE1_DIM1);
+ *
+ * // Read selection from disk
+ * ret=H5Dread(dataset, H5T_STD_REF_OBJ, H5S_ALL, H5S_ALL, H5P_DEFAULT, rbuf);
+ *
+ * // Open dataset object
+ * dset2 = H5Rdereference(dataset, H5R_OBJECT, &rbuf[0]);
+ * \endcode
+ *
* \subsubsection subsubsec_datatype_other_enum ENUM
+ * The enum datatype implements a set of (name, value) pairs, similar to C/C++ enum. The values
+ * are currently limited to native integer datatypes. Each name can be the name of only one value,
+ * and each value can have only one name.
+ *
+ * The data elements of the ENUMERATION are stored according to the datatype. An example
+ * would be as an array of integers. The example below shows an example of how to create an
+ * enumeration with five elements. The elements map symbolic names to 2-byte integers. See the
+ * table below.
+ * <em>Create an enumeration with five elements</em>
+ * \code
+ * hid_t hdf_en_colors;
+ * short val;
+ *
+ * hdf_en_colors = H5Tcreate(H5T_ENUM, sizeof(short));
+ * H5Tenum_insert(hdf_en_colors, “RED”, (val=0, &val));
+ * H5Tenum_insert(hdf_en_colors, “GREEN”, (val=1, &val));
+ * H5Tenum_insert(hdf_en_colors, “BLUE”, (val=2, &val));
+ * H5Tenum_insert(hdf_en_colors, “WHITE”, (val=3, &val));
+ * H5Tenum_insert(hdf_en_colors, “BLACK”, (val=4, &val));
+ * H5Dcreate(fileid, datasetname, hdf_en_colors, spaceid, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * \endcode
+ *
+ * <table>
+ * <caption>An enumeration with five elements</caption>
+ * <tr>
+ * <th>Name</th>
+ * <th>Value</th>
+ * </tr>
+ * <tr>
+ * <td>RED</td>
+ * <td>0</td>
+ * </tr>
+ * <tr>
+ * <td>GREEN</td>
+ * <td>1</td>
+ * </tr>
+ * <tr>
+ * <td>BLUE</td>
+ * <td>2</td>
+ * </tr>
+ * <tr>
+ * <td>WHITE</td>
+ * <td>3</td>
+ * </tr>
+ * <tr>
+ * <td>BLACK</td>
+ * <td>4</td>
+ * </tr>
+ * </table>
+ *
+ * The figure below shows how an array of eight values might be stored. Conceptually, the array is
+ * an array of symbolic names [BLACK, RED, WHITE, BLUE, ...] See item a in the figure below.
+ * These are stored as the values and are short integers. So, the first 2 bytes are the value associated
+ * with “BLACK”, which is the number 4, and so on. See item b in the figure below.
+ * <table>
+ * <caption>Storing an enum array</caption>
+ * <tr>
+ * <td>
+ * a) Logical data to be written - eight elements
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig17a.gif
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * b) The storage layout. Total size of the array is 16 bytes, 2 bytes per element.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig17b.gif
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * The order that members are inserted into an enumeration type is unimportant; the important part
+ * is the associations between the symbol names and the values. Thus, two enumeration datatypes
+ * will be considered equal if and only if both types have the same symbol/value associations and
+ * both have equal underlying integer datatypes. Type equality is tested with the H5Tequal
+ * function.
+ *
+ * If a particular architecture type is required, a little-endian or big-endian datatype for example,
+ * use a native integer datatype as the ENUM base datatype and use #H5Tconvert on values as they
+ * are read from or written to a dataset.
+ *
* \subsubsection subsubsec_datatype_other_opaque Opaque
+ * In some cases, a user may have data objects that should be stored and retrieved as blobs with no
+ * attempt to interpret them. For example, an application might wish to store an array of encrypted
+ * certificates which are 100 bytes long.
+ *
+ * While an arbitrary block of data may always be stored as bytes, characters, integers, or whatever,
+ * this might mislead programs about the meaning of the data. The opaque datatype defines data
+ * elements which are uninterpreted by HDF5. The opaque data may be labeled with
+ * #H5Tset_tag with a string that might be used by an application. For example, the encrypted
+ * certificates might have a tag to indicate the encryption and the certificate standard.
+ *
* \subsubsection subsubsec_datatype_other_bitfield Bitfield
+ * Some data is represented as bits, where the number of bits is not an integral byte and the bits are
+ * not necessarily interpreted as a standard type. Some examples might include readings from
+ * machine registers (for example, switch positions), a cloud mask, or data structures with several
+ * small integers that should be store in a single byte.
+ *
+ * This data could be stored as integers, strings, or enumerations. However, these storage methods
+ * would likely result in considerable wasted space. For example, storing a cloud mask with one
+ * byte per value would use up to eight times the space of a packed array of bits.
+ *
+ * The HDF5 bitfield datatype class defines a data element that is a contiguous sequence of bits,
+ * which are stored on disk in a packed array. The programming model is the same as for unsigned
+ * integers: the datatype object is created by copying a predefined datatype, and then the precision,
+ * offset, and padding are set.
+ *
+ * While the use of the bitfield datatype will reduce storage space substantially, there will still be
+ * wasted space if the bitfield as a whole does not match the 1-, 2-, 4-, or 8-byte unit in which it is
+ * written. The remaining unused space can be removed by applying the N-bit filter to the dataset
+ * containing the bitfield data. For more information, see "Using the N-bit Filter."
+ *
* \subsection subsec_datatype_fill Fill Values
+ * The “fill value” for a dataset is the specification of the default value assigned to data elements
+ * that have not yet been written. In the case of a dataset with an atomic datatype, the fill value is a
+ * single value of the appropriate datatype, such as ‘0’ or ‘-1.0’. In the case of a dataset with a
+ * composite datatype, the fill value is a single data element of the appropriate type. For example,
+ * for an array or compound datatype, the fill value is a single data element with values for all the
+ * component elements of the array or compound datatype.
+ *
+ * The fill value is set (permanently) when the dataset is created. The fill value is set in the dataset
+ * creation properties in the #H5Dcreate call. Note that the #H5Dcreate call must also include the
+ * datatype of the dataset, and the value provided for the fill value will be interpreted as a single
+ * element of this datatype. The example below shows code which creates a dataset of integers with
+ * fill value -1. Any unwritten data elements will be set to -1.
+ *
+ * <em>Create a dataset with a fill value of -1</em>
+ * \code
+ * hid_t plist_id;
+ * int filler;
+ *
+ * filler = -1;
+ * plist_id = H5Pcreate(H5P_DATASET_CREATE);
+ * H5Pset_fill_value(plist_id, H5T_NATIVE_INT, &filler);
+ *
+ * // Create the dataset with fill value ‘-1’.
+ * dataset_id = H5Dcreate(file_id, “/dset”, H5T_STD_I32BE, dataspace_id, H5P_DEFAULT, plist_id,
+ * H5P_DEFAULT);
+ * \endcode
+ *
+ * <em>Create a fill value for a compound datatype</em>
+ * \code
+ * typedef struct s1_t {
+ * int a;
+ * char b;
+ * double c;
+ * } s1_t;
+ * s1_t filler;
+ *
+ * s1_tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
+ * H5Tinsert(s1_tid, “a_name”, HOFFSET(s1_t, a), H5T_NATIVE_INT);
+ * H5Tinsert(s1_tid, “b_name”, HOFFSET(s1_t, b), H5T_NATIVE_CHAR);
+ * H5Tinsert(s1_tid, “c_name”, HOFFSET(s1_t, c), H5T_NATIVE_DOUBLE);
+ *
+ * filler.a = -1;
+ * filler.b = ‘*’;
+ * filler.c = -2.0;
+ * plist_id = H5Pcreate(H5P_DATASET_CREATE);
+ * H5Pset_fill_value(plist_id, s1_tid, &filler);
+ *
+ * // Create the dataset with fill value
+ * // (-1, ‘*’, -2.0).
+ * dataset = H5Dcreate(file, datasetname, s1_tid, space, H5P_DEFAULT, plist_id, H5P_DEFAULT);
+ * \endcode
+ *
+ * The code above shows how to create a fill value for a compound datatype. The procedure is the
+ * same as the previous example except the filler must be a structure with the correct fields. Each
+ * field is initialized to the desired fill value.
+ *
+ * The fill value for a dataset can be retrieved by reading the dataset creation properties of the
+ * dataset and then by reading the fill value with #H5Pget_fill_value. The data will be read into
+ * memory using the storage layout specified by the datatype. This transfer will convert data in the
+ * same way as #H5Dread. The example below shows how to get the fill value from the dataset
+ * created in the example "Create a dataset with a fill value of -1".
+ *
+ * <em>Retrieve a fill value</em>
+ * \code
+ * hid_t plist2;
+ * int filler;
+ *
+ * dataset_id = H5Dopen(file_id, “/dset”, H5P_DEFAULT);
+ * plist2 = H5Dget_create_plist(dataset_id);
+ *
+ * H5Pget_fill_value(plist2, H5T_NATIVE_INT, &filler);
+ *
+ * // filler has the fill value, ‘-1’
+ * \endcode
+ *
+ * A similar procedure is followed for any datatype. The example below shows how to read the fill
+ * value for the compound datatype created in an example above. Note that the program must pass
+ * an element large enough to hold a fill value of the datatype indicated by the argument to
+ * #H5Pget_fill_value. Also, the program must understand the datatype in order to interpret its
+ * components. This may be difficult to determine without knowledge of the application that
+ * created the dataset.
+ *
+ * <em>Read the fill value for a compound datatype</em>
+ * \code
+ * char *fillbuf;
+ * int sz;
+ *
+ * dataset = H5Dopen( file, DATASETNAME, H5P_DEFAULT);
+ *
+ * s1_tid = H5Dget_type(dataset);
+ *
+ * sz = H5Tget_size(s1_tid);
+ *
+ * fillbuf = (char *)malloc(sz);
+ *
+ * plist_id = H5Dget_create_plist(dataset);
+ *
+ * H5Pget_fill_value(plist_id, s1_tid, fillbuf);
+ *
+ * printf(“filler.a: %d\n”,((s1_t *) fillbuf)->a);
+ * printf(“filler.b: %c\n”,((s1_t *) fillbuf)->b);
+ * printf(“filler.c: %f\n”,((s1_t *) fillbuf)->c);
+ * \endcode
+ *
* \subsection subsec_datatype_complex Complex Combinations of Datatypes
+ * Several composite datatype classes define collections of other datatypes, including other
+ * composite datatypes. In general, a datatype can be nested to any depth, with any combination of
+ * datatypes.
+ *
+ * For example, a compound datatype can have members that are other compound datatypes, arrays,
+ * VL datatypes. An array can be an array of array, an array of compound, or an array of VL. And a
+ * VL datatype can be a variable-length array of compound, array, or VL datatypes.
+ *
+ * These complicated combinations of datatypes form a logical tree, with a single root datatype, and
+ * leaves which must be atomic datatypes (predefined or user-defined). The figure below shows an
+ * example of a logical tree describing a compound datatype constructed from different datatypes.
+ *
+ * Recall that the datatype is a description of the layout of storage. The complicated compound
+ * datatype is constructed from component datatypes, each of which describes the layout of part of
+ * the storage. Any datatype can be used as a component of a compound datatype, with the
+ * following restrictions:
+ * <ul><li>1. No byte can be part of more than one component datatype (in other words, the fields cannot
+ * overlap within the compound datatype)</li>
+ * <li>2. The total size of the components must be less than or equal to the total size of the compound
+ * datatype</li></ul>
+ * These restrictions are essentially the rules for C structures and similar record types familiar from
+ * programming languages. Multiple typing, such as a C union, is not allowed in HDF5 datatypes.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig18.gif "A compound datatype built with different datatypes"
+ * </td>
+ * </tr>
+ * </table>
+ *
* \subsubsection subsubsec_datatype_complex_create Creating a Complicated Compound Datatype
+ * To construct a complicated compound datatype, each component is constructed, and then added
+ * to the enclosing datatype description. The example below shows how to create a compound
+ * datatype with four members:
+ * \li “T1”, a compound datatype with three members
+ * \li “T2”, a compound datatype with two members
+ * \li “T3”, a one-dimensional array of integers
+ * \li “T4”, a string
+ *
+ * Below the example code is a figure that shows this datatype as a logical tree. The output of the
+ * h5dump utility is shown in the example below the figure.
+ *
+ * Each datatype is created as a separate datatype object. Figure "The storage layout for the
+ * four member datatypes" below shows the storage layout
+ * for the four individual datatypes. Then the datatypes are inserted into the outer datatype at an
+ * appropriate offset. Figure "The storage layout of the combined four members" below shows the
+ * resulting storage layout. The combined record is 89 bytes long.
+ *
+ * The Dataset is created using the combined compound datatype. The dataset is declared to be a 4
+ * by 3 array of compound data. Each data element is an instance of the 89-byte compound
+ * datatype. Figure "The layout of the dataset" below shows the layout of the dataset, and expands
+ * one of the elements to show the relative position of the component data elements.
+ *
+ * Each data element is a compound datatype, which can be written or read as a record, or each
+ * field may be read or written individually. The first field (“T1”) is itself a compound datatype
+ * with three fields (“T1.a”, “T1.b”, and “T1.c”). “T1” can be read or written as a record, or
+ * individual fields can be accessed. Similarly, the second filed is a compound datatype with two
+ * fields (“T2.f1”, “T2.f2”).
+ *
+ * The third field (“T3”) is an array datatype. Thus, “T3” should be accessed as an array of 40
+ * integers. Array data can only be read or written as a single element, so all 40 integers must be
+ * read or written to the third field. The fourth field (“T4”) is a single string of length 25.
+ *
+ * <em>Create a compound datatype with four members</em>
+ * \code
+ * typedef struct s1_t {
+ * int a;
+ * char b;
+ * double c;
+ * } s1_t;
+ * typedef struct s2_t {
+ * float f1;
+ * float f2;
+ * } s2_t;
+ * hid_t s1_tid, s2_tid, s3_tid, s4_tid, s5_tid;
+ *
+ * // Create a datatype for s1
+ * s1_tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
+ * H5Tinsert(s1_tid, “a_name”, HOFFSET(s1_t, a), H5T_NATIVE_INT);
+ * H5Tinsert(s1_tid, “b_name”, HOFFSET(s1_t, b), H5T_NATIVE_CHAR);
+ * H5Tinsert(s1_tid, “c_name”, HOFFSET(s1_t, c), H5T_NATIVE_DOUBLE);
+ *
+ * // Create a datatype for s2.
+ * s2_tid = H5Tcreate (H5T_COMPOUND, sizeof(s2_t));
+ * H5Tinsert(s2_tid, “f1”, HOFFSET(s2_t, f1), H5T_NATIVE_FLOAT);
+ * H5Tinsert(s2_tid, “f2”, HOFFSET(s2_t, f2), H5T_NATIVE_FLOAT);
+ *
+ * // Create a datatype for an Array of integers
+ * s3_tid = H5Tarray_create(H5T_NATIVE_INT, RANK, dim);
+ *
+ * // Create a datatype for a String of 25 characters
+ * s4_tid = H5Tcopy(H5T_C_S1);
+ * H5Tset_size(s4_tid, 25);
+ *
+ * // Create a compound datatype composed of one of each of these types.
+ * // The total size is the sum of the size of each.
+ * sz = H5Tget_size(s1_tid) + H5Tget_size(s2_tid) + H5Tget_size(s3_tid) + H5Tget_size(s4_tid);
+ * s5_tid = H5Tcreate (H5T_COMPOUND, sz);
+ *
+ * // Insert the component types at the appropriate offsets.
+ * H5Tinsert(s5_tid, “T1”, 0, s1_tid);
+ * H5Tinsert(s5_tid, “T2”, sizeof(s1_t), s2_tid);
+ * H5Tinsert(s5_tid, “T3”, sizeof(s1_t) + sizeof(s2_t), s3_tid);
+ * H5Tinsert(s5_tid, “T4”, (sizeof(s1_t) + sizeof(s2_t) + H5Tget_size(s3_tid)), s4_tid);
+ *
+ * // Create the dataset with this datatype.
+ * dataset = H5Dcreate(file, DATASETNAME, s5_tid, space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * \endcode
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig19.gif "Logical tree for the compound datatype with four members"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <em> Output from h5dump for the compound datatype</em>
+ * \code
+ * DATATYPE H5T_COMPOUND {
+ * H5T_COMPOUND {
+ * H5T_STD_I32LE “a_name”;
+ * H5T_STD_I8LE “b_name”;
+ * H5T_IEEE_F64LE “c_name”;
+ * } “T1”;
+ * H5T_COMPOUND {
+ * H5T_IEEE_F32LE “f1”;
+ * H5T_IEEE_F32LE “f2”;
+ * } “T2”;
+ * H5T_ARRAY { [10] H5T_STD_I32LE } “T3”;
+ * H5T_STRING {
+ * STRSIZE 25;
+ * STRPAD H5T_STR_NULLTERM;
+ * CSET H5T_CSET_ASCII;
+ * CTYPE H5T_C_S1;
+ * } “T4”;
+ * }
+ * \endcode
+ *
+ * <table>
+ * <caption> The storage layout for the four member datatypes</caption>
+ * <tr>
+ * <td>
+ * a) Compound type ‘s1_t’, size 16 bytes.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig20a.gif
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * b) Compound type ‘s2_t’, size 8 bytes.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig20b.gif
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * c) Array type ‘s3_tid’, 40 integers, total size 40 bytes.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig20c.gif
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * d) String type ‘s4_tid’, size 25 bytes.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig20d.gif
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig21.gif "The storage layout of the combined four members"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * \li A 4 x 3 array of Compound Datatype
+ * \li Element [1,1] expanded
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig22.gif "The layout of the dataset"
+ * </td>
+ * </tr>
+ * </table>
+ *
* \subsubsection subsubsec_datatype_complex_analyze Analyzing and Navigating a Compound Datatype
+ * A complicated compound datatype can be analyzed piece by piece to discover the exact storage
+ * layout. In the example above, the outer datatype is analyzed to discover that it is a compound
+ * datatype with four members. Each member is analyzed in turn to construct a complete map of the
+ * storage layout.
+ *
+ * The example below shows an example of code that partially analyzes a nested compound
+ * datatype. The name and overall offset and size of the component datatype is discovered, and then
+ * its type is analyzed depending on the datatype class. Through this method, the complete storage
+ * layout can be discovered.
+ *
+ * <em> Output from h5dump for the compound datatype</em>
+ * \code
+ * s1_tid = H5Dget_type(dataset);
+ *
+ * if (H5Tget_class(s1_tid) == H5T_COMPOUND) {
+ * printf(“COMPOUND DATATYPE {\n”);
+ * sz = H5Tget_size(s1_tid);
+ * nmemb = H5Tget_nmembers(s1_tid);
+ * printf(“ %d bytes\n”,sz);
+ * printf(“ %d members\n”,nmemb);
+ * for (i =0; i < nmemb; i++) {
+ * s2_tid = H5Tget_member_type(s1_tid, i);
+ * if (H5Tget_class(s2_tid) == H5T_COMPOUND) {
+ * // recursively analyze the nested type.
+ * }
+ * else if (H5Tget_class(s2_tid) == H5T_ARRAY) {
+ * sz2 = H5Tget_size(s2_tid);
+ * printf(“ %s: NESTED ARRAY DATATYPE offset %d size %d
+ * {\n”, H5Tget_member_name(s1_tid, i), H5Tget_member_offset(s1_tid, i), sz2);
+ * H5Tget_array_dims(s2_tid, dim);
+ * s3_tid = H5Tget_super(s2_tid);
+ * // Etc., analyze the base type of the array
+ * }
+ * else {
+ * // analyze a simple type
+ * printf(“ %s: type code %d offset %d size %d\n”, H5Tget_member_name(s1_tid, i),
+ * H5Tget_class(s2_tid), H5Tget_member_offset(s1_tid, i), H5Tget_size(s2_tid));
+ * }
+ * // and so on....
+ * \endcode
+ *
* \subsection subsec_datatype_life Life Cycle of the Datatype Object
+ * Application programs access HDF5 datatypes through identifiers. Identifiers are obtained by
+ * creating a new datatype or by copying or opening an existing datatype. The identifier can be used
+ * until it is closed or until the library shuts down. See items a and b in the figure below. By default,
+ * a datatype is transient, and it disappears when it is closed.
+ *
+ * When a dataset or attribute is created (#H5Dcreate or #H5Acreate), its datatype is stored in the
+ * HDF5 file as part of the dataset or attribute object. See item c in the figure below. Once an object
+ * created, its datatype cannot be changed or deleted. The datatype can be accessed by calling
+ * #H5Dget_type, #H5Aget_type, #H5Tget_super, or #H5Tget_member_type. See item d in the figure
+ * below. These calls return an identifier to a transient copy of the datatype of the dataset or
+ * attribute unless the datatype is a committed datatype.
+ * Note that when an object is created, the stored datatype is a copy of the transient datatype. If two
+ * objects are created with the same datatype, the information is stored in each object with the same
+ * effect as if two different datatypes were created and used.
+ *
+ * A transient datatype can be stored using #H5Tcommit in the HDF5 file as an independent, named
+ * object, called a committed datatype. Committed datatypes were formerly known as named
+ * datatypes. See item e in the figure below. Subsequently, when a committed datatype is opened
+ * with #H5Topen (item f), or is obtained with #H5Tget_member_type or similar call (item k), the return
+ * is an identifier to a transient copy of the stored datatype. The identifier can be used in the
+ * same way as other datatype identifiers except that the committed datatype cannot be modified. When a
+ * committed datatype is copied with #H5Tcopy, the return is a new, modifiable, transient datatype
+ * object (item f).
+ *
+ * When an object is created using a committed datatype (#H5Dcreate, #H5Acreate), the stored
+ * datatype is used without copying it to the object. See item j in the figure below. In this case, if
+ * multiple objects are created using the same committed datatype, they all share the exact same
+ * datatype object. This saves space and makes clear that the datatype is shared. Note that a
+ * committed datatype can be shared by objects within the same HDF5 file, but not by objects in
+ * other files. For more information on copying committed datatypes to other HDF5 files, see the
+ * “Copying Committed Datatypes with H5Ocopy” topic in the “Additional Resources” chapter.
+ *
+ * A committed datatype can be deleted from the file by calling #H5Ldelete which replaces
+ * #H5Gunlink. See item i in the figure below. If one or more objects are still using the datatype, the
+ * committed datatype cannot be accessed with #H5Topen, but will not be removed from the file
+ * until it is no longer used. #H5Tget_member_type and similar calls will return a transient copy of the
+ * datatype.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig23.gif "Life cycle of a datatype"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * Transient datatypes are initially modifiable. Note that when a datatype is copied or when it is
+ * written to the file (when an object is created) or the datatype is used to create a composite
+ * datatype, a copy of the current state of the datatype is used. If the datatype is then modified, the
+ * changes have no effect on datasets, attributes, or datatypes that have already been created. See
+ * the figure below.
+ *
+ * A transient datatype can be made read-only (#H5Tlock). Note that the datatype is still transient,
+ * and otherwise does not change. A datatype that is immutable is read-only but cannot be closed
+ * except when the entire library is closed. The predefined types such as #H5T_NATIVE_INT are
+ * immutable transient types.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig24.gif "Transient datatype states: modifiable, read-only, and immutable"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * To create two or more datasets that share a common datatype, first commit the datatype, and then
+ * use that datatype to create the datasets. See the example below.
+ * <em> Create a shareable datatype</em>
+ * \code
+ * hid_t t1 = ...some transient type...;
+ * H5Tcommit (file, “shared_type”, t1, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * hid_t dset1 = H5Dcreate (file, “dset1”, t1, space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * hid_t dset2 = H5Dcreate (file, “dset2”, t1, space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ *
+ * hid_t dset1 = H5Dopen (file, “dset1”, H5P_DEFAULT);
+ * hid_t t2 = H5Dget_type (dset1);
+ * hid_t dset3 = H5Dcreate (file, “dset3”, t2, space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * hid_t dset4 = H5Dcreate (file, “dset4”, t2, space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+ * \endcode
+ *
+ * <table>
+ * <caption> Datatype APIs</caption>
+ * <tr>
+ * <th>Function</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>
+ * \code
+ * hid_t H5Topen (hid_t location, const char *name)
+ * \endcode
+ * </td>
+ * <td>
+ * A committed datatype can be opened by calling this function, which returns a datatype identifier.
+ * The identifier should eventually be released by calling #H5Tclose() to release resources. The
+ * committed datatype returned by this function is read-only or a negative value is returned for failure.
+ * The location is either a file or group identifier.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \code
+ * herr_t H5Tcommit (hid_t location, const char *name, hid_t type, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT)
+ * \endcode
+ * </td>
+ * <td>
+ * A transient datatype (not immutable) can be written to a file and turned into a committed datatype by
+ * calling this function. The location is either a file or group identifier and when combined with name
+ * refers to a new committed datatype.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * \code
+ * htri_t H5Tcommitted (hid_t type)
+ * \endcode
+ * </td>
+ * <td>
+ * A type can be queried to determine if it is a committed type or a transient type. If this function
+ * returns a positive value then the type is committed. Datasets which return committed datatypes with
+ * #H5Dget_type() are able to share the datatype with other datasets in the same file.
+ * </td>
+ * </tr>
+ * </table>
+ *
* \subsection subsec_datatype_transfer Data Transfer: Datatype Conversion and Selection
+ * When data is transferred (write or read), the storage layout of the data elements may be different.
+ * For example, an integer might be stored on disk in big-endian byte order and read into memory
+ * with little-endian byte order. In this case, each data element will be transformed by the HDF5
+ * Library during the data transfer.
+ *
+ * The conversion of data elements is controlled by specifying the datatype of the source and
+ * specifying the intended datatype of the destination. The storage format on disk is the datatype
+ * specified when the dataset is created. The datatype of memory must be specified in the library
+ * call.
+ *
+ * In order to be convertible, the datatype of the source and destination must have the same
+ * datatype class (with the exception of enumeration type). Thus, integers can be converted to other
+ * integers, and floats to other floats, but integers cannot (yet) be converted to floats. For each
+ * atomic datatype class, the possible conversions are defined. An enumeration datatype can be
+ * converted to an integer or a floating-point number datatype.
+ *
+ * Basically, any datatype can be converted to another datatype of the same datatype class. The
+ * HDF5 Library automatically converts all properties. If the destination is too small to hold the
+ * source value then an overflow or underflow exception occurs. If a handler is defined with the
+ * #H5Pset_type_conv_cb function, it will be called. Otherwise, a default action will be performed.
+ * The table below summarizes the default actions.
+ *
+ * <table>
+ * <caption>Default actions for datatype conversion exceptions</caption>
+ * <tr>
+ * <th>Datatype Class</th>
+ * <th>Possible Exceptions</th>
+ * <th>Default Action</th>
+ * </tr>
+ * <tr>
+ * <td>Integer</td>
+ * <td>Size, offset, pad</td>
+ * <td></td>
+ * </tr>
+ * <tr>
+ * <td>Float</td>
+ * <td>Size, offset, pad, ebits</td>
+ * <td></td>
+ * </tr>
+ * <tr>
+ * <td>String</td>
+ * <td>Size</td>
+ * <td>Truncates, zero terminate if required.</td>
+ * </tr>
+ * <tr>
+ * <td>Enumeration</td>
+ * <td>No field</td>
+ * <td>All bits set</td>
+ * </tr>
+ * </table>
+ *
+ * For example, when reading data from a dataset, the source datatype is the datatype set when the
+ * dataset was created, and the destination datatype is the description of the storage layout in
+ * memory. The destination datatype must be specified in the #H5Dread call. The example below
+ * shows an example of reading a dataset of 32-bit integers. The figure below the example shows
+ * the data transformation that is performed.
+ * <em>Specify the destination datatype with H5Dread</em>
+ * \code
+ * // Stored as H5T_STD_BE32
+ * // Use the native memory order in the destination
+ * mem_type_id = H5Tcopy(H5T_NATIVE_INT);
+ * status = H5Dread(dataset_id, mem_type_id, mem_space_id, file_space_id, xfer_plist_id, buf);
+ * \endcode
+ *
+ * <table>
+ * <caption>Layout of a datatype conversion</caption>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig25a.gif<br />
+ * \image html Dtypes_fig25b.gif<br />
+ * \image html Dtypes_fig25c.gif
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * One thing to note in the example above is the use of the predefined native datatype
+ * #H5T_NATIVE_INT. Recall that in this example, the data was stored as a 4-bytes in big-endian
+ * order. The application wants to read this data into an array of integers in memory. Depending on
+ * the system, the storage layout of memory might be either big or little-endian, so the data may
+ * need to be transformed on some platforms and not on others. The #H5T_NATIVE_INT type is set
+ * by the HDF5 Library to be the correct type to describe the storage layout of the memory on the
+ * system. Thus, the code in the example above will work correctly on any platform, performing a
+ * transformation when needed.
+ *
+ * There are predefined native types for most atomic datatypes, and these can be combined in
+ * composite datatypes. In general, the predefined native datatypes should always be used for data
+ * stored in memory.
+ * Predefined native datatypes describe the storage properties of memory.
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig26.gif "An enum datatype conversion"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <em>Create an aligned and packed compound datatype</em>
+ * \code
+ * // Stored as H5T_STD_BE32
+ * // Use the native memory order in the destination
+ * mem_type_id = H5Tcopy(H5T_NATIVE_INT);
+ * status = H5Dread(dataset_id, mem_type_id, mem_space_id, file_space_id, xfer_plist_id, buf);
+ * \endcode
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig27.gif "Alignment of a compound datatype"
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <em>Transfer some fields of a compound datatype</em>
+ * \code
+ * // Stored as H5T_STD_BE32
+ * // Use the native memory order in the destination
+ * mem_type_id = H5Tcopy(H5T_NATIVE_INT);
+ * status = H5Dread(dataset_id, mem_type_id, mem_space_id, file_space_id, xfer_plist_id, buf);
+ * \endcode
+ *
+ * <table>
+ * <tr>
+ * <td>
+ * \image html Dtypes_fig28.gif "Layout when an element is skipped"
+ * </td>
+ * </tr>
+ * </table>
+ *
* \subsection subsec_datatype_text Text Descriptions of Datatypes: Conversion to and from
*
+ * HDF5 provides a means for generating a portable and human-readable text description of a
+ * datatype and for generating a datatype from such a text description. This capability is particularly
+ * useful for creating complex datatypes in a single step, for creating a text description of a datatype
+ * for debugging purposes, and for creating a portable datatype definition that can then be used to
+ * recreate the datatype on many platforms or in other applications.
+ *
+ * These tasks are handled by two functions provided in the HDF5 Lite high-level library:
+ * \li #H5LTtext_to_dtype Creates an HDF5 datatype in a single step.
+ * \li #H5LTdtype_to_text Translates an HDF5 datatype into a text description.
+ *
+ * Note that this functionality requires that the HDF5 High-Level Library (H5LT) be installed.
+ *
+ * While #H5LTtext_to_dtype can be used to generate any sort of datatype, it is particularly useful
+ * for complex datatypes.
+ *
+ * #H5LTdtype_to_text is most likely to be used in two sorts of situations: when a datatype must be
+ * closely examined for debugging purpose or to create a portable text description of the datatype
+ * that can then be used to recreate the datatype on other platforms or in other applications.
+ *
+ * These two functions work for all valid HDF5 datatypes except time, bitfield, and reference
+ * datatypes.
+ *
+ * The currently supported text format used by #H5LTtext_to_dtype and #H5LTdtype_to_text is the
+ * data description language (DDL) and conforms to the \ref DDLBNF110. The portion of the
+ * \ref DDLBNF110 that defines HDF5 datatypes appears below.
+ * <em>The definition of HDF5 datatypes from the HDF5 DDL</em>
+ * \code
+ * <datatype> ::= <atomic_type> | <compound_type> | <variable_length_type> | <array_type>
+ *
+ * <atomic_type> ::= <integer> | <float> | <time> | <string> |
+ * <bitfield> | <opaque> | <reference> | <enum>
+ * <integer> ::= H5T_STD_I8BE | H5T_STD_I8LE |
+ * H5T_STD_I16BE | H5T_STD_I16LE |
+ * H5T_STD_I32BE | H5T_STD_I32LE |
+ * H5T_STD_I64BE | H5T_STD_I64LE |
+ * H5T_STD_U8BE | H5T_STD_U8LE |
+ * H5T_STD_U16BE | H5T_STD_U16LE |
+ * H5T_STD_U32BE | H5T_STD_U32LE |
+ * H5T_STD_U64BE | H5T_STD_U64LE |
+ * H5T_NATIVE_CHAR | H5T_NATIVE_UCHAR |
+ * H5T_NATIVE_SHORT | H5T_NATIVE_USHORT |
+ * H5T_NATIVE_INT | H5T_NATIVE_UINT |
+ * H5T_NATIVE_LONG | H5T_NATIVE_ULONG |
+ * H5T_NATIVE_LLONG | H5T_NATIVE_ULLONG
+ * <float> ::= H5T_IEEE_F32BE | H5T_IEEE_F32LE |
+ * H5T_IEEE_F64BE | H5T_IEEE_F64LE |
+ * H5T_NATIVE_FLOAT | H5T_NATIVE_DOUBLE |
+ * H5T_NATIVE_LDOUBLE
+ * <time> ::= H5T_TIME: not yet implemented
+ * <string> ::= H5T_STRING {
+ * STRSIZE <strsize> ;
+ * STRPAD <strpad> ;
+ * CSET <cset> ;
+ * CTYPE <ctype> ;
+ * }
+ * <strsize> ::= <int_value>
+ * <strpad> ::= H5T_STR_NULLTERM | H5T_STR_NULLPAD | H5T_STR_SPACEPAD
+ * <cset> ::= H5T_CSET_ASCII | H5T_CSET_UTF8
+ * <ctype> ::= H5T_C_S1 | H5T_FORTRAN_S1
+ *
+ * <bitfield> ::= H5T_STD_B8BE | H5T_STD_B8LE |
+ * H5T_STD_B16BE | H5T_STD_B16LE |
+ * H5T_STD_B32BE | H5T_STD_B32LE |
+ * H5T_STD_B64BE | H5T_STD_B64LE
+ *
+ * <opaque> ::= H5T_OPAQUE {
+ * OPAQUE_TAG <identifier>;
+ * OPAQUE_SIZE <int_value>;opt
+ * }
+ *
+ * <reference> ::= H5T_REFERENCE { <ref_type> }
+ * <ref_type> ::= H5T_STD_REF_OBJECT | H5T_STD_REF_DSETREG
+ *
+ * <compound_type> ::= H5T_COMPOUND {
+ * <member_type_def>+
+ * }
+ * <member_type_def> ::= <datatype> <field_name>;
+ * <field_name> ::= <identifier>
+ *
+ * <variable_length_type> ::= H5T_VLEN { <datatype> }
+ *
+ * <array_type> ::= H5T_ARRAY { <dim_sizes> <datatype> }
+ * <dim_sizes> ::= '['<dimsize>']' | '['<dimsize>']'<dim_sizes>
+ * <dimsize> ::= <int_value>
+ *
+ * <enum> ::= H5T_ENUM {
+ * <enum_base_type> <enum_def>+
+ * }
+ * <enum_base_type> ::= <integer>
+ * // Currently enums can only hold integer type data, but they may be expanded
+ * // in the future to hold any datatype
+ * <enum_def> ::= <enum_symbol> <enum_val>;
+ * <enum_symbol> ::= <identifier>
+ * <enum_val> ::= <int_value>
+ * \endcode
+ *
+ * <em> Old definitions of the opaque and compound datatypes</em>
+ * \code
+ * <opaque> ::= H5T_OPAQUE { <identifier> }
+ * <compound_type> ::= H5T_COMPOUND { <member_type_def>+ }
+ * <member_type_def> ::= <datatype> <field_name> ;
+ * <field_name> ::= <identifier>
+ * \endcode
+ *
+ * <h4>Examples</h4>
+ * The code sample below illustrates the use of #H5LTtext_to_dtype to generate a variable-length
+ * string datatype.
+ *
+ * <em>Creating a variable-length string datatype from a text description</em>
+ * \code
+ * hid_t dtype;
+ * if((dtype = H5LTtext_to_dtype(
+ * “H5T_STRING {
+ * STRSIZE H5T_VARIABLE;
+ * STRPAD H5T_STR_NULLPAD;
+ * CSET H5T_CSET_ASCII;
+ * CTYPE H5T_C_S1;
+ * }”, H5LT_DDL)) < 0)
+ * goto out;
+ * \endcode
+ *
+ * The code sample below illustrates the use of #H5LTtext_to_dtype to generate a complex array
+ * datatype.
+ *
+ * <em>Creating a complex array datatype from a text description</em>
+ * \code
+ * hid_t dtype;
+ * if((dtype = H5LTtext_to_dtype(
+ * “H5T_ARRAY { [5][7][13] H5T_ARRAY
+ * { [17][19] H5T_COMPOUND
+ * {
+ * H5T_STD_I8BE \“arr_compound_1\”;
+ * H5T_STD_I32BE \“arr_compound_2\”;
+ * }
+ * }
+ * }”, H5LT_DDL))<0)
+ * goto out;
+ * \endcode
+ *
+ *
+ *
*/
-/**\defgroup H5T H5T Datatypes
+/**
+ * \defgroup H5T H5T Datatypes
*
* Use the functions in this module to manage HDF5 datatypes.
*
diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index 4c3dece..665434c 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -2844,29 +2844,6 @@ H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id);
*/
H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background,
hid_t plist_id);
-/**
- * \ingroup VLEN
- *
- * \brief Reclaims the variable length (VL) datatype memory buffers
- *
- * \type_id
- * \space_id
- * \dxpl_id{plist_id} used to create the buffer
- * \param[in] buf Pointer to the buffer to be reclaimed
- *
- * \return \herr_t
- *
- * \details H5Treclaim() reclaims memory buffers created to store VL datatypes.
- * It only frees the variable length data in the selection defined in
- * the dataspace specified by \p space_id. The dataset transfer
- * property list \p plist_id is required to find the correct
- * allocation and/or free methods for the variable-length data in the
- * buffer.
- *
- * \since 1.12.0
- *
- */
-H5_DLL herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *buf);
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h
index 37d9f70..214c87b 100644
--- a/src/H5Zmodule.h
+++ b/src/H5Zmodule.h
@@ -29,7 +29,8 @@
#define H5_MY_PKG_ERR H5E_PLINE
#define H5_MY_PKG_INIT YES
-/**\defgroup H5Z H5Z Filters
+/**
+ * \defgroup H5Z H5Z Filters
*
* Use the functions in this module to manage HDF5 filters.
*
diff --git a/src/H5module.h b/src/H5module.h
index d335d87..a044eff 100644
--- a/src/H5module.h
+++ b/src/H5module.h
@@ -68,7 +68,8 @@
*
*/
-/**\defgroup H5 H5
+/**
+ * \defgroup H5 H5
*
* Use the functions in this module to manage the life cycle of HDF5 library
* instances.