summaryrefslogtreecommitdiffstats
path: root/hl/src/H5LDpublic.h
blob: 363b59cc259f620357aa03e407c5e237897c0d45 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * Copyright by the Board of Trustees of the University of Illinois.         *
 * 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 */