summaryrefslogtreecommitdiffstats
path: root/hl
diff options
context:
space:
mode:
authorvchoi-hdfgroup <55293060+vchoi-hdfgroup@users.noreply.github.com>2022-07-01 15:42:15 (GMT)
committerGitHub <noreply@github.com>2022-07-01 15:42:15 (GMT)
commit9e97a22b8bb7cc92f0b2ef2b63de61e9da50aba6 (patch)
tree8921d2c772d5616a1251b312663a97f5d0513406 /hl
parent3ed53d17fb018c0415be2d668c6765217deff16f (diff)
downloadhdf5-9e97a22b8bb7cc92f0b2ef2b63de61e9da50aba6.zip
hdf5-9e97a22b8bb7cc92f0b2ef2b63de61e9da50aba6.tar.gz
hdf5-9e97a22b8bb7cc92f0b2ef2b63de61e9da50aba6.tar.bz2
Add doxygen for high level modules. (#1839)
* Add doxygen for high level modules. * Committing clang-format changes * Correct spelling based on spelling check. * Committing clang-format changes Co-authored-by: vchoi <vchoi@jelly.ad.hdfgroup.org> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'hl')
-rw-r--r--hl/src/H5DOpublic.h199
-rw-r--r--hl/src/H5DSpublic.h362
-rw-r--r--hl/src/H5IMpublic.h293
-rw-r--r--hl/src/H5LDpublic.h141
-rw-r--r--hl/src/H5LTpublic.h1398
-rw-r--r--hl/src/H5PTpublic.h416
-rw-r--r--hl/src/H5TBpublic.h539
7 files changed, 3346 insertions, 2 deletions
diff --git a/hl/src/H5DOpublic.h b/hl/src/H5DOpublic.h
index 88616a3..99358b3 100644
--- a/hl/src/H5DOpublic.h
+++ b/hl/src/H5DOpublic.h
@@ -18,6 +18,29 @@
extern "C" {
#endif
+/**\defgroup H5DO Optimizations
+ *
+ * <em>Bypassing default HDF5 behavior in order to optimize for specific
+ * use cases (H5DO)</em>
+ *
+ * HDF5 functions described is this section are implemented in the HDF5 High-level
+ * library as optimized functions. These functions generally require careful setup
+ * and testing as they enable an application to bypass portions of the HDF5
+ * library’s I/O pipeline for performance purposes.
+ *
+ * These functions are distributed in the standard HDF5 distribution and are
+ * available any time the HDF5 High-level library is available.
+ *
+ * - \ref H5DOappend
+ * \n Appends data to a dataset along a specified dimension.
+ * - \ref H5DOread_chunk
+ * \n Reads a raw data chunk directly from a dataset in a file into a buffer (DEPRECATED)
+ * - \ref H5DOwrite_chunk
+ * \n Writes a raw data chunk from a buffer directly to a dataset in a file (DEPRECATED)
+ * .
+ *
+ */
+
/*-------------------------------------------------------------------------
*
* "Optimized dataset" routines.
@@ -25,6 +48,48 @@ extern "C" {
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DO
+ *
+ * \brief Appends data to a dataset along a specified dimension.
+ *
+ * \param[in] dset_id Dataset identifier
+ * \param[in] dxpl_id Dataset transfer property list identifier
+ * \param[in] axis Dataset Dimension (0-based) for the append
+ * \param[in] extension Number of elements to append for the
+ * axis-th dimension
+ * \param[in] memtype The memory datatype identifier
+ * \param[in] buf Buffer with data for the append
+ *
+ * \return \herr_t
+ *
+ * \details The H5DOappend() routine extends a dataset by \p extension
+ * number of elements along a dimension specified by a
+ * dimension \p axis and writes \p buf of elements to the
+ * dataset. Dimension \p axis is 0-based. Elements’ type
+ * is described by \p memtype.
+ *
+ * This routine combines calling H5Dset_extent(),
+ * H5Sselect_hyperslab(), and H5Dwrite() into a single routine
+ * that simplifies application development for the common case
+ * of appending elements to an existing dataset.
+ *
+ * For a multi-dimensional dataset, appending to one dimension
+ * will write a contiguous hyperslab over the other dimensions.
+ * For example, if a 3-D dataset has dimension sizes (3, 5, 8),
+ * extending the 0th dimension (currently of size 3) by 3 will
+ * append 3*5*8 = 120 elements (which must be pointed to by the
+ * \p buffer parameter) to the dataset, making its final
+ * dimension sizes (6, 5, 8).
+ *
+ * If a dataset has more than one unlimited dimension, any of
+ * those dimensions may be appended to, although only along
+ * one dimension per call to H5DOappend().
+ *
+ * \since 1.10.0
+ *
+ */
H5_HLDLL herr_t H5DOappend(hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t extension, hid_t memtype,
const void *buf);
@@ -35,8 +100,142 @@ H5_HLDLL herr_t H5DOappend(hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t e
#ifndef H5_NO_DEPRECATED_SYMBOLS
/* Compatibility wrappers for functionality moved to H5D */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DO
+ *
+ * \brief Writes a raw data chunk from a buffer directly to a dataset in a file.
+ *
+ * \param[in] dset_id Identifier for the dataset to write to
+ * \param[in] dxpl_id Transfer property list identifier for
+ * this I/O operation
+ * \param[in] filters Mask for identifying the filters in use
+ * \param[in] offset Logical position of the chunk’s first element
+ * in the dataspace
+ * \param[in] data_size Size of the actual data to be written in bytes
+ * \param[in] buf Buffer containing data to be written to the chunk
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function was deprecated in favor of the function
+ * H5Dwrite_chunk() of HDF5-1.10.3.
+ * The functionality of H5DOwrite_chunk() was moved
+ * to H5Dwrite_chunk().
+ * \deprecated For compatibility, this API call has been left as a stub which
+ * simply calls H5Dwrite_chunk(). New code should use H5Dwrite_chunk().
+ *
+ * \details The H5DOwrite_chunk() writes a raw data chunk as specified by its
+ * logical \p offset in a chunked dataset \p dset_id from the application
+ * memory buffer \p buf to the dataset in the file. Typically, the data
+ * in \p buf is preprocessed in memory by a custom transformation, such as
+ * compression. The chunk will bypass the library’s internal data
+ * transfer pipeline, including filters, and will be written directly to the file.
+ *
+ * \p dxpl_id is a data transfer property list identifier.
+ *
+ * \p filters is a mask providing a record of which filters are used
+ * with the chunk. The default value of the mask is zero (\c 0),
+ * indicating that all enabled filters are applied. A filter is skipped
+ * if the bit corresponding to the filter’s position in the pipeline
+ * (<tt>0 ≤ position < 32</tt>) is turned on. This mask is saved
+ * with the chunk in the file.
+ *
+ * \p offset is an array specifying the logical position of the first
+ * element of the chunk in the dataset’s dataspace. The length of the
+ * offset array must equal the number of dimensions, or rank, of the
+ * dataspace. The values in \p offset must not exceed the dimension limits
+ * and must specify a point that falls on a dataset chunk boundary.
+ *
+ * \p data_size is the size in bytes of the chunk, representing the number of
+ * bytes to be read from the buffer \p buf. If the data chunk has been
+ * precompressed, \p data_size should be the size of the compressed data.
+ *
+ * \p buf is the memory buffer containing data to be written to the chunk in the file.
+ *
+ * \attention Exercise caution when using H5DOread_chunk() and H5DOwrite_chunk(),
+ * as they read and write data chunks directly in a file.
+ * H5DOwrite_chunk() bypasses hyperslab selection, the conversion of data
+ * from one datatype to another, and the filter pipeline to write the chunk.
+ * Developers should have experience with these processes before
+ * using this function. Please see
+ * <a href="https://portal.hdfgroup.org/display/HDF5/Using+the+Direct+Chunk+Write+Function">
+ * Using the Direct Chunk Write Function</a>
+ * for more information.
+ *
+ * \note H5DOread_chunk() and H5DOwrite_chunk() are not
+ * supported under parallel and do not support variable length types.
+ *
+ * \par Example
+ * The following code illustrates the use of H5DOwrite_chunk to write
+ * an entire dataset, chunk by chunk:
+ * \snippet H5DO_examples.c H5DOwrite
+ *
+ * \version 1.10.3 Function deprecated in favor of H5Dwrite_chunk.
+ *
+ * \since 1.8.11
+ */
H5_HLDLL herr_t H5DOwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, const hsize_t *offset,
size_t data_size, const void *buf);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DO
+ *
+ * \brief Reads a raw data chunk directly from a dataset in a file into a buffer.
+ *
+ * \param[in] dset_id Identifier for the dataset to be read
+ * \param[in] dxpl_id Transfer property list identifier for
+ * this I/O operation
+ * \param[in] offset Logical position of the chunk’s first
+ element in the dataspace
+ * \param[in,out] filters Mask for identifying the filters used
+ * with the chunk
+ * \param[in] buf Buffer containing the chunk read from
+ * the dataset
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function was deprecated in favor of the function
+ * H5Dread_chunk() as of HDF5-1.10.3.
+ * In HDF5 1.10.3, the functionality of H5DOread_chunk()
+ * was moved to H5Dread_chunk().
+ * \deprecated For compatibility, this API call has been left as a stub which
+ * simply calls H5Dread_chunk(). New code should use H5Dread_chunk().
+ *
+ * \details The H5DOread_chunk() reads a raw data chunk as specified
+ * by its logical \p offset in a chunked dataset \p dset_id
+ * from the dataset in the file into the application memory
+ * buffer \p buf. The data in \p buf is read directly from the file
+ * bypassing the library’s internal data transfer pipeline,
+ * including filters.
+ *
+ * \p dxpl_id is a data transfer property list identifier.
+ *
+ * The mask \p filters indicates which filters are used with the
+ * chunk when written. A zero value indicates that all enabled filters
+ * are applied on the chunk. A filter is skipped if the bit corresponding
+ * to the filter’s position in the pipeline
+ * (<tt>0 ≤ position < 32</tt>) is turned on.
+ *
+ * \p offset is an array specifying the logical position of the first
+ * element of the chunk in the dataset’s dataspace. The length of the
+ * offset array must equal the number of dimensions, or rank, of the
+ * dataspace. The values in \p offset must not exceed the dimension
+ * limits and must specify a point that falls on a dataset chunk boundary.
+ *
+ * \p buf is the memory buffer containing the chunk read from the dataset
+ * in the file.
+ *
+ * \par Example
+ * The following code illustrates the use of H5DOread_chunk()
+ * to read a chunk from a dataset:
+ * \snippet H5DO_examples.c H5DOread
+ *
+ * \version 1.10.3 Function deprecated in favor of H5Dread_chunk.
+ *
+ * \since 1.10.2, 1.8.19
+ */
H5_HLDLL herr_t H5DOread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters /*out*/,
void *buf /*out*/);
diff --git a/hl/src/H5DSpublic.h b/hl/src/H5DSpublic.h
index 979a173..1dd0781 100644
--- a/hl/src/H5DSpublic.h
+++ b/hl/src/H5DSpublic.h
@@ -19,33 +19,393 @@
#define REFERENCE_LIST "REFERENCE_LIST"
#define DIMENSION_LABELS "DIMENSION_LABELS"
+/**
+ * \brief Prototype for H5DSiterate_scales() operator
+ *
+ */
+//! <!-- [H5DS_iterate_t_snip] -->
typedef herr_t (*H5DS_iterate_t)(hid_t dset, unsigned dim, hid_t scale, void *visitor_data);
+//! <!-- [H5DS_iterate_t_snip] -->
#ifdef __cplusplus
extern "C" {
#endif
+/**\defgroup H5DS Dimension Scales
+ *
+ * <em>Creating and manipulating HDF5 datasets that are associated with
+ * the dimension of another HDF5 dataset (H5DS)</em>
+ *
+ * \note \Bold{Programming hints:}
+ * \note To use any of these functions or subroutines,
+ * you must first include the relevant include file (C) or
+ * module (Fortran) in your application.
+ * \note The following line includes the HDF5 Dimension Scale package,
+ * H5DS, in C applications:
+ * \code #include "hdf5_hl.h" \endcode
+ * \note This line includes the H5DS module in Fortran applications:
+ * \code use h5ds \endcode
+ *
+ * - \ref H5DSwith_new_ref
+ * \n Determines if new references are used with dimension scales.
+ * - \ref H5DSattach_scale
+ * \n Attach dimension scale dsid to dimension idx of dataset did.
+ * - \ref H5DSdetach_scale
+ * \n Detach dimension scale dsid from the dimension idx of Dataset did.
+ * - \ref H5DSget_label
+ * \n Read the label for dimension idx of did into buffer label.
+ * - \ref H5DSget_num_scales
+ * \n Determines how many Dimension Scales are attached
+ * to dimension idx of did.
+ * - \ref H5DSget_scale_name
+ * \n Retrieves name of scale did into buffer name.
+ * - \ref H5DSis_attached
+ * \n Report if dimension scale dsid is currently attached
+ * to dimension idx of dataset did.
+ * - \ref H5DSis_scale
+ * \n Determines whether dset is a Dimension Scale.
+ * - \ref H5DSiterate_scales
+ * \n Iterates the operation visitor through the scales
+ * attached to dimension dim.
+ * - \ref H5DSset_label
+ * \n Set label for the dimension idx of did to the value label.
+ * - \ref H5DSset_scale
+ * \n Convert dataset dsid to a dimension scale,
+ * with optional name, dimname.
+ * .
+ *
+ */
+
+/* THIS IS A NEW ROUTINE NOT ON OLD PORTAL */
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Determines if new references are used with dimension scales.
+ *
+ * \param[in] obj_id Object identifier
+ * \param[out] with_new_ref New references are used or not
+ *
+ * \return \herr_t
+ *
+ * \details H5DSwith_new_ref() takes any object identifier and checks
+ * if new references are used for dimension scales. Currently,
+ * new references are used when non-native VOL connector is
+ * used or when H5_DIMENSION_SCALES_WITH_NEW_REF is set up
+ * via configure option.
+ *
+ */
H5_HLDLL herr_t H5DSwith_new_ref(hid_t obj_id, hbool_t *with_new_ref);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Attach dimension scale \p dsid to dimension \p idx of
+ * dataset did.
+ *
+ * \param[in] did The dataset
+ * \param[in] dsid The scale to be attached
+ * \param[in] idx The dimension of \p did that \p dsid is associated with
+ *
+ * \return \herr_t
+ *
+ * \details Define Dimension Scale \p dsid to be associated with
+ * dimension \p idx of dataset \p did.
+ *
+ * Entries are created in the #DIMENSION_LIST and
+ * #REFERENCE_LIST attributes, as defined in section 4.2 of
+ * <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf">
+ * HDF5 Dimension Scale Specification</a>.
+ *
+ * Fails if:
+ * - Bad arguments
+ * - If \p dsid is not a Dimension Scale
+ * - If \p did is a Dimension Scale
+ * (A Dimension Scale cannot have scales.)
+ *
+ * \note The Dimension Scale \p dsid can be attached to the
+ * same dimension more than once, which has no effect.
+ */
H5_HLDLL herr_t H5DSattach_scale(hid_t did, hid_t dsid, unsigned int idx);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Detach dimension scale \p dsid from the dimension \p idx of dataset \p did.
+ *
+ * \param[in] did The dataset
+ * \param[in] dsid The scale to be detached
+ * \param[in] idx The dimension of \p did to detach
+ *
+ * \return \herr_t
+ *
+ * \details If possible, deletes association of Dimension Scale \p dsid with
+ * dimension \p idx of dataset \p did. This deletes the entries in the
+ * #DIMENSION_LIST and #REFERENCE_LIST attributes,
+ * as defined in section 4.2 of
+ * <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf">
+ * HDF5 Dimension Scale Specification</a>.
+ *
+ * Fails if:
+ * - Bad arguments
+ * - The dataset \p did or \p dsid do not exist
+ * - The \p dsid is not a Dimension Scale
+ * - \p dsid is not attached to \p did
+ * .
+ *
+ * \note A scale may be associated with more than dimension of the
+ * same dataset. If so, the detach operation only deletes one
+ * of the associations, for \p did.
+ *
+ */
H5_HLDLL herr_t H5DSdetach_scale(hid_t did, hid_t dsid, unsigned int idx);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Convert dataset \p dsid to a dimension scale,
+ * with optional name, \p dimname.
+ *
+ * \param[in] dsid The dataset to be made a Dimemsion Scale
+ * \param[in] dimname The dimension name (optional), NULL if the
+ * dimension has no name.
+ *
+ * \return \herr_t
+ *
+ * \details The dataset \p dsid is converted to a Dimension Scale dataset,
+ * as defined above. Creates the CLASS attribute, set to the value
+ * "DIMENSION_SCALE" and an empty #REFERENCE_LIST attribute,
+ * as described in
+ * <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf">
+ * HDF5 Dimension Scale Specification</a>.
+ * (PDF, see section 4.2).
+ *
+ * If \p dimname is specified, then an attribute called NAME
+ * is created, with the value \p dimname.
+ *
+ * Fails if:
+ * - Bad arguments
+ * - If \p dsid is already a scale
+ * - If \p dsid is a dataset which already has dimension scales
+ * .
+ *
+ * If the dataset was created with the Table, Image, or Palette interface [9],
+ * it is not recommended to convert to a Dimension Scale.
+ * (These Datasets will have a CLASS Table, Image, or Palette.)
+ *
+ * \todo what is [9] after Palette interface?
+ */
H5_HLDLL herr_t H5DSset_scale(hid_t dsid, const char *dimname);
-H5_HLDLL int H5DSget_num_scales(hid_t did, unsigned int dim);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Determines how many Dimension Scales are attached
+ * to dimension \p idx of \p did.
+ *
+ * \param[in] did The dataset to query
+ * \param[in] idx The dimension of \p did to query
+ *
+ * \return Returns the number of Dimension Scales associated
+ * with \p did, if successful, otherwise returns a
+ * negative value.
+ *
+ * \details H5DSget_num_scales() determines how many Dimension
+ * Scales are attached to dimension \p idx of
+ * dataset \p did.
+ *
+ */
+H5_HLDLL int H5DSget_num_scales(hid_t did, unsigned int idx);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Set label for the dimension \p idx of \p did
+ * to the value \p label.
+ *
+ * \param[in] did The dataset
+ * \param[in] idx The dimension
+ * \param[in] label The label
+ *
+ * \return \herr_t
+ *
+ * \details Sets the #DIMENSION_LABELS for dimension \p idx of
+ * dataset \p did. If the dimension had a label,
+ * the new value replaces the old.
+ *
+ * Fails if:
+ * - Bad arguments
+ * .
+ */
H5_HLDLL herr_t H5DSset_label(hid_t did, unsigned int idx, const char *label);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Read the label for dimension \p idx of \p did into buffer \p label.
+ *
+ * \param[in] did The dataset
+ * \param[in] idx The dimension
+ * \param[out] label The label
+ * \param[in] size The length of the label buffer
+ *
+ * \return Upon success, size of label or zero if no label found.
+ * Negative if fail.
+ *
+ * \details Returns the value of the #DIMENSION_LABELS for
+ * dimension \p idx of dataset \p did, if set.
+ * Up to \p size characters of the name are copied into
+ * the buffer \p label. If the label is longer than
+ * \p size, it will be truncated to fit. The parameter
+ * \p size is set to the size of the returned \p label.
+ *
+ * If \p did has no label, the return value of
+ * \p label is NULL.
+ *
+ * Fails if:
+ * - Bad arguments
+ * .
+ */
H5_HLDLL ssize_t H5DSget_label(hid_t did, unsigned int idx, char *label, size_t size);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Retrieves name of scale \p did into buffer \p name.
+ *
+ * \param[in] did Dimension scale identifier
+ * \param[out] name Buffer to contain the returned name
+ * \param[in] size Size in bytes, of the \p name buffer
+ *
+ * \return Upon success, the length of the scale name or zero if no name found.
+ * Negative if fail.
+ *
+ * \details H5DSget_scale_name() retrieves the name attribute
+ * for scale \p did.
+ *
+ * Up to \p size characters of the scale name are returned
+ * in \p name; additional characters, if any, are not returned
+ * to the user application.
+ *
+ * If the length of the name, which determines the required value of
+ * \p size, is unknown, a preliminary H5DSget_scale_name() call can
+ * be made by setting \p name to NULL. The return value of this call
+ * will be the size of the scale name; that value plus one (1) can then
+ * be assigned to \p size for a second H5DSget_scale_name() call,
+ * which will retrieve the actual name. (The value passed in with the
+ * parameter \p size must be one greater than size in bytes of the actual
+ * name in order to accommodate the null terminator;
+ * if \p size is set to the exact size of the name, the last byte
+ * passed back will contain the null terminator and the last character
+ * will be missing from the name passed back to the calling application.)
+ */
H5_HLDLL ssize_t H5DSget_scale_name(hid_t did, char *name, size_t size);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Determines whether \p did is a Dimension Scale.
+ *
+ * \param[in] did The dataset to query
+ *
+ * \return \htri_t
+ *
+ * \details H5DSis_scale() determines if \p did is a Dimension Scale,
+ * i.e., has class="DIMENSION_SCALE").
+ *
+ */
H5_HLDLL htri_t H5DSis_scale(hid_t did);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Iterates the operation visitor through the scales
+ * attached to dimension \p dim.
+ *
+ * \param[in] did The dataset
+ * \param[in] dim The dimension of dataset \p did
+ * \param[in,out] idx Input the index to start iterating,
+ * output the next index to visit.
+ * If NULL, start at the first position.
+ * \param[in] visitor The visitor function
+ * \param[in] visitor_data Arbitrary data to pass to the
+ * visitor function
+ *
+ * \return Returns the return value of the last operator if it was
+ * non-zero, or zero if all scales were processed.
+ *
+ * \details H5DSiterate_scales() iterates over the scales attached to
+ * dimension \p dim of dataset \p did. For each scale in the
+ * list, the \p visitor_data and some additional information,
+ * specified below, are passed to the \p visitor function.
+ * The iteration begins with the \p idx object in the
+ * group and the next element to be processed by the operator
+ * is returned in \p idx. If \p idx is NULL, then the
+ * iterator starts at the first group member; since no
+ * stopping point is returned in this case,
+ * the iterator cannot be restarted if one of the calls
+ * to its operator returns non-zero.
+ *
+ * The prototype for \ref H5DS_iterate_t is:
+ * \snippet this H5DS_iterate_t_snip
+ *
+ * The operation receives the Dimension Scale dataset
+ * identifier, \p scale, and the pointer to the operator
+ * data passed in to H5DSiterate_scales(), \p visitor_data.
+ *
+ * The return values from an operator are:
+ *
+ * - Zero causes the iterator to continue, returning zero
+ * when all group members have been processed.
+ * - Positive causes the iterator to immediately return that
+ * positive value, indicating short-circuit success.
+ * The iterator can be restarted at the next group member.
+ * - Negative causes the iterator to immediately return
+ * that value, indicating failure. The iterator can be
+ * restarted at the next group member.
+ * .
+ *
+ * H5DSiterate_scales() assumes that the scales of the
+ * dimension identified by \p dim remain unchanged through
+ * the iteration. If the membership changes during the iteration,
+ * the function's behavior is undefined.
+ */
H5_HLDLL herr_t H5DSiterate_scales(hid_t did, unsigned int dim, int *idx, H5DS_iterate_t visitor,
void *visitor_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5DS
+ *
+ * \brief Report if dimension scale \p dsid is currently attached to
+ * dimension \p idx of dataset \p did.
+ *
+ * \param[in] did The dataset
+ * \param[in] dsid The scale to be attached
+ * \param[in] idx The dimension of \p did that \p dsid is associated with
+ *
+ * \return \htri_t
+ *
+ * \details Report if dimension scale \p dsid is currently attached to
+ * dimension \p idx of dataset \p did.
+ *
+ * Fails if:
+ * - Bad arguments
+ * - If \p dsid is not a Dimension Scale
+ * - The \p dsid is not a Dimension Scale
+ * - If \p did is a Dimension Scale (A Dimension Scale cannot have scales.)
+ * .
+ *
+ */
H5_HLDLL htri_t H5DSis_attached(hid_t did, hid_t dsid, unsigned int idx);
#ifdef __cplusplus
diff --git a/hl/src/H5IMpublic.h b/hl/src/H5IMpublic.h
index 2843942..2129509 100644
--- a/hl/src/H5IMpublic.h
+++ b/hl/src/H5IMpublic.h
@@ -18,33 +18,326 @@
extern "C" {
#endif
+/**\defgroup H5IM Images
+ *
+ * <em>Creating and manipulating HDF5 datasets intended to be
+ * interpreted as images (H5IM)</em>
+ *
+ * The specification for the Images API is presented in another
+ * document: \ref IMG
+ * This version of the API is primarily concerned with two dimensional raster
+ * data similar to HDF4 Raster Images.
+ * The HDF5 Images API uses the \ref H5LT HDF5 API.
+ *
+ * \note \Bold{Programming hints:}
+ * \note To use any of these functions or subroutines,
+ * you must first include the relevant include file (C) or
+ * module (Fortran) in your application.
+ * \note The following line includes the HDF5 Images package, H5IM,
+ * in C applications:
+ * \code #include "hdf5_hl.h" \endcode
+ * \note This line includes the H5IM module in Fortran applications:
+ * \code use h5im \endcode
+ *
+ * - \ref H5IMget_image_info
+ * \n Gets information about an image dataset (dimensions,
+ * interlace mode and number of associated palettes).
+ * - \ref H5IMget_npalettes
+ * \n Gets the number of palettes associated to an image.
+ * - \ref H5IMget_palette
+ * \n Gets the palette dataset.
+ * - \ref H5IMget_palette_info
+ * \n Gets information about a palette dataset (dimensions).
+ * - \ref H5IMis_image
+ * \n Inquires if a dataset is an image
+ * - \ref H5IMis_palette
+ * \n Inquires if a dataset is a palette.
+ * - \ref H5IMlink_palette
+ * \n Attaches a palette to an image.
+ * - \ref H5IMmake_image_8bit
+ * \n Creates and writes an image.
+ * - \ref H5IMmake_image_24bit
+ * \n Creates and writes a true color image.
+ * - \ref H5IMmake_palette
+ * \n Creates and writes a palette.
+ * - \ref H5IMread_image
+ * \n Reads image data from disk.
+ * - \ref H5IMunlink_palette
+ * \n Dettaches a palette from an image.
+ * .
+ *
+ */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Creates and writes an image.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to create
+ * \param[in] width The width of the image
+ * \param[in] height The height of the image
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMmake_image_8bit() creates and writes a dataset named
+ * \p dset_name attached to the file or group specified by the
+ * identifier \p loc_id. Attributes conforming to the HDF5 Image
+ * and Palette specification for an indexed image are attached to
+ * the dataset, thus identifying it as an image. The image data is
+ * of the type #H5T_NATIVE_UCHAR. An indexed image is an image in
+ * which each each pixel information storage is an index to a
+ * table palette.
+ *
+ */
H5_HLDLL herr_t H5IMmake_image_8bit(hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height,
const unsigned char *buffer);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Creates and writes a true color image.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to create
+ * \param[in] width The width of the image
+ * \param[in] height The height of the image
+ * \param[in] interlace String defining the interlace mode
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMmake_image_24bit() creates and writes a dataset named
+ * \p dset_name attached to the file or group specified by the
+ * identifier \p loc_id. This function defines a true color image
+ * conforming to the HDF5 Image and Palette specification.
+ * The function assumes that the image data is of the type
+ * #H5T_NATIVE_UCHAR.
+ *
+ * A true color image is an image where the pixel storage contains
+ * several color planes. In a 24 bit RGB color model, these planes
+ * are red, green and blue. In a true color image the stream of bytes
+ * can be stored in several different ways, thus defining the
+ * interlace (or interleaving) mode. The 2 most used types of interlace mode
+ * are interlace by pixel and interlace by plane. In the 24 bit RGB color
+ * model example, interlace by plane means all the red components for the
+ * entire dataset are stored first, followed by all the green components,
+ * and then by all the blue components. Interlace by pixel in this example
+ * means that for each pixel the sequence red, green, blue is defined.
+ * In this function, the interlace mode is defined in the parameter
+ * \p interlace, a string that can have the values INTERLACE_PIXEL
+ * or INTERLACE_PLANE.
+ *
+ */
H5_HLDLL herr_t H5IMmake_image_24bit(hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height,
const char *interlace, const unsigned char *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Gets information about an image dataset
+ * (dimensions, interlace mode and number of associated palettes).
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset
+ * \param[out] width The width of the image
+ * \param[out] height The height of the image
+ * \param[out] planes The number of color planes of the image
+ * \param[out] interlace The interlace mode of the image
+ * \param[out] npals The number of palettes associated to the image
+ *
+ * \return \herr_t
+ *
+ * \details H5IMget_image_info() gets information about an image
+ * named \p dset_name attached to the file or group specified
+ * by the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5IMget_image_info(hid_t loc_id, const char *dset_name, hsize_t *width, hsize_t *height,
hsize_t *planes, char *interlace, hssize_t *npals);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Reads image data from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to create
+ * \param[out] buffer Buffer with data to store the image
+ *
+ * \return \herr_t
+ *
+ * \details H5IMread_image() reads a dataset named \p dset_name
+ * attached to the file or group specified by the
+ * identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5IMread_image(hid_t loc_id, const char *dset_name, unsigned char *buffer);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Creates and writes a palette.
+ *
+ * \fg_loc_id
+ * \param[in] pal_name The name of the palette
+ * \param[in] pal_dims An array of the size of the palette dimensions
+ * \param[in] pal_data Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMmake_palette() creates and writes a dataset
+ * named \p pal_name. Attributes conforming to the HDF5 Image and
+ * Palette specification are attached to the dataset, thus
+ * identifying it as a palette. The palette data is of the
+ * type #H5T_NATIVE_UCHAR.
+ *
+ */
H5_HLDLL herr_t H5IMmake_palette(hid_t loc_id, const char *pal_name, const hsize_t *pal_dims,
const unsigned char *pal_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Attaches a palette to an image.
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the dataset to attach the palette to
+ * \param[in] pal_name The name of the palette
+ *
+ * \return \herr_t
+ *
+ * \details H5IMlink_palette() attaches a palette named \p pal_name
+ * to an image specified by \p image_name. The image dataset
+ * may or not already have an attached palette. If it has,
+ * the array of palette references is extended to hold the reference
+ * to the new palette.
+ *
+ */
H5_HLDLL herr_t H5IMlink_palette(hid_t loc_id, const char *image_name, const char *pal_name);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Dettaches a palette from an image.
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the image dataset
+ * \param[in] pal_name The name of the palette
+ *
+ * \return \herr_t
+ *
+ * \details H5IMunlink_palette() dettaches a palette from an image
+ * specified by \p image_name.
+ *
+ */
H5_HLDLL herr_t H5IMunlink_palette(hid_t loc_id, const char *image_name, const char *pal_name);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Gets the number of palettes associated to an image.
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the image dataset
+ * \param[out] npals The number of palettes
+ *
+ * \return \herr_t
+ *
+ * \details H5IMget_npalettes() gets the number of palettes associated to
+ * an image specified by \p image_name.
+ *
+ */
H5_HLDLL herr_t H5IMget_npalettes(hid_t loc_id, const char *image_name, hssize_t *npals);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Gets information about a palette dataset (dimensions).
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the image dataset
+ * \param[in] pal_number The zero based index that identifies
+ * the palette
+ * \param[out] pal_dims The dimensions of the palette dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMget_palette_info() gets the dimensions of the palette
+ * dataset identified by \p pal_number (a zero based index)
+ * associated to an image specified by \p image_name.
+ *
+ */
H5_HLDLL herr_t H5IMget_palette_info(hid_t loc_id, const char *image_name, int pal_number, hsize_t *pal_dims);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Gets the palette dataset.
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the image dataset
+ * \param[in] pal_number The zero based index that identifies
+ * the palette
+ * \param[out] pal_data The palette dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMget_palette() gets the palette dataset identified
+ * by \p pal_number (a zero based index) associated to an
+ * image specified by \p image_name.
+ *
+ */
H5_HLDLL herr_t H5IMget_palette(hid_t loc_id, const char *image_name, int pal_number,
unsigned char *pal_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Inquires if a dataset is an image.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset
+ *
+ * \return \htri_t
+ *
+ * \details H5IMis_image() inquires if a dataset named \p dset_name,
+ * attached to the file or group specified by the identifier
+ * \p loc_id, is an image based on the HDF5 Image and Palette
+ * Specification.
+ *
+ */
H5_HLDLL herr_t H5IMis_image(hid_t loc_id, const char *dset_name);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Inquires if a dataset is a palette
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset
+ *
+ * \return \htri_t
+ *
+ * \details H5IMis_palette() inquires if a dataset named \p dset_name,
+ * attached to the file or group specified by the
+ * identifier \p loc_id, is a palette based on the HDF5
+ * Image and Palette Specification.
+ *
+ */
H5_HLDLL herr_t H5IMis_palette(hid_t loc_id, const char *dset_name);
#ifdef __cplusplus
diff --git a/hl/src/H5LDpublic.h b/hl/src/H5LDpublic.h
index 011b208..826da40 100644
--- a/hl/src/H5LDpublic.h
+++ b/hl/src/H5LDpublic.h
@@ -18,8 +18,149 @@
extern "C" {
#endif
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Retrieves the current dimension sizes of a dataset.
+ *
+ * \param[in] did The dataset identifier
+ * \param[out] cur_dims The current dimension sizes of the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LDget_dset_dims() retrieves the current dimension sizes
+ * for the dataset \p did through the parameter \p cur_dims.
+ * It will return failure if \p cur_dims is NULL.
+ *
+ * \note See Also:
+ * \note Dataset Watch functions (used with \ref h5watch):
+ * - H5LDget_dset_dims()
+ * - H5LDget_dset_elmts()
+ * - H5LDget_dset_type_size()
+ * .
+ *
+ * \par Example:
+ * See the example code in H5LDget_dset_elmts() for usage of this routine.
+ *
+ * \since 1.10.0
+ *
+ */
H5_HLDLL herr_t H5LDget_dset_dims(hid_t did, hsize_t *cur_dims);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Returns the size in bytes of the dataset’s datatype
+ *
+ * \param[in] did The dataset identifier
+ * \param[in] fields The pointer to a comma-separated list of fields for a compound datatype
+ *
+ * \return If successful, returns the size in bytes of the
+ * dataset’s datatype. Otherwise, returns 0.
+ *
+ * \details H5LDget_dset_type_size() allows the user to find out the datatype
+ * size for the dataset associated with \p did. If the
+ * parameter \p fields is NULL, this routine just returns the size
+ * of the dataset’s datatype. If the dataset has a compound datatype
+ * and \p fields is non-NULL, this routine returns the size of the
+ * datatype(s) for the selected fields specified in \p fields.
+ * Note that ’,’ is the separator for the fields of a compound
+ * datatype while ’.’ (dot) is the separator for a nested field.
+ * Use a backslash ( \ ) to escape characters in field names that
+ * conflict with these two separators.
+ *
+ * \note See Also:
+ * \note Dataset Watch functions (used with \ref h5watch):
+ * - H5LDget_dset_dims()
+ * - H5LDget_dset_elmts()
+ * - H5LDget_dset_type_size()
+ * .
+ *
+ * \par Example:
+ * See the example code in H5LDget_dset_elmts() for usage of this routine.
+ *
+ * \since 1.10.0
+ *
+ */
H5_HLDLL size_t H5LDget_dset_type_size(hid_t did, const char *fields);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Retrieves selected data from the dataset
+ *
+ * \param[in] did The dataset identifier
+ * \param[in] prev_dims The previous dimension size of the dataset
+ * \param[in] cur_dims The current dimension sizes of the dataset
+ * \param[in] fields A string containing a comma-separated list
+ * of fields for a compound datatype
+ * \param[out] buf Buffer for storing data retrieved from the
+ * dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LDget_dset_dims() retrieves selected data of the dataset
+ * \p did and stores the data in the parameter \p buf.
+ * The difference between the parameters \p prev_dims and
+ * \p cur_dims indicates the dimension sizes of the data to be
+ * selected from the dataset. Note that \p cur_dims must have
+ * at least one dimension whose size is greater than the
+ * corresponding dimension in \p prev_dims. Users can
+ * determine the size of buf by multipling the datatype
+ * size of the dataset by the number of selected elements.
+ *
+ * If the parameter \p fields is NULL, this routine returns
+ * data for the selected elements of the dataset. If \p fields
+ * is not NULL and the dataset has a compound datatype, \p fields
+ * is a string containing a comma-separated list of fields.
+ * Each name in \p fields specifies a field in the compound
+ * datatype, and this routine returns data of the selected fields
+ * for the dataset's selected elements. Note that ’,’ is the
+ * separator for the fields of a compound datatype while
+ * ’.’ is the separator for a nested field. Use backslash to
+ * escape characters in field names that conflict with these
+ * two separators.
+ *
+ * \note See Also:
+ * \note Dataset Watch functions (used with \ref h5watch):
+ * - H5LDget_dset_dims()
+ * - H5LDget_dset_elmts()
+ * - H5LDget_dset_type_size()
+ * .
+ *
+ * \par Examples:
+ *
+ * For the first example, \c DSET1 is a two-dimensional chunked dataset with atomic type defined below:
+ * \snippet H5LDget_dset_elmts.c first_declare
+ *
+ * The following coding sample illustrates the reading of
+ * data elements appended to the dataset \c DSET1:
+ * \snippet H5LDget_dset_elmts.c first_reading
+ *
+ * The output buffer will contain data elements selected from
+ * \c DSET1 as follows:
+ * \snippet H5LDget_dset_elmts.c first_output
+ *
+ * For the second example, DSET2 is a one-dimensional chunked dataset
+ * with compound type defined below:
+ * \snippet H5LDget_dset_elmts.c second_declare
+ *
+ * The following coding sample illustrates the reading of data elements
+ * appended to the dataset \c DSET2 with compound datatype.
+ * This example selects only 2 fields: the fourth field \c d and a
+ * subfield of the sixth field \c s2.c:
+ * \snippet H5LDget_dset_elmts.c second_reading
+ *
+ * The output buffer will contain data for \c d and \c s2.c
+ * selected from \c DSET2 as follows:
+ * \snippet H5LDget_dset_elmts.c second_output
+ *
+ * \since 1.10.0
+ *
+ */
H5_HLDLL herr_t H5LDget_dset_elmts(hid_t did, const hsize_t *prev_dims, const hsize_t *cur_dims,
const char *fields, void *buf);
diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h
index a6c7c84..2f87944 100644
--- a/hl/src/H5LTpublic.h
+++ b/hl/src/H5LTpublic.h
@@ -35,6 +35,116 @@ typedef enum H5LT_lang_t {
extern "C" {
#endif
+/**\defgroup H5LT Lite
+ * <em>Functions used to simplify creating and manipulating datasets,
+ * attributes and other features (H5LT, H5LD)</em>
+ *
+ * The HDF5 Lite API consists of higher-level functions which do
+ * more operations per call than the basic HDF5 interface.
+ * The purpose is to wrap intuitive functions around certain sets
+ * of features in the existing APIs.
+ * It has the following sets of functions listed below.
+ *
+ * \note \Bold{Programming hints:}
+ * \note To use any of these functions or subroutines,
+ * you must first include the relevant include file (C) or
+ * module (Fortran) in your application.
+ * \note The following line includes the HDF5 Lite package, H5LT,
+ * in C applications:
+ * \code #include "hdf5_hl.h" \endcode
+ * \note This line includes the H5LT module in Fortran applications:
+ * \code use h5lt \endcode
+ *
+ * - Dataset Functions
+ * - Make dataset functions
+ * - \ref H5LTmake_dataset
+ * - \ref H5LTmake_dataset_char
+ * - \ref H5LTmake_dataset_short
+ * - \ref H5LTmake_dataset_int
+ * - \ref H5LTmake_dataset_long
+ * - \ref H5LTmake_dataset_float
+ * - \ref H5LTmake_dataset_double
+ * - \ref H5LTmake_dataset_string
+ * .
+ * - Read dataset functions
+ * - \ref H5LTread_dataset
+ * - \ref H5LTread_dataset_char
+ * - \ref H5LTread_dataset_short
+ * - \ref H5LTread_dataset_int
+ * - \ref H5LTread_dataset_long
+ * - \ref H5LTread_dataset_float
+ * - \ref H5LTread_dataset_double
+ * - \ref H5LTread_dataset_string
+ * .
+ * - Query dataset functions
+ * - \ref H5LTfind_dataset
+ * - \ref H5LTget_dataset_ndims
+ * - \ref H5LTget_dataset_info
+ * .
+ * - Dataset watch functions
+ * - \ref H5LDget_dset_dims
+ * - \ref H5LDget_dset_elmts
+ * - \ref H5LDget_dset_type_size
+ * .
+ * .
+ * - Attribute Functions
+ * - Set attribute functions
+ * - \ref H5LTset_attribute_string
+ * - \ref H5LTset_attribute_char
+ * - \ref H5LTset_attribute_uchar
+ * - \ref H5LTset_attribute_short
+ * - \ref H5LTset_attribute_ushort
+ * - \ref H5LTset_attribute_int
+ * - \ref H5LTset_attribute_uint
+ * - \ref H5LTset_attribute_long
+ * - \ref H5LTset_attribute_long_long
+ * - \ref H5LTset_attribute_ulong
+ * - \ref H5LTset_attribute_ullong
+ * - \ref H5LTset_attribute_float
+ * - \ref H5LTset_attribute_double
+ * - \ref H5LTset_attribute_f (fortran ONLY)
+ * .
+ * - Get attribute functions
+ * - \ref H5LTget_attribute
+ * - \ref H5LTget_attribute_string
+ * - \ref H5LTget_attribute_char
+ * - \ref H5LTget_attribute_uchar
+ * - \ref H5LTget_attribute_short
+ * - \ref H5LTget_attribute_ushort
+ * - \ref H5LTget_attribute_int
+ * - \ref H5LTget_attribute_uint
+ * - \ref H5LTget_attribute_long
+ * - \ref H5LTget_attribute_long_long
+ * - \ref H5LTget_attribute_ulong
+ * - \ref H5LTget_attribute_ullong
+ * - \ref H5LTget_attribute_float
+ * - \ref H5LTget_attribute_double
+ * .
+ * - Query attribute functions
+ * - \ref H5LTfind_attribute
+ * - \ref H5LTget_attribute_info
+ * - \ref H5LTget_attribute_ndims
+ * .
+ * .
+ * - Datatype Functions
+ * - Datatype translation functions
+ * - \ref H5LTtext_to_dtype
+ * - \ref H5LTdtype_to_text
+ * .
+ * .
+ * - File image function
+ * - Open file image function
+ * - \ref H5LTopen_file_image
+ * .
+ * .
+ * - Path and object function
+ * - Query path and object function
+ * - \ref H5LTpath_valid
+ * .
+ * .
+ * .
+ */
+
/*-------------------------------------------------------------------------
*
* Make dataset functions
@@ -42,27 +152,214 @@ extern "C" {
*-------------------------------------------------------------------------
*/
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes a dataset of a type \p type_id.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The Name of the dataset to create
+ * \param[in] rank Number of dimensions of dataspace
+ * \param[in] dims An array of the size of each dimension
+ * \param[in] type_id Identifier of the datatype to use when creating the dataset
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LTmake_dataset() creates and writes a dataset named
+ * \p dset_name attached to the object specified by the
+ * identifier \p loc_id.
+ *
+ * The parameter \p type_id can be any valid HDF5 Prdefined \ref PDTNAT;
+ * For example, setting \p type_id to #H5T_NATIVE_INT will result in a dataset
+ * of <em>signed \e integer datatype</em>.
+ *
+ * \version 1.10.0 Fortran 2003 subroutine added to accept a C address of the data buffer.
+ * \version 1.8.7 Fortran subroutine modified in this release to accommodate arrays
+ * with more than three dimensions.
+ *
+ */
H5_HLDLL herr_t H5LTmake_dataset(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims,
hid_t type_id, const void *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes a dataset.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The Name of the dataset to create
+ * \param[in] rank Number of dimensions of dataspace
+ * \param[in] dims An array of the size of each dimension
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LTmake_dataset_char() creates and writes a dataset
+ * named \p dset_name attached to the object specified by
+ * the identifier \p loc_id.
+ *
+ * The dataset’s datatype will be \e character, #H5T_NATIVE_CHAR.
+ *
+ */
H5_HLDLL herr_t H5LTmake_dataset_char(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims,
const char *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes a dataset.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The Name of the dataset to create
+ * \param[in] rank Number of dimensions of dataspace
+ * \param[in] dims An array of the size of each dimension
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LTmake_dataset_short() creates and writes a dataset
+ * named \p dset_name attached to the object specified by
+ * the identifier \p loc_id.
+ *
+ * The dataset’s datatype will be <em>short signed integer</em>,
+ * #H5T_NATIVE_SHORT.
+ *
+ */
H5_HLDLL herr_t H5LTmake_dataset_short(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims,
const short *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes a dataset.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The Name of the dataset to create
+ * \param[in] rank Number of dimensions of dataspace
+ * \param[in] dims An array of the size of each dimension
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LTmake_dataset_int() creates and writes a dataset
+ * named \p dset_name attached to the object specified by
+ * the identifier \p loc_id.
+ *
+ * The dataset’s datatype will be <em>native signed integer</em>,
+ * #H5T_NATIVE_INT.
+ *
+ * \version Fortran subroutine modified in this release to accommodate
+ * arrays with more than three dimensions.
+ *
+ */
H5_HLDLL herr_t H5LTmake_dataset_int(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims,
const int *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes a dataset.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The Name of the dataset to create
+ * \param[in] rank Number of dimensions of dataspace
+ * \param[in] dims An array of the size of each dimension
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LTmake_dataset_long() creates and writes a dataset
+ * named \p dset_name attached to the object specified by
+ * the identifier \p loc_id.
+ *
+ * The dataset’s datatype will be <em>long signed integer</em>,
+ * #H5T_NATIVE_LONG.
+ *
+ */
H5_HLDLL herr_t H5LTmake_dataset_long(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims,
const long *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes a dataset.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The Name of the dataset to create
+ * \param[in] rank Number of dimensions of dataspace
+ * \param[in] dims An array of the size of each dimension
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LTmake_dataset_float() creates and writes a dataset
+ * named \p dset_name attached to the object specified by
+ * the identifier \p loc_id.
+ *
+ * The dataset’s datatype will be <em>native floating point</em>,
+ * #H5T_NATIVE_FLOAT.
+ *
+ * \version 1.8.7 Fortran subroutine modified in this release to accommodate
+ * arrays with more than three dimensions.
+ *
+ */
H5_HLDLL herr_t H5LTmake_dataset_float(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims,
const float *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes a dataset.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The Name of the dataset to create
+ * \param[in] rank Number of dimensions of dataspace
+ * \param[in] dims An array of the size of each dimension
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LTmake_dataset_double() creates and writes a dataset
+ * named \p dset_name attached to the object specified by
+ * the identifier \p loc_id.
+ *
+ * The dataset’s datatype will be
+ * <em>native floating-point double</em>, #H5T_NATIVE_DOUBLE.
+ *
+ * \version 1.8.7 Fortran subroutine modified in this release to accommodate
+ * arrays with more than three dimensions.
+ *
+ */
H5_HLDLL herr_t H5LTmake_dataset_double(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims,
const double *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes a dataset with string datatype.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to create
+ * \param[in] buf Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LTmake_dataset_string() creates and writes a dataset
+ * named \p dset_name attached to the object specified by
+ * the identifier \p loc_id.
+ *
+ * The dataset’s datatype will be <em>C string</em>, #H5T_C_S1.
+ *
+ */
H5_HLDLL herr_t H5LTmake_dataset_string(hid_t loc_id, const char *dset_name, const char *buf);
/*-------------------------------------------------------------------------
@@ -72,20 +369,169 @@ H5_HLDLL herr_t H5LTmake_dataset_string(hid_t loc_id, const char *dset_name, con
*-------------------------------------------------------------------------
*/
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads a dataset from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[in] type_id Identifier of the datatype to use when reading
+ * the dataset
+ * \param[out] buffer Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_dataset() reads a dataset named \p dset_name
+ * attached to the object specified by the identifier \p loc_id.
+ *
+ * \version 1.10.0 Fortran 2003 subroutine added to accept a C
+ * address of the data buffer.
+ * \version 1.8.7 Fortran subroutine modified in this release to
+ * accommodate arrays with more than three dimensions.
+ *
+ */
H5_HLDLL herr_t H5LTread_dataset(hid_t loc_id, const char *dset_name, hid_t type_id, void *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads a dataset from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[out] buffer Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_dataset_char() reads a dataset named \p dset_name
+ * attached to the object specified by the identifier \p loc_id.
+ * The HDF5 datatype is #H5T_NATIVE_CHAR.
+ *
+ */
H5_HLDLL herr_t H5LTread_dataset_char(hid_t loc_id, const char *dset_name, char *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads a dataset from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[out] buffer Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_dataset_short() reads a dataset named \p dset_name
+ * attached to the object specified by the identifier \p loc_id.
+ * The HDF5 datatype is #H5T_NATIVE_SHORT.
+ *
+ */
H5_HLDLL herr_t H5LTread_dataset_short(hid_t loc_id, const char *dset_name, short *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads a dataset from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[out] buffer Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_dataset_int() reads a dataset named \p dset_name
+ * attached to the object specified by the identifier \p loc_id.
+ * The HDF5 datatype is #H5T_NATIVE_INT.
+ *
+ * \version 1.8.7 Fortran subroutine modified in this release to
+ * accommodate arrays with more than three dimensions.
+ *
+ */
H5_HLDLL herr_t H5LTread_dataset_int(hid_t loc_id, const char *dset_name, int *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads a dataset from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[out] buffer Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_dataset_long() reads a dataset named \p dset_name
+ * attached to the object specified by the identifier \p loc_id.
+ * The HDF5 datatype is #H5T_NATIVE_LONG.
+ *
+ */
H5_HLDLL herr_t H5LTread_dataset_long(hid_t loc_id, const char *dset_name, long *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads a dataset from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[out] buffer Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_dataset_float() reads a dataset named \p dset_name
+ * attached to the object specified by the identifier \p loc_id.
+ * The HDF5 datatype is #H5T_NATIVE_FLOAT.
+ *
+ * \version 1.8.7 Fortran subroutine modified in this release to
+ * accommodate arrays with more than three dimensions.
+ */
H5_HLDLL herr_t H5LTread_dataset_float(hid_t loc_id, const char *dset_name, float *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads a dataset from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[out] buffer Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_dataset_double() reads a dataset named \p dset_name
+ * attached to the object specified by the identifier \p loc_id.
+ * The HDF5 datatype is #H5T_NATIVE_DOUBLE.
+ *
+ * \version 1.8.7 Fortran subroutine modified in this release to
+ * accommodate arrays with more than three dimensions.
+ */
H5_HLDLL herr_t H5LTread_dataset_double(hid_t loc_id, const char *dset_name, double *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads a dataset from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[out] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_dataset_string() reads a dataset named \p dset_name
+ * attached to the object specified by the identifier \p loc_id.
+ * The HDF5 datatype is #H5T_C_S1.
+ *
+ */
H5_HLDLL herr_t H5LTread_dataset_string(hid_t loc_id, const char *dset_name, char *buf);
/*-------------------------------------------------------------------------
@@ -95,11 +541,67 @@ H5_HLDLL herr_t H5LTread_dataset_string(hid_t loc_id, const char *dset_name, cha
*-------------------------------------------------------------------------
*/
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Gets the dimensionality of a dataset
+ *
+ * \param[in] loc_id Identifier of the object to
+ * locate the dataset within
+ * \param[in] dset_name The dataset name
+ * \param[out] rank The dimensionality of the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_dataset_ndims() gets the dimensionality of a dataset
+ * named \p dset_name exists attached to the object \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5LTget_dataset_ndims(hid_t loc_id, const char *dset_name, int *rank);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Retrieves information about a dataset
+ *
+ * \param[in] loc_id Identifier of the object to locate
+ * the dataset within
+ * \param[in] dset_name The dataset name
+ * \param[out] dims The dimensions of the dataset
+ * \param[out] type_class The class identifier. #H5T_class_t is defined in
+ * H5Tpublic.h. See H5Tget_class() for a list
+ * of class types.
+ * \param[out] type_size The size of the datatype in bytes
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_dataset_info() retrieves information about a dataset
+ * named \p dset_name attached to the object \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5LTget_dataset_info(hid_t loc_id, const char *dset_name, hsize_t *dims,
H5T_class_t *type_class, size_t *type_size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Determines whether a dataset exists.
+ *
+ * \param[in] loc_id Identifier of the group containing the dataset
+ * \param[in] name Dataset name
+ *
+ * \return \htri_t
+ *
+ * \details H5LTfind_dataset() determines whether a dataset named
+ * \p name exists in the group specified by \p loc_id.
+ *
+ * \p loc_id must be a group identifier and \p name must
+ * specify a dataset that is a member of that group.
+ *
+ */
H5_HLDLL herr_t H5LTfind_dataset(hid_t loc_id, const char *name);
/*-------------------------------------------------------------------------
@@ -109,42 +611,343 @@ H5_HLDLL herr_t H5LTfind_dataset(hid_t loc_id, const char *name);
*-------------------------------------------------------------------------
*/
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes a string attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] attr_data Buffer with data to be written to the attribute
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_string() creates and writes a string attribute
+ * named \p attr_name and attaches it to the object specified by
+ * the name \p obj_name. If the attribute already exists,
+ * it is overwritten.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_string(hid_t loc_id, const char *obj_name, const char *attr_name,
const char *attr_data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_char() creates and writes a numerical attribute
+ * named \p attr_name and attaches it to the object specified by the
+ * name \p obj_name. The attribute has a dimensionality of 1.
+ * The HDF5 datatype of the attribute is #H5T_NATIVE_CHAR.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_char(hid_t loc_id, const char *obj_name, const char *attr_name,
const char *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_uchar() creates and writes a numerical attribute
+ * named \p attr_name and attaches it to the object specified by the
+ * name \p obj_name. The attribute has a dimensionality of 1.
+ * The HDF5 datatype of the attribute is #H5T_NATIVE_UCHAR.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_uchar(hid_t loc_id, const char *obj_name, const char *attr_name,
const unsigned char *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_short() creates and writes a numerical attribute
+ * named \p attr_name and attaches it to the object specified by the
+ * name \p obj_name. The attribute has a dimensionality of 1.
+ * The HDF5 datatype of the attribute is #H5T_NATIVE_SHORT.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_short(hid_t loc_id, const char *obj_name, const char *attr_name,
const short *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_ushort() creates and writes a numerical attribute
+ * named \p attr_name and attaches it to the object specified by the
+ * name \p obj_name. The attribute has a dimensionality of 1.
+ * The HDF5 datatype of the attribute is #H5T_NATIVE_USHORT.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_ushort(hid_t loc_id, const char *obj_name, const char *attr_name,
const unsigned short *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_int() creates and writes a numerical integer
+ * attribute named \p attr_name and attaches it to the object
+ * specified by the name \p obj_name. The attribute has a
+ * dimensionality of 1. The HDF5 datatype of the attribute
+ * is #H5T_NATIVE_INT.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_int(hid_t loc_id, const char *obj_name, const char *attr_name,
const int *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_uint() creates and writes a numerical integer
+ * attribute named \p attr_name and attaches it to the object specified
+ * by the name \p obj_name. The attribute has a dimensionality of 1.
+ * The HDF5 datatype of the attribute is #H5T_NATIVE_UINT.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_uint(hid_t loc_id, const char *obj_name, const char *attr_name,
const unsigned int *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_long() creates and writes a numerical
+ * attribute named \p attr_name and attaches it to the object
+ * specified by the name \p obj_name. The attribute has a
+ * dimensionality of 1. The HDF5 datatype of the attribute
+ * is #H5T_NATIVE_LONG.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_long(hid_t loc_id, const char *obj_name, const char *attr_name,
const long *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Location of the object to which the attribute
+ * is to be attached
+ * \param[in] obj_name That object's name
+ * \param[in] attr_name Attribute name
+ * \param[in] buffer Attribute value
+ * \param[in] size Attribute size
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_long_long() creates and writes a numerical
+ * attribute named \p attr_name and attaches it to the object
+ * specified by the name \p obj_name.
+ *
+ * The attribute has a dimensionality of 1 and its HDF5 datatype
+ * is #H5T_NATIVE_LLONG.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_long_long(hid_t loc_id, const char *obj_name, const char *attr_name,
const long long *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_ulong() creates and writes a numerical
+ * attribute named \p attr_name and attaches it to the object
+ * specified by the name \p obj_name. The attribute has a
+ * dimensionality of 1. The HDF5 datatype of the attribute
+ * is #H5T_NATIVE_ULONG.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_name,
const unsigned long *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Location of the object to which the attribute
+ * is to be attached
+ * \param[in] obj_name That object's name
+ * \param[in] attr_name Attribute name
+ * \param[in] buffer Attribute value
+ * \param[in] size Attribute size
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_ullong() creates and writes a numerical
+ * attribute named \p attr_name and attaches it to the object
+ * specified by the name \p obj_name.
+ *
+ * The attribute has a dimensionality of 1 and its HDF5 datatype
+ * is #H5T_NATIVE_ULLONG.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name,
const unsigned long long *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_float() creates and writes a numerical
+ * floating point attribute named \p attr_name and attaches
+ * it to the object specified by the name \p obj_name.
+ * The attribute has a dimensionality of 1. The HDF5 datatype
+ * of the attribute is #H5T_NATIVE_FLOAT.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_float(hid_t loc_id, const char *obj_name, const char *attr_name,
const float *buffer, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates and writes an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to create the attribute within
+ * \param[in] obj_name The name of the object to attach the attribute
+ * \param[in] attr_name The attribute name
+ * \param[in] buffer Buffer with data to be written to the attribute
+ * \param[in] size The size of the 1D array (one in the case of a
+ * scalar attribute). This value is used by
+ * H5Screate_simple() to create the dataspace.
+ *
+ * \return \herr_t
+ *
+ * \details H5LTset_attribute_double() creates and writes a numerical
+ * attribute named \p attr_name and attaches
+ * it to the object specified by the name \p obj_name.
+ * The attribute has a dimensionality of 1. The HDF5 datatype
+ * of the attribute is #H5T_NATIVE_DOUBLE.
+ *
+ */
H5_HLDLL herr_t H5LTset_attribute_double(hid_t loc_id, const char *obj_name, const char *attr_name,
const double *buffer, size_t size);
@@ -155,42 +958,337 @@ H5_HLDLL herr_t H5LTset_attribute_double(hid_t loc_id, const char *obj_name, con
*-------------------------------------------------------------------------
*/
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[in] mem_type_id Identifier of the memory datatype
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute() reads an attribute named
+ * \p attr_name with the memory type \p mem_type_id.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute(hid_t loc_id, const char *obj_name, const char *attr_name,
hid_t mem_type_id, void *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_string() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The datatype is a string.
+ *
+ * \version 1.8.9 The content of the buffer returned by the Fortran
+ * subroutine has changed in this release:\n
+ * If the returned buffer requires padding,
+ * h5ltget_attribute_string_f() now employs space
+ * padding; this buffer was previously returned with a C NULL terminator.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_string(hid_t loc_id, const char *obj_name, const char *attr_name,
char *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_char() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The datatype of the attribute
+ * is #H5T_NATIVE_CHAR.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_char(hid_t loc_id, const char *obj_name, const char *attr_name, char *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_uchar() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_UCHAR
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_uchar(hid_t loc_id, const char *obj_name, const char *attr_name,
unsigned char *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_short() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_SHORT
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_short(hid_t loc_id, const char *obj_name, const char *attr_name,
short *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_ushort() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_USHORT.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_ushort(hid_t loc_id, const char *obj_name, const char *attr_name,
unsigned short *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_int() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_INT.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_int(hid_t loc_id, const char *obj_name, const char *attr_name, int *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_uint() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_INT.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_uint(hid_t loc_id, const char *obj_name, const char *attr_name,
unsigned int *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_long() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_LONG.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_long(hid_t loc_id, const char *obj_name, const char *attr_name, long *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads a \e long \e long attribute.
+ *
+ * \param[in] loc_id Location of the object to which
+ * the attribute is attached
+ * \param[in] obj_name That object's name
+ * \param[in] attr_name Attribute name
+ * \param[out] data Attribute value
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_long_long() reads the attribute
+ * specified by \p loc_id and \p obj_name.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_long_long(hid_t loc_id, const char *obj_name, const char *attr_name,
long long *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_ulong() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_ULONG.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_name,
unsigned long *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_ullong() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_ULLONG.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name,
unsigned long long *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_float() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_FLOAT.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_float(hid_t loc_id, const char *obj_name, const char *attr_name,
float *data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Reads an attribute from disk.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] data Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_double() reads an attribute named
+ * \p attr_name that is attached to the object specified
+ * by the name \p obj_name. The HDF5 datatype of the
+ * attribute is #H5T_NATIVE_DOUBLE.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_double(hid_t loc_id, const char *obj_name, const char *attr_name,
double *data);
@@ -201,8 +1299,55 @@ H5_HLDLL herr_t H5LTget_attribute_double(hid_t loc_id, const char *obj_name, con
*-------------------------------------------------------------------------
*/
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Gets the dimensionality of an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] rank The dimensionality of the attribute
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_ndims() gets the dimensionality of an attribute
+ * named \p attr_name that is attached to the object specified
+ * by the name \p obj_name.
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_ndims(hid_t loc_id, const char *obj_name, const char *attr_name, int *rank);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Gets information about an attribute.
+ *
+ * \param[in] loc_id Identifier of the object (dataset or group)
+ * to read the attribute from
+ * \param[in] obj_name The name of the object that the attribute is
+ * attached to
+ * \param[in] attr_name The attribute name
+ * \param[out] dims The dimensions of the attribute
+ * \param[out] type_class The class identifier. #H5T_class_t is
+ * defined in H5Tpublic.h. For a list of valid class
+ * types see: H5Tget_class().
+ * \param[out] type_size The size of the datatype in bytes
+ *
+ * \return \herr_t
+ *
+ * \details H5LTget_attribute_info() gets information about an attribute
+ * named \p attr_name attached to the object specified by
+ * the name \p obj_name.
+ *
+ * \par Example
+ * \snippet H5LT_examples.c get_attribute_info
+ *
+ */
H5_HLDLL herr_t H5LTget_attribute_info(hid_t loc_id, const char *obj_name, const char *attr_name,
hsize_t *dims, H5T_class_t *type_class, size_t *type_size);
@@ -213,7 +1358,74 @@ H5_HLDLL herr_t H5LTget_attribute_info(hid_t loc_id, const char *obj_name, const
*-------------------------------------------------------------------------
*/
-H5_HLDLL hid_t H5LTtext_to_dtype(const char *text, H5LT_lang_t lang_type);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates an HDF5 datatype given a text description.
+ *
+ * \param[in] text A character string containing a DDL
+ * definition of the datatype to be created
+ * \param[in] lang_type The language used to describe the datatype.
+ * The only currently supported language is
+ * #H5LT_DDL.
+ *
+ * \return Returns the datatype identifier(non-negative) if successful;
+ * otherwise returns a negative value.
+ *
+ * \details Given a text description of a datatype, this function creates
+ * an HDF5 datatype and returns the datatype identifier.
+ * The text description of the datatype has to comply with the
+ * \p lang_type definition of HDF5 datatypes.
+ * Currently, only the DDL(#H5LT_DDL) is supported.
+ * The complete DDL definition of HDF5 datatypes can be found in
+ * the last chapter of the
+ * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides">
+ * HDF5 User's Guide</a>.
+ *
+ * \par Example
+ * An example of DDL definition of \c enum type is shown as follows.
+ * \snippet H5LT_examples.c enum
+ *
+ */
+H5_HLDLL hid_t H5LTtext_to_dtype(const char *text, H5LT_lang_t lang_type);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Creates a text description of an HDF5 datatype.
+ *
+ * \param[in] dtype Identifier of the datatype to be converted
+ * \param[out] str Buffer for the text description of the datatype
+ * \param[in] lang_type The language used to describe the datatype.
+ * The currently supported language is #H5LT_DDL.
+ * \param[out] len The size of buffer needed to store the text description
+ *
+ * \return \herr_t
+ *
+ * \details Given an HDF5 datatype identifier, this function creates
+ * a description of this datatype in \p lang_type language format.
+ * A preliminary H5LTdtype_to_text() call can be made to determine
+ * the size of the buffer needed with a NULL passed in for \p str.
+ * This value is returned as \p len. That value can then be assigned
+ * to len for a second H5Ttype_to_text() call, which will
+ * retrieve the actual text description for the datatype.
+ *
+ * If \p len is not big enough for the description, the text
+ * description will be truncated to fit in the buffer.
+ *
+ * Currently only DDL (#H5LT_DDL) is supported for \p lang_type.
+ * The complete DDL definition of HDF5 data types can be found in
+ * the last chapter of the
+ * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides">
+ * HDF5 User's Guide</a>.
+ *
+ * \par Example
+ * An example of DDL definition of \c enum type is shown as follows.
+ * \snippet H5LT_examples.c enum
+ *
+ */
H5_HLDLL herr_t H5LTdtype_to_text(hid_t dtype, char *str, H5LT_lang_t lang_type, size_t *len);
/*-------------------------------------------------------------------------
@@ -223,8 +1435,116 @@ H5_HLDLL herr_t H5LTdtype_to_text(hid_t dtype, char *str, H5LT_lang_t lang_type,
*-------------------------------------------------------------------------
*/
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Determines whether an attribute exists.
+ *
+ * \param[in] loc_id Identifier of the object to which the attribute
+ * is expected to be attached
+ * \param[in] name Attribute name
+ *
+ * \return \htri_t
+ *
+ * \details H5LTfind_attribute() determines whether an attribute named
+ * \p name exists attached to the object specified
+ * by \p loc_id.
+ *
+ * \p loc_id must be an object identifier and \p name
+ * must specify an attribute that is expected to be attached
+ * to that object.
+ *
+ */
H5_HLDLL herr_t H5LTfind_attribute(hid_t loc_id, const char *name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Determines whether an HDF5 path is valid and, optionally,
+ * whether the path resolves to an HDF5 object.
+ *
+ * \param[in] loc_id Identifier of an object in the file
+ * \param[in] path The path to the object to check;
+ * links in \p path may be of any type.
+ * \param[in] check_object_valid If TRUE, determine whether the final
+ * component of \p path resolves to
+ * an object; if FALSE, do not check.
+ *
+ * \return Upon success:
+ * \return If \p check_object_valid is set to \c FALSE:
+ * \return Returns \c TRUE if the path is valid;
+ * otherwise returns \c FALSE.
+ * \return If \p check_object_valid is set to \c TRUE:
+ * \return Returns \c TRUE if the path is valid and
+ * resolves to an HDF5 object;
+ * otherwise returns \c FALSE.
+ *
+ * \return Upon error, returns a negative value.
+ *
+ * \details H5LTpath_valid() checks the validity of \p path relative
+ * to the identifier of an object, \p loc_id. Optionally,
+ * \p check_object_valid can be set to determine whether the
+ * final component of \p path resolves to an HDF5 object;
+ * if not, the final component is a dangling link.
+ *
+ * The meaning of the function’s return value depends on the
+ * value of \p check_object_valid:
+ *
+ * If \p check_object_valid is set to \c FALSE, H5LTpath_valid()
+ * will check all links in \p path to verify that they exist.
+ * If all the links in \p path exist, the function will
+ * return \c TRUE; otherwise the function will return \c FALSE.
+ *
+ * If \p check_object_valid is set to \c TRUE,
+ * H5LTpath_valid() will first check the links in \p path,
+ * as described above. If all the links exist,
+ * \p check_object_valid will then determine whether the final
+ * component of \p path resolves to an actual HDF5 object.
+ * H5LTpath_valid() will return \c TRUE if all the links in
+ * \p path exist and the final component resolves to an
+ * actual object; otherwise, it will return \c FALSE.
+ *
+ * \p path can be any one of the following:
+ *
+ * - An absolute path, which starts with a slash (\c /)
+ * indicating the file’s root group, followed by the members
+ * - A relative path with respect to \p loc_id
+ * - A dot (\c .), if \p loc_id is the object identifier for
+ * the object itself
+ * .
+ *
+ * If \p path is an absolute path, then \p loc_id can be an
+ * identifier for any object in the file as it is used only to
+ * identify the file. If \p path is a relative path, then
+ * \p loc_id must be a file or a group identifier.
+ *
+ * \note
+ * <b>Note on Behavior Change:</b>
+ * The behavior of H5LTpath_valid() was changed in the 1.10.0 release
+ * in the case where the root group, “/”, is the value of path.
+ * This change is described below:
+ * - Let \p loc_id denote a valid HDF5 file identifier, and let
+ * \p check_object_valid be set to true or false.
+ * A call to H5LTpath_valid() with arguments \p loc_id, “/”,
+ * and \p check_object_valid returns a positive value;
+ * in other words, H5LTpath_valid(loc_id, "/", check_object_valid)
+ * returns a positive value.
+ * In HDF5 version 1.8.16, this function returns 0.
+ * - Let ‘root’ denote a valid HDF5 group identifier that refers
+ * to the root group of an HDF5 file, and let \p check_object_valid
+ * be set to true or false.
+ * A call to H5LTpath_valid() with arguments ‘root’, “/”, and
+ * \p check_object_valid returns a positive value;
+ * in other words, H5LTpath_valid(root, "/", check_object_valid)
+ * returns a positive value.
+ * In HDF5 version 1.8.16, this function returns 0.
+ *
+ * \version 1.10.0 Function behavior changed in this release.
+ * See the “Note on Behavior Change” section above.
+ *
+ */
H5_HLDLL htri_t H5LTpath_valid(hid_t loc_id, const char *path, hbool_t check_object_valid);
/*-------------------------------------------------------------------------
@@ -234,6 +1554,82 @@ H5_HLDLL htri_t H5LTpath_valid(hid_t loc_id, const char *path, hbool_t check_obj
*-------------------------------------------------------------------------
*/
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5LT
+ *
+ * \brief Opens an HDF5 file image in memory.
+ *
+ * \param[in] buf_ptr A pointer to the supplied initial image
+ * \param[in] buf_size Size of the supplied buffer
+ * \param[in] flags Flags specifying whether to open the image
+ * read-only or read/write, whether HDF5 is to
+ * take control of the buffer, and instruction
+ * regarding releasing the buffer.
+ *
+ * \return Returns a file identifier if successful;
+ * otherwise returns a negative value.
+ * \warning \Bold{Failure Modes:}
+ * \warning H5LTopen_file_image() will fail if either \p buf_ptr is NULL
+ * or \p buf_size equals 0 (zero).
+ *
+ *
+ * \details H5LTopen_file_image() opens the HDF5 file image that is
+ * located in system memory at the address indicated by
+ * \p buf_ptr of size \p buf_size.
+ * H5LTopen_file_image() opens a file image with the
+ * Core driver, #H5FD_CORE.
+ *
+ * A value of NULL for \p buf_ptr is invalid and will
+ * cause the function to fail.
+ *
+ * A value of 0 for \p buf_size is invalid and will cause
+ * the function to fail.
+ *
+ * The flags passed in \p flags specify whether to open the image
+ * read-only or read/write, whether HDF5 is to take control of the
+ * buffer, and instruction regarding releasing the buffer.
+ * Valid values are:
+ * - #H5LT_FILE_IMAGE_OPEN_RW
+ * - Specifies opening the file image in read/write mode.
+ * - Default without this flag: File image will be opened read-only.
+ * .
+ * - #H5LT_FILE_IMAGE_DONT_COPY
+ * - Specifies to not copy the provided file image buffer;
+ * the buffer will be used directly. HDF5 will release the
+ * file image when finished.
+ * - Default without this flag: Copy the file image buffer and
+ * open the copied file image.
+ * .
+ * - #H5LT_FILE_IMAGE_DONT_RELEASE
+ * - Specifies that HDF5 is not to release the buffer when
+ * the file opened with H5LTopen_file_image() is closed;
+ * releasing the buffer will be left to the application.
+ * - Default without this flag: HDF5 will automatically
+ * release the file image buffer after the file image is
+ * closed. This flag is valid only when used with
+ * #H5LT_FILE_IMAGE_DONT_COPY.
+ * .
+ * .
+ *
+ * \note **Motivation:**
+ * \note H5LTopen_file_image() and other elements of HDF5
+ * are used to load an image of an HDF5 file into system memory
+ * and open that image as a regular HDF5 file. An application can
+ * then use the file without the overhead of disk I/O.
+ *
+ * \note **Recommended Reading:**
+ * \note This function is part of the file image operations feature set.
+ * It is highly recommended to study the guide
+ * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations">
+ * HDF5 File Image Operations</a> before using this feature set.\n
+ * See the “See Also” section below for links to other elements of
+ * HDF5 file image operations.
+ *
+ * \todo There is no "See Also" section???
+ *
+ * \since 1.8.9
+ */
H5_HLDLL hid_t H5LTopen_file_image(void *buf_ptr, size_t buf_size, unsigned flags);
#ifdef __cplusplus
diff --git a/hl/src/H5PTpublic.h b/hl/src/H5PTpublic.h
index d74baa5..b881b25 100644
--- a/hl/src/H5PTpublic.h
+++ b/hl/src/H5PTpublic.h
@@ -18,19 +18,201 @@
extern "C" {
#endif
+/**\defgroup H5PT Packet Table
+ *
+ * <em>Creating and manipulating HDF5 datasets to support append-
+ * and read-only operations on table data (H5PT)</em>
+ *
+ * The HDF5 Packet Table API is designed to allow records to be
+ * appended to and read from a table. Packet Table datasets are
+ * chunked, allowing them to grow as needed.
+ *
+ * The Packet Table API, with the H5PT prefix, is not to be confused with
+ * the H5TB Table API (H5TB prefix). The H5TB APIs are stateless
+ * (H5TB Tables do not need to be opened or closed) but H5PT Packet Tables
+ * require less performance overhead. Also, H5TB Tables support insertions
+ * and deletions, while H5PT Packet Tables support only append operations.
+ * H5TB functions should not be called on tables created with the
+ * H5PT API, or vice versa.
+ *
+ * Packet Tables are datasets in an HDF5 file, so while their contents
+ * should not be changed outside of the H5PT API calls, the datatypes of
+ * Packet Tables can be queried using \ref H5Dget_type.
+ * Packet Tables can also be given attributes using the normal HDF5 APIs.
+ *
+ * \note \Bold{Programming hints:}
+ * \note The following line includes the HDF5 Packet Table package, H5PT,
+ * in C applications:
+ * \code #include "hdf5_hl.h" \endcode
+ * Without this include, an application will not have access to
+ * these functions.
+ *
+ * - \ref H5PTappend
+ * \n Appends packets to the end of a packet table.
+ * - \ref H5PTclose
+ * \n Closes an open packet table.
+ * - \ref H5PTcreate
+ * \n Creates a packet table to store fixed-length
+ * or variable-length packets.
+ * - \ref H5PTcreate_fl
+ * \n Creates a packet table to store fixed-length packets.
+ * - \ref H5PTcreate_index
+ * \n Resets a packet table's index to the first packet.
+ * - \ref H5PTfree_vlen_buff
+ * \n Releases memory allocated in the process of
+ * reading variable-length packets.
+ * - \ref H5PTget_dataset
+ * \n Returns the backend dataset of this packet table.
+ * - \ref H5PTget_index
+ * \n Gets the current record index for a packet table
+ * - \ref H5PTget_next
+ * \n Reads packets from a packet table starting at the
+ * current index.
+ * - \ref H5PTget_num_packets
+ * \n Returns the number of packets in a packet table.
+ * - \ref H5PTget_type
+ * \n Returns the backend datatype of this packet table.
+ * - \ref H5PTis_valid
+ * \n Determines whether an identifier points to a packet table.
+ * - \ref H5PTis_varlen
+ * \n Determines whether a packet table contains variable-length
+ * or fixed-length packets.
+ * - \ref H5PTopen
+ * \n Opens an existing packet table.
+ * - \ref H5PTread_packets
+ * \n Reads a number of packets from a packet table.
+ * - \ref H5PTset_index
+ * \n Sets a packet table's index.
+ * .
+ *
+ */
+
/*-------------------------------------------------------------------------
* Create/Open/Close functions
*-------------------------------------------------------------------------
*/
/* NOTE: H5PTcreate is replacing H5PTcreate_fl for better name due to the
removal of H5PTcreate_vl. H5PTcreate_fl may be retired in 1.8.19. */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Creates a packet table to store fixed-length or
+ * variable-length packets.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the packet table to create
+ * \param[in] dtype_id The datatype of the packet
+ * \param[in] chunk_size The size in number of table entries per chunk
+ * \param[in] plist_id Identifier of the property list. Can be used to
+ * specify the compression of the packet table.
+ *
+ * \return Returns an identifier for the new packet table or
+ * #H5I_INVALID_HID on error.
+ *
+ * \details The H5PTcreate() creates and opens a packet table named
+ * \p dset_name attached to the object specified by the
+ * identifier \p loc_id. The created packet table should be closed
+ * with H5PTclose(), eventually.
+ *
+ * The datatype, \p dtype_id, may specify any datatype, including
+ * variable-length data. If \p dtype_id specifies a compound
+ * datatype, one or more fields in that compound type may be
+ * variable-length.
+ *
+ * \p chunk_size is the size in number of table entries per chunk.
+ * Packet table datasets use HDF5 chunked storage
+ * to allow them to grow. This value allows the user
+ * to set the size of a chunk. The chunk size affects
+ * performance.
+ *
+ * \since 1.10.0 and 1.8.17
+ *
+ */
H5_HLDLL hid_t H5PTcreate(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size,
hid_t plist_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Opens an existing packet table.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the packet table to open
+ *
+ * \return Returns an identifier for the packet table or
+ * #H5I_INVALID_HID on error.
+ *
+ * \details H5PTopen() opens an existing packet table in the file or group
+ * specified by \p loc_id. \p dset_name is the name of the packet
+ * table and is used to identify it in the file. This function is
+ * used to open both fixed-length packet tables and variable-length
+ * packet tables. The packet table should later be closed with
+ * H5PTclose().
+ *
+ */
H5_HLDLL hid_t H5PTopen(hid_t loc_id, const char *dset_name);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Closes an open packet table.
+ *
+ * \param[in] table_id Identifier of packet table to be closed
+ *
+ * \return \herr_t
+ *
+ * \details The H5PTclose() ends access to a packet table specified
+ * by \p table_id.
+ *
+ */
H5_HLDLL herr_t H5PTclose(hid_t table_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Creates a packet table to store fixed-length packets
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to create
+ * \param[in] dtype_id The datatype of a packet.
+ * \param[in] chunk_size The size in number of table entries per
+ * chunk.
+ * \param[in] compression The compression level;
+ * a value of 0 through 9.
+ *
+ * \return Returns an identifier for the packet table or
+ * #H5I_INVALID_HID on error.
+ *
+ * \deprecated This function was deprecated in favor of the function
+ * H5PTcreate().
+ *
+ * \details The H5PTcreate_fl() creates and opens a packet table
+ * named \p dset_name attached to the object specified by
+ * the identifier \p loc_id. It should be closed
+ * with H5PTclose().
+ *
+ * The datatype, \p dtype_id, may specify any datatype,
+ * including variable-length data. If \p dtype_id specifies a
+ * compound datatype, one or more fields in that compound type
+ * may be variable-length.
+ *
+ * \p chunk_size is the size in number of table entries per chunk.
+ * Packet table datasets use HDF5 chunked storage
+ * to allow them to grow. This value allows the user
+ * to set the size of a chunk. The chunk size affects
+ * performance.
+ *
+ * \p compression is the compression level, a value of 0 through 9.
+ * Level 0 is faster but offers the least compression;
+ * level 9 is slower but offers maximum compression.
+ * A setting of -1 indicates that no compression is desired.
+
+ */
/* This function may be removed from the packet table in release 1.8.19. */
H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size,
int compression);
@@ -39,24 +221,148 @@ H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id
* Write functions
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Appends packets to the end of a packet table.
+ *
+ * \param[in] table_id Identifier of packet table to which
+ * packets should be appended
+ * \param[in] nrecords Number of packets to be appended
+ * \param[in] data Buffer holding data to write
+ *
+ * \return \herr_t
+ *
+ * \details The H5PTappend() writes \p nrecords packets to the end of a
+ * packet table specified by \p table_id. \p data is a buffer
+ * containing the data to be written. For a packet table holding
+ * fixed-length packets, this data should be in the packet
+ * table's datatype. For a variable-length packet table,
+ * the data should be in the form of #hvl_t structs.
+ *
+ */
H5_HLDLL herr_t H5PTappend(hid_t table_id, size_t nrecords, const void *data);
/*-------------------------------------------------------------------------
* Read functions
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Reads packets from a packet table starting at the current index.
+ *
+ * \param[in] table_id Identifier of packet table to read from
+ * \param[in] nrecords Number of packets to be read
+ * \param[out] data Buffer into which to read data
+ *
+ * \return \herr_t
+ *
+ * \details The H5PTget_next() reads \p nrecords packets starting with
+ * the "current index" from a packet table specified by \p table_id.
+ * The packet table's index is set and reset with H5PTset_index()
+ * and H5PTcreate_index(). \p data is a buffer into which the
+ * data should be read.
+ *
+ * For a packet table holding variable-length records, the data
+ * returned in the buffer will be in form of a #hvl_t struct
+ * containing the length of the data and a pointer to it in memory.
+ * The memory used by this data must be freed using H5PTfree_vlen_buff().
+ *
+ */
H5_HLDLL herr_t H5PTget_next(hid_t table_id, size_t nrecords, void *data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Reads a number of packets from a packet table.
+ *
+ * \param[in] table_id Identifier of packet table to read from
+ * \param[in] start Packet to start reading from
+ * \param[in] nrecords Number of packets to be read
+ * \param[out] data Buffer into which to read data.
+ *
+ * \return \herr_t
+ *
+ * \details The H5PTread_packets() reads \p nrecords packets starting at
+ * packet number \p start from a packet table specified by
+ * \p table_id. \p data is a buffer into which the data should
+ * be read.
+ *
+ * For a packet table holding variable-length records, the data
+ * returned in the buffer will be in form of #hvl_t structs,
+ * each containing the length of the data and a pointer to it in
+ * memory. The memory used by this data must be freed using
+ * H5PTfree_vlen_buff().
+ *
+ */
H5_HLDLL herr_t H5PTread_packets(hid_t table_id, hsize_t start, size_t nrecords, void *data);
/*-------------------------------------------------------------------------
* Inquiry functions
*-------------------------------------------------------------------------
*/
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Returns the number of packets in a packet table.
+ *
+ * \param[in] table_id Identifier of packet table to query
+ * \param[out] nrecords Number of packets in packet table
+ *
+ * \return \herr_t
+ *
+ * \details The H5PTget_num_packets() returns by reference the number
+ * of packets in a packet table specified by \p table_id.
+ *
+ */
H5_HLDLL herr_t H5PTget_num_packets(hid_t table_id, hsize_t *nrecords);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Determines whether an identifier points to a packet table.
+ *
+ * \param[in] table_id Identifier to query
+ *
+ * \return Returns a non-negative value if \p table_id is
+ * a valid packet table, otherwise returns a negative value.
+ *
+ * \details The H5PTis_valid() returns a non-negative value if
+ * \p table_id corresponds to an open packet table,
+ * and returns a negative value otherwise.
+ *
+ */
H5_HLDLL herr_t H5PTis_valid(hid_t table_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Determines whether a packet table contains
+ * variable-length or fixed-length packets.
+ *
+ * \param[in] table_id Packet table to query
+ *
+ * \return Returns 1 for a variable-length packet table,
+ * 0 for fixed-length, or a negative value on error.
+ *
+ * \details The H5PTis_varlen() returns 1 (TRUE) if \p table_id is
+ * a packet table containing variable-length records.
+ * It returns 0 (FALSE) if \p table_id is a packet table
+ * containing fixed-length records. If \p table_id is not a
+ * packet table, a negative value is returned.
+ *
+ * \version 1.10.0 and 1.8.17 Function re-introduced.
+ * Function had been removed in 1.8.3.
+ *
+ */
H5_HLDLL herr_t H5PTis_varlen(hid_t table_id);
/*-------------------------------------------------------------------------
@@ -66,8 +372,42 @@ H5_HLDLL herr_t H5PTis_varlen(hid_t table_id);
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Returns the backend dataset of this packet table.
+ *
+ * \param[in] table_id Identifier of the packet table
+ *
+ * \return Returns a dataset identifier or H5I_INVALID_HID on error.
+ *
+ * \details The H5PTget_dataset() returns the identifier of the dataset
+ * storing the packet table \p table_id. This dataset identifier
+ * will be closed by H5PTclose().
+ *
+ * \since 1.10.0 and 1.8.17
+ *
+ */
H5_HLDLL hid_t H5PTget_dataset(hid_t table_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Returns the backend datatype of this packet table.
+ *
+ * \param[in] table_id Identifier of the packet table
+ *
+ * \return Returns a datatype identifier or H5I_INVALID_HID on error.
+ *
+ * \details The H5PTget_type() returns the identifier of the datatype
+ * used by the packet table \p table_id. This datatype
+ * identifier will be closed by H5PTclose().
+ *
+ * \since 1.10.0 and 1.8.17
+ *
+ */
H5_HLDLL hid_t H5PTget_type(hid_t table_id);
/*-------------------------------------------------------------------------
@@ -77,10 +417,63 @@ H5_HLDLL hid_t H5PTget_type(hid_t table_id);
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Resets a packet table's index to the first packet.
+ *
+ * \param[in] table_id Identifier of packet table whose index
+ * should be initialized.
+ *
+ * \return \herr_t
+ *
+ * \details Each packet table keeps an index of the "current" packet
+ * so that \c get_next can iterate through the packets in order.
+ * H5PTcreate_index() initializes a packet table's index, and
+ * should be called before using \c get_next. The index must be
+ * initialized every time a packet table is created or opened;
+ * this information is lost when the packet table is closed.
+ *
+ */
H5_HLDLL herr_t H5PTcreate_index(hid_t table_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Sets a packet table's index.
+ *
+ * \param[in] table_id Identifier of packet table whose index is to be set
+ * \param[in] pt_index The packet to which the index should point
+ *
+ * \return \herr_t
+ *
+ * \details Each packet table keeps an index of the "current" packet
+ * so that \c get_next can iterate through the packets in order.
+ * H5PTset_index() sets this index to point to a user-specified
+ * packet (the packets are zero-indexed).
+ *
+ */
H5_HLDLL herr_t H5PTset_index(hid_t table_id, hsize_t pt_index);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Gets the current record index for a packet table.
+ *
+ * \param[in] table_id Table identifier
+ * \param[out] pt_index Current record index
+ *
+ * \return \herr_t
+ *
+ * \details The H5PTget_index() returns the current record index
+ * \p pt_index for the table identified by \p table_id.
+ *
+ * \since 1.8.0
+ *
+ */
H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index);
/*-------------------------------------------------------------------------
@@ -90,6 +483,29 @@ H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index);
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5PT
+ *
+ * \brief Releases memory allocated in the process of reading
+ * variable-length packets.
+ *
+ * \param[in] table_id Packet table whose memory should be freed.
+ * \param[in] bufflen Size of \p buff
+ * \param[in] buff Buffer that was used to read in variable-length
+ * packets
+ *
+ * \return \herr_t
+ *
+ * \details When variable-length packets are read, memory is automatically
+ * allocated to hold them, and must be freed. H5PTfree_vlen_buff()
+ * frees this memory, and should be called whenever packets are
+ * read from a variable-length packet table.
+ *
+ * \version 1.10.0 and 1.8.17 Function re-introduced.
+ * Function had been removed in 1.8.3.
+ *
+ */
H5_HLDLL herr_t H5PTfree_vlen_buff(hid_t table_id, size_t bufflen, void *buff);
#ifdef __cplusplus
diff --git a/hl/src/H5TBpublic.h b/hl/src/H5TBpublic.h
index 1750490..042bf99 100644
--- a/hl/src/H5TBpublic.h
+++ b/hl/src/H5TBpublic.h
@@ -18,6 +18,64 @@
extern "C" {
#endif
+/**\defgroup H5TB Table
+ *
+ * <em>Creating and manipulating HDF5 datasets intended to be
+ * interpreted as tables (H5TB)</em>
+ *
+ * The HDF5 Table API defines a standard storage for HDF5 datasets
+ * that are intended to be interpreted as tables. A table is defined
+ * as a collection of records whose values are stored in fixed-length
+ * fields. All records have the same structure, and all values in
+ * each field have the same data type.
+ *
+ * \note \Bold{Programming hints:}
+ * \note To use any of these functions or subroutines,
+ * you must first include the relevant include file (C) or
+ * module (Fortran) in your application.
+ * \note The following line includes the HDF5 Table package, H5TB,
+ * in C applications:
+ * \code #include "hdf5_hl.h" \endcode
+ * \note To include the H5TB module in Fortran applications specify:
+ * \code use h5tb \endcode
+ * Fortran applications must also include \ref H5open before
+ * any HDF5 calls to initialize global variables and \ref H5close
+ * after all HDF5 calls to close the Fortran interface.
+ *
+ * - Creation
+ * - \ref H5TBmake_table
+ * - Storage
+ * - \ref H5TBappend_records (No Fortran)
+ * - \ref H5TBwrite_records (No Fortran)
+ * - \ref H5TBwrite_fields_name
+ * - \ref H5TBwrite_fields_index
+ * .
+ * - Modification
+ * - \ref H5TBdelete_record (No Fortran)
+ * - \ref H5TBinsert_record (No Fortran)
+ * - \ref H5TBadd_records_from (No Fortran)
+ * - \ref H5TBcombine_tables (No Fortran)
+ * - \ref H5TBinsert_field
+ * - \ref H5TBdelete_field
+ * .
+ * - Retrieval
+ * - \ref H5TBread_table
+ * - \ref H5TBread_records (No Fortran)
+ * - \ref H5TBread_fields_name
+ * - \ref H5TBread_fields_index
+ * .
+ * - Query
+ * - \ref H5TBget_table_info
+ * - \ref H5TBget_field_info
+ * .
+ * - Query Table Attributes
+ * - \ref H5TBAget_fill
+ * - \ref H5TBAget_title
+ * .
+ * .
+ *
+ */
+
/*-------------------------------------------------------------------------
*
* Create functions
@@ -25,6 +83,38 @@ extern "C" {
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ * \brief Creates and writes a table
+ *
+ * \param[in] table_title The title of the table
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to create
+ * \param[in] nfields The number of fields
+ * \param[in] nrecords The number of records
+ * \param[in] type_size The size in bytes of the structure
+ * associated with the table;
+ * This value is obtained with \c sizeof().
+ * \param[in] field_names An array containing the names of
+ * the fields
+ * \param[in] field_offset An array containing the offsets of
+ * the fields
+ * \param[in] field_types An array containing the type of
+ * the fields
+ * \param[in] chunk_size The chunk size
+ * \param[in] fill_data Fill values data
+ * \param[in] compress Flag that turns compression on or off
+ * \param[in] buf Buffer with data to be written to the table
+ *
+ * \return \herr_t
+ *
+ * \details H5TBmake_table() creates and writes a dataset named
+ * \p dset_name attached to the object specified by the
+ * identifier loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBmake_table(const char *table_title, hid_t loc_id, const char *dset_name, hsize_t nfields,
hsize_t nrecords, size_t type_size, const char *field_names[],
const size_t *field_offset, const hid_t *field_types, hsize_t chunk_size,
@@ -37,17 +127,128 @@ H5_HLDLL herr_t H5TBmake_table(const char *table_title, hid_t loc_id, const char
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ * \brief Adds records to the end of the table
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to overwrite
+ * \param[in] nrecords The number of records to append
+ * \param[in] type_size The size of the structure type,
+ * as calculated by \c sizeof().
+ * \param[in] field_offset An array containing the offsets of
+ * the fields. These offsets can be
+ * calculated with the #HOFFSET macro
+ * \param[in] dst_sizes An array containing the sizes of
+ * the fields
+ * \param[in] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBappend_records() adds records to the end of the table
+ * named \p dset_name attached to the object specified by the
+ * identifier \p loc_id. The dataset is extended to hold the
+ * new records.
+ *
+ */
H5_HLDLL herr_t H5TBappend_records(hid_t loc_id, const char *dset_name, hsize_t nrecords, size_t type_size,
const size_t *field_offset, const size_t *dst_sizes, const void *buf);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ * \brief Overwrites records
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to overwrite
+ * \param[in] start The zero index record to start writing
+ * \param[in] nrecords The number of records to write
+ * \param[in] type_size The size of the structure type, as
+ * calculated by \c sizeof().
+ * \param[in] field_offset An array containing the offsets of
+ * the fields. These offsets can be
+ * calculated with the #HOFFSET macro
+ * \param[in] dst_sizes An array containing the sizes of
+ * the fields
+ * \param[in] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBwrite_records() overwrites records starting at the zero
+ * index position start of the table named \p dset_name attached
+ * to the object specified by the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBwrite_records(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords,
size_t type_size, const size_t *field_offset, const size_t *dst_sizes,
const void *buf);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ * \brief Overwrites fields
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to overwrite
+ * \param[in] field_names The names of the fields to write
+ * \param[in] start The zero index record to start writing
+ * \param[in] nrecords The number of records to write
+ * \param[in] type_size The size of the structure type, as
+ * calculated by \c sizeof().
+ * \param[in] field_offset An array containing the offsets of
+ * the fields. These offsets can be
+ * calculated with the #HOFFSET macro
+ * \param[in] dst_sizes An array containing the sizes of
+ * the fields
+ * \param[in] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBwrite_fields_name() overwrites one or several fields
+ * specified by \p field_names with data in \p buf from a
+ * dataset named \p dset_name attached to the object specified
+ * by the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBwrite_fields_name(hid_t loc_id, const char *dset_name, const char *field_names,
hsize_t start, hsize_t nrecords, size_t type_size,
const size_t *field_offset, const size_t *dst_sizes, const void *buf);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ * \brief Overwrites fields
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to overwrite
+ * \param[in] nfields The number of fields to overwrite.
+ * This parameter is also the size of the
+ * \p field_index array.
+ * \param[in] field_index The indexes of the fields to write
+ * \param[in] start The zero based index record to start writing
+ * \param[in] nrecords The number of records to write
+ * \param[in] type_size The size of the structure type, as
+ * calculated by \c sizeof().
+ * \param[in] field_offset An array containing the offsets of
+ * the fields. These offsets can be
+ * calculated with the #HOFFSET macro
+ * \param[in] dst_sizes An array containing the sizes of
+ * the fields
+ * \param[in] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBwrite_fields_index() overwrites one or several fields
+ * specified by \p field_index with a buffer \p buf from a
+ * dataset named \p dset_name attached to the object
+ * specified by the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBwrite_fields_index(hid_t loc_id, const char *dset_name, hsize_t nfields,
const int *field_index, hsize_t start, hsize_t nrecords,
size_t type_size, const size_t *field_offset, const size_t *dst_sizes,
@@ -60,18 +261,128 @@ H5_HLDLL herr_t H5TBwrite_fields_index(hid_t loc_id, const char *dset_name, hsiz
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ * \brief Reads a table
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[in] dst_size The size of the structure type,
+ * as calculated by \c sizeof()
+ * \param[in] dst_offset An array containing the offsets of
+ * the fields. These offsets can be
+ * calculated with the #HOFFSET macro
+ * \param[in] dst_sizes An array containing the sizes of
+ * the fields. These sizes can be
+ * calculated with the sizeof() macro.
+ * \param[in] dst_buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBread_table() reads a table named
+ * \p dset_name attached to the object specified by
+ * the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBread_table(hid_t loc_id, const char *dset_name, size_t dst_size, const size_t *dst_offset,
const size_t *dst_sizes, void *dst_buf);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ * \brief Reads one or several fields. The fields are identified by name.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[in] field_names An array containing the names of the
+ * fields to read
+ * \param[in] start The start record to read from
+ * \param[in] nrecords The number of records to read
+ * \param[in] type_size The size in bytes of the structure associated
+ * with the table
+ * (This value is obtained with \c sizeof().)
+ * \param[in] field_offset An array containing the offsets of the fields
+ * \param[in] dst_sizes An array containing the size in bytes of
+ * the fields
+ * \param[out] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBread_fields_name() reads the fields identified
+ * by \p field_names from a dataset named \p dset_name
+ * attached to the object specified by the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBread_fields_name(hid_t loc_id, const char *dset_name, const char *field_names,
hsize_t start, hsize_t nrecords, size_t type_size,
const size_t *field_offset, const size_t *dst_sizes, void *buf);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Reads one or several fields. The fields are identified by index.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[in] nfields The number of fields to read
+ * (This parameter is also the size of the
+ * \p field_index array.)
+ * fields to read
+ * \param[in] field_index The indexes of the fields to read
+ * \param[in] start The start record to read from
+ * \param[in] nrecords The number of records to read
+ * \param[in] type_size The size in bytes of the structure associated
+ * with the table
+ * (This value is obtained with \c sizeof())
+ * \param[in] field_offset An array containing the offsets of the fields
+ * \param[in] dst_sizes An array containing the size in bytes of
+ * the fields
+ * \param[out] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBread_fields_index() reads the fields identified
+ * by \p field_index from a dataset named \p dset_name attached
+ * to the object specified by the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBread_fields_index(hid_t loc_id, const char *dset_name, hsize_t nfields,
const int *field_index, hsize_t start, hsize_t nrecords,
size_t type_size, const size_t *field_offset, const size_t *dst_sizes,
void *buf);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Reads records
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[in] start The start record to read from
+ * \param[in] nrecords The number of records to read
+ * \param[in] type_size The size of the structure type,
+ * as calculated by \c sizeof()
+ * \param[in] dst_offset An array containing the offsets of the
+ * fields. These offsets can be calculated
+ * with the #HOFFSET macro
+ * \param[in] dst_sizes An array containing the size in bytes of
+ * the fields
+ * \param[out] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBread_records() reads some records identified from a dataset
+ * named \p dset_name attached to the object specified by the
+ * identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBread_records(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords,
size_t type_size, const size_t *dst_offset, const size_t *dst_sizes,
void *buf);
@@ -83,8 +394,52 @@ H5_HLDLL herr_t H5TBread_records(hid_t loc_id, const char *dset_name, hsize_t st
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Gets the table dimensions
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[out] nfields The number of fields
+ * \param[out] nrecords The number of records
+ *
+ * \return \herr_t
+ *
+ * \details H5TBget_table_info() retrieves the table dimensions from a
+ * dataset named \p dset_name attached to the object specified
+ * by the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBget_table_info(hid_t loc_id, const char *dset_name, hsize_t *nfields, hsize_t *nrecords);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Gets information about a table
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to read
+ * \param[out] field_names An array containing the names of the fields
+ * \param[out] field_sizes An array containing the size of the fields
+ * \param[out] field_offsets An array containing the offsets of the fields
+ * \param[out] type_size The size of the HDF5 datatype associated
+ * with the table. (More specifically,
+ * the size in bytes of the HDF5 compound
+ * datatype used to define a row, or record,
+ * in the table)
+ *
+ * \return \herr_t
+ *
+ * \details H5TBget_field_info() gets information about a dataset
+ * named \p dset_name attached to the object specified
+ * by the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBget_field_info(hid_t loc_id, const char *dset_name, char *field_names[],
size_t *field_sizes, size_t *field_offsets, size_t *type_size);
@@ -95,21 +450,162 @@ H5_HLDLL herr_t H5TBget_field_info(hid_t loc_id, const char *dset_name, char *fi
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Delete records
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset
+ * \param[in] start The start record to delete from
+ * \param[in] nrecords The number of records to delete
+ *
+ * \return \herr_t
+ *
+ * \details H5TBdelete_record() deletes nrecords number of records starting
+ * from \p start from the middle of the table \p dset_name
+ * ("pulling up" all the records after it).
+ *
+ */
H5_HLDLL herr_t H5TBdelete_record(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Insert records
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset
+ * \param[in] start The position to insert
+ * \param[in] nrecords The number of records to insert
+ * \param[in] dst_size The size in bytes of the structure
+ * associated with the table
+ * \param[in] dst_offset An array containing the offsets of the
+ * fields
+ * \param[in] dst_sizes An array containing the size in bytes of
+ * the fields
+ * \param[in] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBinsert_record() inserts records into the middle of the table
+ * ("pushing down" all the records after it)
+ *
+ */
H5_HLDLL herr_t H5TBinsert_record(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords,
size_t dst_size, const size_t *dst_offset, const size_t *dst_sizes,
void *buf);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Add records from first table to second table
+ *
+ * \fg_loc_id
+ * \param[in] dset_name1 The name of the dataset to read the records
+ * \param[in] start1 The position to read the records from the
+ * first table
+ * \param[in] nrecords The number of records to read from the first
+ * table
+ * \param[in] dset_name2 The name of the dataset to write the records
+ * \param[in] start2 The position to write the records on the
+ * second table
+ *
+ * \return \herr_t
+ *
+ * \details H5TBadd_records_from() adds records from a dataset named
+ * \p dset_name1 to a dataset named \p dset_name2. Both tables
+ * are attached to the object specified by the identifier loc_id.
+ *
+ */
H5_HLDLL herr_t H5TBadd_records_from(hid_t loc_id, const char *dset_name1, hsize_t start1, hsize_t nrecords,
const char *dset_name2, hsize_t start2);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Combines records from two tables into a third
+ *
+ * \param[in] loc_id1 Identifier of the file or group in which
+ * the first table is located
+ * \param[in] dset_name1 The name of the first table to combine
+ * \param[in] loc_id2 Identifier of the file or group in which
+ * the second table is located
+ * \param[in] dset_name2 The name of the second table to combine
+ * \param[in] dset_name3 The name of the new table
+ *
+ * \return \herr_t
+ *
+ * \details H5TBcombine_tables() combines records from two datasets named
+ * \p dset_name1 and \p dset_name2, to a new table named
+ * \p dset_name3. These tables can be located on different files,
+ * identified by \p loc_id1 and \p loc_id2 (identifiers obtained
+ * with H5Fcreate()). They can also be located on the same file.
+ * In this case one uses the same identifier for both parameters
+ * \p loc_id1 and \p loc_id2. If two files are used, the third
+ * table is written in the first file.
+ *
+ */
H5_HLDLL herr_t H5TBcombine_tables(hid_t loc_id1, const char *dset_name1, hid_t loc_id2,
const char *dset_name2, const char *dset_name3);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Insert a new field into a table
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the table
+ * \param[in] field_name The name of the field to insert
+ * \param[in] field_type The data type of the field
+ * \param[in] position The zero based index position where to
+ * insert the field
+ * \param[in] fill_data Fill value data for the field. This parameter
+ * can be NULL
+ * \param[in] buf Buffer with data
+ *
+ * \return \herr_t
+ *
+ * \details H5TBinsert_field() inserts a new field named \p field_name into
+ * the table \p dset_name. Note: this function requires the table
+ * to be re-created and rewritten in its entirety, and this can result
+ * in some unused space in the file, and can also take a great deal of
+ * time if the table is large.
+ *
+ */
H5_HLDLL herr_t H5TBinsert_field(hid_t loc_id, const char *dset_name, const char *field_name,
hid_t field_type, hsize_t position, const void *fill_data, const void *buf);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Deletes a field from a table
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the table
+ * \param[in] field_name The name of the field to delete
+ *
+ * \return \herr_t
+ *
+ * \details H5TBdelete_field() deletes a field named \p field_name from the
+ * table \p dset_name. Note: this function requires the table to be
+ * re-created and rewritten in its entirety, and this can result in
+ * some unused space in the file, and can also take a great deal of
+ * time if the table is large.
+ *
+ */
H5_HLDLL herr_t H5TBdelete_field(hid_t loc_id, const char *dset_name, const char *field_name);
/*-------------------------------------------------------------------------
@@ -119,8 +615,51 @@ H5_HLDLL herr_t H5TBdelete_field(hid_t loc_id, const char *dset_name, const char
*-------------------------------------------------------------------------
*/
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Reads a table's title
+ *
+ * \fg_loc_id
+ * \param[out] table_title Buffer for title name
+ *
+ * \return \herr_t
+ *
+ * \details H5TBget_title() returns the title of the table identified
+ * by \p loc_id in a buffer \p table_title.
+ *
+ */
H5_HLDLL herr_t H5TBAget_title(hid_t loc_id, char *table_title);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5TB
+ *
+ *
+ * \brief Reads the table attribute fill values
+ *
+ * \fg_loc_id
+ * \param[in] dset_name Name of table
+ * \param[in] dset_id Table identifier
+ * \param[out] dst_buf Buffer of fill values for table fields
+ *
+ * \return
+ * \return A return value of 1 indicates that a fill value is present.
+ * \return A return value of 0 indicates a fill value is not present.
+ * \return A return value <0 indicates an error.
+ *
+ *
+ * \details H5TBget_fill() reads the table attribute fill values into
+ * the buffer \p dst_buf for the table specified by \p dset_id
+ * and \p dset_name located in \p loc_id.
+ *
+ *
+ * \par Example
+ * \include H5TBAget_fill.c
+ *
+ */
H5_HLDLL htri_t H5TBAget_fill(hid_t loc_id, const char *dset_name, hid_t dset_id, unsigned char *dst_buf);
#ifdef __cplusplus