/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the LICENSE file, which can be found at the root of the source code       *
 * distribution tree, or in https://www.hdfgroup.org/licenses.               *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

#ifndef H5LDpublic_H
#define H5LDpublic_H

#ifdef __cplusplus
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 sec_cltools_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
 *
 */
H5HL_DLL 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 sec_cltools_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
 *
 */
H5HL_DLL 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 multiplying 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 sec_cltools_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
 *
 */
H5HL_DLL herr_t H5LDget_dset_elmts(hid_t did, const hsize_t *prev_dims, const hsize_t *cur_dims,
                                   const char *fields, void *buf);

#ifdef __cplusplus
}
#endif

#endif /* H5LDpublic_H */
