source/include/H5LDpublic.h

0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
0002  * Copyright by The HDF Group.                                               *
0003  * All rights reserved.                                                      *
0004  *                                                                           *
0005  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
0006  * terms governing use, modification, and redistribution, is contained in    *
0007  * the COPYING file, which can be found at the root of the source code       *
0008  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
0009  * If you do not have access to either file, you may request a copy from     *
0010  * help@hdfgroup.org.                                                        *
0011  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
0012
0013 #ifndef H5LDpublic_H
0014 #define H5LDpublic_H
0015
0016 #ifdef __cplusplus
0017 extern "C" {
0018 #endif
0019
0020 /**
0021  *-------------------------------------------------------------------------
0022  * \ingroup H5LT
0023  *
0024  * \brief Retrieves the current dimension sizes of a dataset.
0025  *
0026  * \param[in] did       The dataset identifier
0027  * \param[out] cur_dims The current dimension sizes of the dataset
0028  *
0029  * \return \herr_t
0030  *
0031  * \details H5LDget_dset_dims() retrieves the current dimension sizes
0032  *          for the dataset \p did through the parameter \p cur_dims.
0033  *          It will return failure if \p cur_dims is NULL.
0034  *
0035  * \note See Also:
0036  * \note Dataset Watch functions (used with h5watch):
0037  *       - H5LDget_dset_dims()
0038  *       - H5LDget_dset_elmts()
0039  *       - H5LDget_dset_type_size()
0040  *
0041  * \par Example:
0042  * See the example code in H5LDget_dset_elmts() for usage of this routine.
0043  *
0044  * \since 1.10.0
0045  *
0046  */
0047 H5_HLDLL herr_t H5LDget_dset_dims(hid_t did, hsize_t *cur_dims);
0048
0049 /**
0050  *-------------------------------------------------------------------------
0051  * \ingroup H5LT
0052  *
0053  * \brief Returns the size in bytes of the dataset's datatype
0054  *
0055  * \param[in] did       The dataset identifier
0056  * \param[in] fields    The pointer to a comma-separated list of fields for a compound datatype
0057  *
0058  * \return If successful, returns the size in bytes of the
0059  *         dataset's datatype. Otherwise, returns 0.
0060  *
0061  * \details H5LDget_dset_type_size() allows the user to find out the datatype
0062  *          size for the dataset associated with \p did. If the
0063  *          parameter \p fields is NULL, this routine just returns the size
0064  *          of the dataset's datatype. If the dataset has a compound datatype
0065  *          and \p fields is non-NULL, this routine returns the size of the
0066  *          datatype(s) for the selected fields specified in \p fields.
0067  *          Note that ’,’ is the separator for the fields of a compound
0068  *          datatype while ’.’ (dot) is the separator for a nested field.
0069  *          Use a backslash ( \ ) to escape characters in field names that
0070  *          conflict with these two separators.
0071  *
0072  * \note See Also:
0073  * \note Dataset Watch functions (used with h5watch):
0074  *       - H5LDget_dset_dims()
0075  *       - H5LDget_dset_elmts()
0076  *       - H5LDget_dset_type_size()
0077  *
0078  * \par Example:
0079  * See the example code in H5LDget_dset_elmts() for usage of this routine.
0080  *
0081  * \since 1.10.0
0082  *
0083  */
0084 H5_HLDLL size_t H5LDget_dset_type_size(hid_t did, const char *fields);
0085
0086 /**
0087  *-------------------------------------------------------------------------
0088  * \ingroup H5LT
0089  *
0090  * \brief Retrieves selected data from the dataset
0091  *
0092  * \param[in] did       The dataset identifier
0093  * \param[in] prev_dims The previous dimension size of the dataset
0094  * \param[in] cur_dims  The current dimension sizes of the dataset
0095  * \param[in] fields    A string containing a comma-separated list
0096  *                      of fields for a compound datatype
0097  * \param[out] buf      Buffer for storing data retrieved from the
0098  *                      dataset
0099  *
0100  * \return \herr_t
0101  *
0102  * \details H5LDget_dset_dims() retrieves selected data of the dataset
0103  *          \p did and stores the data in the parameter \p buf.
0104  *          The difference between the parameters \p prev_dims and
0105  *          \p cur_dims indicates the dimension sizes of the data to be
0106  *          selected from the dataset. Note that \p cur_dims must have
0107  *          at least one dimension whose size is greater than the
0108  *          corresponding dimension in \p prev_dims. Users can
0109  *          determine the size of buf by multiplying the datatype
0110  *          size of the dataset by the number of selected elements.
0111  *
0112  *          If the parameter \p fields is NULL, this routine returns
0113  *          data for the selected elements of the dataset. If \p fields
0114  *          is not NULL and the dataset has a compound datatype, \p fields
0115  *          is a string containing a comma-separated list of fields.
0116  *          Each name in \p fields specifies a field in the compound
0117  *          datatype, and this routine returns data of the selected fields
0118  *          for the dataset's selected elements. Note that ’,’ is the
0119  *          separator for the fields of a compound datatype while
0120  *          ’.’ is the separator for a nested field. Use backslash to
0121  *          escape characters in field names that conflict with these
0122  *          two separators.
0123  *
0124  * \note See Also:
0125  * \note Dataset Watch functions (used with h5watch):
0126  *       - H5LDget_dset_dims()
0127  *       - H5LDget_dset_elmts()
0128  *       - H5LDget_dset_type_size()
0129  *
0130  * \par Examples:
0131  *
0132  * For the first example, \c DSET1 is a two-dimensional chunked dataset with atomic type defined below:
0133  * \snippet H5LDget_dset_elmts.c first_declare
0134  *
0135  * The following coding sample illustrates the reading of
0136  * data elements appended to the dataset \c DSET1:
0137  * \snippet H5LDget_dset_elmts.c first_reading
0138  *
0139  * The output buffer will contain data elements selected from
0140  * \c DSET1 as follows:
0141  * \snippet H5LDget_dset_elmts.c first_output
0142  *
0143  * For the second example, DSET2 is a one-dimensional chunked dataset
0144  * with compound type defined below:
0145  * \snippet H5LDget_dset_elmts.c second_declare
0146  *
0147  * The following coding sample illustrates the reading of data elements
0148  * appended to the dataset \c DSET2 with compound datatype.
0149  * This example selects only 2 fields: the fourth field \c d and a
0150  * subfield of the sixth field \c s2.c:
0151  * \snippet H5LDget_dset_elmts.c second_reading
0152  *
0153  * The output buffer will contain data for \c d and \c s2.c
0154  * selected from \c DSET2 as follows:
0155  * \snippet H5LDget_dset_elmts.c second_output
0156  *
0157  * \since 1.10.0
0158  *
0159  */
0160 H5_HLDLL herr_t H5LDget_dset_elmts(hid_t did, const hsize_t *prev_dims, const hsize_t *cur_dims,
0161                                    const char *fields, void *buf);
0162
0163 #ifdef __cplusplus
0164 }
0165 #endif
0166
0167 #endif /* H5LDpublic_H */