Line data Source code
1 1 : // Distributed under the MIT License.
2 : // See LICENSE.txt for details.
3 :
4 : /// \file
5 : /// Defines functions for h5 manipulations
6 :
7 : #pragma once
8 :
9 : #include <array>
10 : #include <cstddef>
11 : #include <hdf5.h>
12 : #include <string>
13 : #include <vector>
14 :
15 : #include "DataStructures/Index.hpp"
16 :
17 : /// \cond
18 : class DataVector;
19 : /// \endcond
20 :
21 : namespace h5 {
22 : /*!
23 : * \ingroup HDF5Group
24 : * \brief Check if `dtype1` and `dtype2` are the same HDF5 data type.
25 : */
26 1 : bool types_equal(hid_t dtype1, hid_t dtype2);
27 :
28 : /*!
29 : * \ingroup HDF5Group
30 : * \brief Write a std::vector named `name` to the group `group_id`
31 : */
32 : template <typename T>
33 1 : void write_data(hid_t group_id, const std::vector<T>& data,
34 : const std::vector<size_t>& extents,
35 : const std::string& name = "scalar",
36 : const bool overwrite_existing = false);
37 :
38 : /*!
39 : * \ingroup HDF5Group
40 : * \brief Write a DataVector named `name` to the group `group_id`
41 : */
42 1 : void write_data(hid_t group_id, const DataVector& data, const std::string& name,
43 : const bool overwrite_existing = false);
44 :
45 : /*!
46 : * \ingroup HDF5Group
47 : * \brief Write the extents as an attribute named `name` to the group
48 : * `group_id`.
49 : */
50 : template <size_t Dim>
51 1 : void write_extents(hid_t group_id, const Index<Dim>& extents,
52 : const std::string& name = "Extents");
53 :
54 : /*!
55 : * \ingroup HDF5Group
56 : * \brief Write a value of type `Type` to an HDF5 attribute named `name`
57 : */
58 : template <typename Type>
59 1 : void write_to_attribute(hid_t location_id, const std::string& name,
60 : const Type& value);
61 :
62 : /*!
63 : * \ingroup HDF5Group
64 : * \brief Write the vector `data` to the attribute `attribute_name` in the group
65 : * `group_id`.
66 : */
67 : template <typename T>
68 1 : void write_to_attribute(hid_t group_id, const std::string& name,
69 : const std::vector<T>& data);
70 :
71 : /*!
72 : * \ingroup HDF5Group
73 : * \brief Write the `vector<array<fundamental, size>>` `data` to the attribute
74 : * `name` in the group `group_id`.
75 : */
76 : template <typename T, size_t Size>
77 1 : void write_to_attribute(hid_t group_id, const std::string& name,
78 : const std::vector<std::array<T, Size>>& data);
79 :
80 : /*!
81 : * \ingroup HDF5Group
82 : * \brief Read a value of type `Type` from an HDF5 attribute named `name`
83 : */
84 : template <typename Type>
85 1 : Type read_value_attribute(hid_t location_id, const std::string& name);
86 :
87 : /*!
88 : * \ingroup HDF5Group
89 : * \brief Read rank-1 of type `Type` from an HDF5 attribute named `name`
90 : */
91 : template <typename Type>
92 1 : std::vector<Type> read_rank1_attribute(hid_t group_id, const std::string& name);
93 :
94 : /*!
95 : * \ingroup HDF5Group
96 : * \brief Read the `vector<array<fundamental, size>>` from the attribute
97 : * `name` in the group `group_id`.
98 : */
99 : template <typename T, size_t Size>
100 1 : std::vector<std::array<T, Size>> read_rank1_array_attribute(
101 : hid_t group_id, const std::string& name);
102 :
103 : /*!
104 : * \ingroup HDF5Group
105 : * \brief Get the names of all the attributes in a group
106 : */
107 1 : std::vector<std::string> get_attribute_names(hid_t file_id,
108 : const std::string& group_name);
109 :
110 : /*!
111 : * \ingroup HDF5Group
112 : * \brief Write the connectivity into the group in the H5 file
113 : */
114 1 : void write_connectivity(hid_t group_id, const std::vector<int>& connectivity);
115 :
116 : /*!
117 : * \ingroup HDF5Group
118 : * \brief Delete the connectivity from the group in the H5 file
119 : */
120 1 : void delete_connectivity(hid_t group_id);
121 :
122 : /*!
123 : * \ingroup HDF5Group
124 : * \brief Get the names of all the groups and datasets in a group
125 : */
126 1 : std::vector<std::string> get_group_names(hid_t file_id,
127 : const std::string& group_name);
128 :
129 : /*!
130 : * \ingroup HDF5Group
131 : * \brief Check if `name` is a dataset or group in the subgroup `group_name` of
132 : * `id`.
133 : *
134 : * \note To check the current id for `name`, pass `""` as `group_name`.
135 : */
136 1 : bool contains_dataset_or_group(hid_t id, const std::string& group_name,
137 : const std::string& dataset_name);
138 :
139 : /*!
140 : * \ingroup HDF5Group
141 : * \brief Check if an attribute is in a group
142 : */
143 1 : bool contains_attribute(hid_t file_id, const std::string& group_name,
144 : const std::string& attribute_name);
145 :
146 : /*!
147 : * \ingroup HDF5Group
148 : * \brief Open an HDF5 dataset
149 : */
150 1 : hid_t open_dataset(hid_t group_id, const std::string& dataset_name);
151 :
152 : /*!
153 : * \ingroup HDF5Group
154 : * \brief Close an HDF5 dataset
155 : */
156 1 : void close_dataset(hid_t dataset_id);
157 :
158 : /*!
159 : * \ingroup HDF5Group
160 : * \brief Open an HDF5 dataspace
161 : */
162 1 : hid_t open_dataspace(hid_t dataset_id);
163 :
164 : /*!
165 : * \ingroup HDF5Group
166 : * \brief Close an HDF5 dataspace
167 : */
168 1 : void close_dataspace(hid_t dataspace_id);
169 :
170 : /*!
171 : * \ingroup HDF5Group
172 : * \brief Read an array of rank 0-3 into an object.
173 : *
174 : * For each rank, the data can be read into objects of the following types:
175 : * rank 0: double or int
176 : * rank 1: std::vector or DataVector
177 : * rank 2: boost::multiarray or DataVector
178 : * rank 3: boost::multiarray or DataVector
179 : */
180 : template <size_t Rank, typename T>
181 1 : T read_data(hid_t group_id, const std::string& dataset_name);
182 :
183 : /*!
184 : * \ingroup HDF5Group
185 : * \brief Read the HDF5 attribute representing extents from a group
186 : */
187 : template <size_t Dim>
188 1 : Index<Dim> read_extents(hid_t group_id,
189 : const std::string& extents_name = "Extents");
190 : } // namespace h5
191 :
192 : namespace h5 {
193 : namespace detail {
194 : /*!
195 : * \ingroup HDF5Group
196 : * \brief Create a dataset that can be extended/appended to
197 : *
198 : * \requires group_id is an open group, each element of `initial_size` is less
199 : * than the respective element in `max_size`, and each element in `max_size` is
200 : * a positive integer or `H5S_UNLIMITED`
201 : * \effects creates a potentially extensible dataset of dimension Dim inside the
202 : * group `group_id`
203 : * \returns the HDF5 id to the created dataset
204 : *
205 : * See the tutorial at https://support.hdfgroup.org/HDF5/Tutor/extend.html
206 : * for details on the implementation choice.
207 : */
208 : template <size_t Dims>
209 : hid_t create_extensible_dataset(hid_t group_id, const std::string& name,
210 : const std::array<hsize_t, Dims>& initial_size,
211 : const std::array<hsize_t, Dims>& chunk_size,
212 : const std::array<hsize_t, Dims>& max_size);
213 : } // namespace detail
214 : } // namespace h5
|
