diff options
Diffstat (limited to 'hl/src/H5LDpublic.h')
| -rw-r--r-- | hl/src/H5LDpublic.h | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/hl/src/H5LDpublic.h b/hl/src/H5LDpublic.h index 011b208..e42c8d8 100644 --- a/hl/src/H5LDpublic.h +++ b/hl/src/H5LDpublic.h @@ -18,8 +18,146 @@ 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); |