/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 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 COPYING 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 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 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 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 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); #ifdef __cplusplus } #endif #endif /* H5LDpublic_H */