Templated dataset I/O — h5::create, h5::open, h5::read, h5::write, packet-table streaming (h5::append / h5::flush / h5::reset), and the sparse-matrix CSC group form. Element type T follows the Supported Types dispatch matrix; offset / stride / count / block select hyperslabs; chunking, compression, and access tuning go through the property-list family.
- See also
- H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
◆ create() [1/2]
template<
class T, class... args_t>
creates a dataset within an already opened HDF5 container By default the HDF5 dataset size, the file space, is derived from the passed object properties, or may be explicitly specified with optional properties such as h5::count, h5::current_dims h5::max_dims, h5::stride, h5::block
- Parameters
-
| fd | valid open h5::fd_t file descriptor |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Returns
- open
h5::ds_t dataset descriptor; throws h5::error on failure
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
The following arguments are context sensitive, may be passed in arbitrary order and with the exception of const ref& or const T* object being saved/memory region pointed to, the arguments are optional. By default the arguments are set to sensible values, and in most cases the function call will deliver good performance. With that in mind, the options below provide an easy to use high level fine tuning mechanism to get the best experience without calling HDF5 CAPI functions directly.
current_dims — initial (current) dataset extent When omitted, the system computes the default value as follows h5::block{..} and h5::stride{..} given as: current_dims[i] = count[i] (stride[i] - block[i] + 1) + offset[i] and when only h5::count is available current_dims[i] = count[i] + offset[i] max_dims — maximum dataset extent; use H5S_UNLIMITED to mark an extendable dimension or H5S_UNLIMITED along the dimension intended to be extendable dcpl — dataset creation property list lcpl — link creation property list
example:
h5::create_path | h5::utf8,
h5::chunk{2,3} | h5::fill_value<short>{42} | h5::fletcher32 | h5::shuffle | h5::nbit | h5::gzip{9})
T aread(const hid_t &ds, const std::string &name, const h5::acpl_t &acpl=h5::default_acpl)
Read an attribute by name and return its value as type T.
Definition H5Aread.hpp:76
◆ create() [2/2]
template<
class T, class... args_t>
creates a dataset within an HDF5 container opened with flag H5F_ACC_RDWR By default the HDF5 dataset size, the file space, is derived from the passed object properties, or may be explicitly specified with optional properties such as h5::count, h5::current_dims h5::max_dims, h5::stride, h5::block
- Parameters
-
| file_path | path to the HDF5 container within the OS file system |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Returns
- open
h5::ds_t dataset descriptor; throws h5::error on failure
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
The following arguments are context sensitive, may be passed in arbitrary order and with the exception of const ref& or const T* object being saved/memory region pointed to, the arguments are optional. By default the arguments are set to sensible values, and in most cases the function call will deliver good performance. With that in mind, the options below provide an easy to use high level fine tuning mechanism to get the best experience without calling HDF5 CAPI functions directly.
current_dims — initial (current) dataset extent When omitted, the system computes the default value as follows h5::block{..} and h5::stride{..} given as: current_dims[i] = count[i] (stride[i] - block[i] + 1) + offset[i] and when only h5::count is available current_dims[i] = count[i] + offset[i] max_dims — maximum dataset extent; use H5S_UNLIMITED to mark an extendable dimension or H5S_UNLIMITED along the dimension intended to be extendable dcpl — dataset creation property list lcpl — link creation property list
example:
h5::create_path | h5::utf8,
h5::chunk{2,3} | h5::fill_value<short>{42} | h5::fletcher32 | h5::shuffle | h5::nbit | h5::gzip{9})
◆ read() [1/10]
template<
class T, class... args_t>
Read elements from an open HDF5 dataset into caller-allocated memory.
Low-level raw-pointer overload — caller owns the memory and must supply h5::count{...} so the dispatch knows how many elements to materialise. Optional h5::offset / h5::stride / h5::block select a hyperslab; without them the read covers the whole extent (provided count matches it). For container / value targets use the h5::read(ds, T& ref, ...) overload below, which derives the element count from the destination object.
- Parameters
-
| ds | valid open h5::ds_t dataset descriptor |
| ptr | pointer to a memory region large enough to receive all requested elements |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
- Returns
- void — errors are reported by throwing
h5::error derived exceptions
- Exceptions
-
| h5::error::io::dataset::read | on H5Dread failure (type-conversion error, rank mismatch, invalid hyperslab). |
example:
h5::read(ds, buf.data(), h5::count{10,10});
h5::read(ds, buf.data(), h5::count{4,4}, h5::offset{5,0});
h5::at_t open(const hid_t &parent, const std::string &path, const h5::acpl_t &acpl=h5::default_acpl)
Open an existing attribute by name on a parent HDF5 object.
Definition H5Aopen.hpp:56
std::enable_if_t<!std::is_same_v< T, char ** >, void > read(const h5::ds_t &ds, T *ptr, args_t &&... args)
Read elements from an open HDF5 dataset into caller-allocated memory.
Definition H5Dread.hpp:56
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::open h5::write h5::create Supported Types
- Examples
- collective.cpp, independent.cpp, nested.cpp, smart_ptr.cpp, strings.cpp, throughput.cpp, and tuples_pairs.cpp.
◆ read() [2/10]
template<
class T, class... args_t,
class = std::enable_if_t<arg::tpos<const h5::count_t&, const args_t&...>::present>>
Open a dataset by path and read elements into caller-allocated memory.
Convenience overload — opens the dataset internally then forwards to h5::read(ds, ptr, ...). The dataset handle is closed via RAII before this function returns. Requires an explicit h5::count{...} (SFINAE-gated): a bare read(fd, path, buf) without count does NOT match here and is dispatched to the by-reference overload instead — that path lets char[N] reach the fixed-length-string branch.
- Parameters
-
| fd | valid open h5::fd_t file descriptor |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| ptr | pointer to a memory region large enough to receive all requested elements |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
- Returns
- void — errors are reported by throwing
h5::error derived exceptions
- Exceptions
-
| h5::error::io::dataset::open | if the dataset is not present. |
| h5::error::io::dataset::read | on H5Dread failure. |
example:
h5::count{10,10}, h5::offset{5,0});
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::open h5::write h5::create
◆ read() [3/10]
template<
class T, class... args_t>
Open a file and dataset by path then read into caller-allocated memory.
Convenience overload — opens the file in H5F_ACC_RDWR mode and forwards to h5::read(fd, dataset_path, ptr, ...). Both the file and dataset handles close via RAII before this function returns.
- Parameters
-
| file_path | path to the HDF5 container within the OS file system |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| ptr | pointer to a memory region large enough to receive all requested elements |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
- Returns
- void — errors are reported by throwing
h5::error derived exceptions
- Exceptions
-
| h5::error::io::file::open | if the file cannot be opened. |
| h5::error::io::dataset::open | if the dataset is not present. |
| h5::error::io::dataset::read | on H5Dread failure. |
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::open h5::write
◆ read() [4/10]
template<
class T, class... args_t>
Read into a caller-allocated container or value of type T.
Primary by-reference overload — T is anything the dispatch accepts (see Supported Types): elementary scalar, registered compound POD, fixed or variable-length string, STL container, linear-algebra container, std::tuple / std::pair / std::complex. Element count is derived from ref via access_traits_t<T>::size; passing h5::count{...} here is a compile-time error.
Optional h5::offset / h5::stride / h5::block arguments select a hyperslab from the file space; omitting them reads the whole extent. The on-disk type must be compatible with T — HDF5 has no fixed-length / VLEN string conversion, so a fixed-length string dataset reads into char[N] / std::array<char,N> but not into std::string (and vice versa).
- Parameters
-
| ds | valid open h5::ds_t dataset descriptor |
| ref | reference to a linear algebra object (armadillo, eigen, blitz, blaze, dlib, ublas) or std::vector<T> |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
- Returns
- void — errors are reported by throwing
h5::error derived exceptions
- Exceptions
-
| h5::error::io::dataset::read | on H5Dread failure (type-conversion error, rank mismatch, etc.). |
example:
arma::Mat<double>
mat(10, 10);
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::open h5::write h5::create Supported Types
◆ read() [5/10]
template<
class T, class... args_t,
class = std::enable_if_t<!h5::meta::is_sparse_v<std::decay_t<T>>>>
Open a dataset by path and read into a caller-allocated container or value.
Convenience overload — opens the dataset then forwards to h5::read(ds, ref, ...). For scatter-decomposed types (compiler- emitted via H5CPP_REGISTER_STRUCT with deep nesting) routes through the generated h5::gather<T> specialization instead.
- Parameters
-
| fd | valid open h5::fd_t file descriptor |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| ref | reference to a linear algebra object (armadillo, eigen, blitz, blaze, dlib, ublas) or std::vector<T> |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
- Returns
- void — errors are reported by throwing
h5::error derived exceptions
- Exceptions
-
| h5::error::io::dataset::open | if the dataset is not present. |
| h5::error::io::dataset::read | on H5Dread failure. |
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::open h5::write
◆ read() [6/10]
template<
class T, class... args_t,
class = std::enable_if_t<!h5::meta::is_sparse_v<std::decay_t<T>>>>
Open a file and dataset by path then read into a caller-allocated container.
Convenience overload — opens the file in H5F_ACC_RDWR mode and forwards to h5::read(fd, dataset_path, ref, ...).
- Parameters
-
| file_path | path to the HDF5 container within the OS file system |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| ref | reference to a linear algebra object (armadillo, eigen, blitz, blaze, dlib, ublas) or std::vector<T> |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
- Returns
- void — errors are reported by throwing
h5::error derived exceptions
- Exceptions
-
| h5::error::io::file::open | if the file cannot be opened. |
| h5::error::io::dataset::open | if the dataset is not present. |
| h5::error::io::dataset::read | on H5Dread failure. |
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::open h5::write
◆ read() [7/10]
template<
class T, class... args_t>
Return-by-value read — materialise the dataset as a fresh T.
The most convenient form — T is constructed in-place from the dataset's shape and populated in one call. Use this when you don't already have a target container; use the by-reference overload (h5::read(ds, T& ref, ...)) when you do.
Optional h5::offset / h5::stride / h5::count / h5::block select a hyperslab; omitting them returns the whole extent.
- Parameters
-
| ds | valid open h5::ds_t dataset descriptor |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
- Returns
- fully constructed object of type
T populated with dataset data; throws h5::error on failure
- Exceptions
-
| h5::error::io::dataset::read | on H5Dread failure. |
example:
h5::count{10,10}, h5::offset{5,0});
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::open h5::write h5::create Supported Types
◆ read() [8/10]
template<
class T, class... args_t,
class = std::enable_if_t<!h5::meta::is_sparse_v<std::decay_t<T>>>>
Open a dataset by path and return its contents as a fresh T.
Convenience overload — opens the dataset then forwards to h5::read<T>(ds, ...). Most concise form when both the file and a one-shot read are needed in a single line.
- Parameters
-
| fd | valid open h5::fd_t file descriptor |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
- Returns
- fully constructed object of type
T populated with dataset data; throws h5::error on failure
- Exceptions
-
| h5::error::io::dataset::open | if the dataset is not present. |
| h5::error::io::dataset::read | on H5Dread failure. |
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::open h5::write
◆ read() [9/10]
template<
class T, class... args_t,
class = std::enable_if_t<!h5::meta::is_sparse_v<std::decay_t<T>>>>
Open a file + dataset by path and return contents as a fresh T.
Most concise convenience form — opens the file in H5F_ACC_RDWR mode, opens the dataset, performs the read, and returns the value all in one line. All intermediate handles close via RAII.
- Parameters
-
| file_path | path to the HDF5 container within the OS file system |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
- Returns
- fully constructed object of type
T populated with dataset data; throws h5::error on failure
- Exceptions
-
| h5::error::io::file::open | if the file cannot be opened. |
| h5::error::io::dataset::open | if the dataset is not present. |
| h5::error::io::dataset::read | on H5Dread failure. |
example:
h5::count{10,10}, h5::offset{5,0});
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::open h5::write
◆ write() [1/7]
template<
class T,
class LOC,
class = std::enable_if_t<h5::impl::is_valid_group_parent<LOC>::value && h5::meta::is_sparse_v<T>>>
Write a sparse matrix or vector as a CSC group.
Emits the canonical Compressed Sparse Column layout (see Supported Linear Algebra Types § Sparse storage layout) — a group containing four datasets (data, indices, indptr, shape) plus @format = "csc" and @axis = "column" self-describing attributes. The on-disk file is byte-compatible with scipy.sparse.csc_matrix, Julia HDF5.jl, and the 10x Genomics / Loompy convention.
Index width is fixed uint32 on disk regardless of the upstream library's index type; values exceeding 2^32 - 1 throw h5::error::io::dataset::write at the call site.
SFINAE-gated on is_sparse_v<T> so this overload activates only for sparse types; the dense h5::write(fd, path, ref) path excludes them.
Preconditions (the call does not enforce these implicitly — would require a mutable const &):
arma::SpMat: SpMat::sync() must have completed.Eigen::SparseMatrix: makeCompressed() must have been called, and the matrix must be ColMajor (RowMajor triggers a compile-time static_assert).
- Parameters
-
| parent | open parent handle: h5::fd_t, h5::gr_t, or any handle satisfying is_valid_group_parent<LOC>. |
| path | POSIX-style group path; the group is created. |
| src | sparse source — arma::SpMat / SpRow / SpCol or Eigen::SparseMatrix / SparseVector (ColMajor). |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
| LOC | deduced from the parent argument. |
- Returns
h5::gr_t RAII handle owning the newly created CSC group.
- Exceptions
-
| h5::error::io::dataset::write | on H5Dwrite failure or when nnz / n_rows / n_cols exceeds 2^32 - 1. |
example:
arma::SpMat<double>
A(100, 100);
h5::at_t create(const hid_t &parent, const std::string &path, args_t &&... args)
Create a new attribute of element type T on a parent HDF5 object.
Definition H5Acreate.hpp:100
h5::gr_t write(const LOC &parent, const std::string &path, const T &src)
Write a sparse matrix or vector as a CSC group.
Definition H5Dsparse.hpp:185
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::read Supported Linear Algebra Types
- Examples
- arma.cpp, attributes.cpp, basics.cpp, blaze.cpp, blitz.cpp, collective.cpp, compound.cpp, container.cpp, cout.cpp, datasets.cpp, datatypes.cpp, detected.cpp, dlib.cpp, eigen.cpp, eigen3.cpp, file_per_rank.cpp, independent.cpp, itpp.cpp, maps.cpp, mdspan.cpp, nested.cpp, optimized.cpp, pipeline.cpp, reference.cpp, reflection.cpp, sequences.cpp, sets.cpp, smart_ptr.cpp, string.cpp, strings.cpp, throughput.cpp, transform.cpp, tuples_pairs.cpp, ublas.cpp, and utf.cpp.
◆ read() [10/10]
template<
class T,
class LOC,
class = std::enable_if_t<h5::impl::is_valid_group_parent<LOC>::value && h5::meta::is_sparse_v<T>>>
Read a CSC group back into a sparse matrix or vector of type T.
Counterpart to h5::write(parent, path, sparse_src). Validates @format = "csc" on the group, reads data / indices / indptr / shape, and reconstructs T via its sparse_traits<T>::construct factory.
Sparse vectors are stored as Nx1 / 1xN CSC matrices on disk; reading into arma::SpCol / SpRow / Eigen::SparseVector materialises the single-column form directly. Reading into arma::SpMat / Eigen::SparseMatrix always works because every sparse value is a matrix on disk.
SFINAE-gated on is_sparse_v<T> so this overload activates only for sparse types.
- Parameters
-
| parent | open parent handle holding the CSC group. |
| path | POSIX-style path to the CSC group. |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
| LOC | deduced from the parent argument. |
- Returns
- fully constructed sparse object of type
T.
- Exceptions
-
| h5::error::io::dataset::read | on H5Dread / H5Aread failure, wrong @format, or shape mismatch. |
example:
- See also
- h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
-
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI
-
h5::write Supported Linear Algebra Types
◆ write() [2/7]
write the memory content of const T* ptr with given mem_space into file_space of the dataset
- Parameters
-
| ds | valid open h5::ds_t dataset descriptor |
| mem_space | the dimensions of the memory region being transferred |
| file_space | the dimensions of the target dataset region nelems(mem_space) == nelems(file_space) |
| dxpl | data transfer property list (h5::dxpl_t) |
| ptr | pointer to a memory region large enough to receive all requested elements |
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
◆ write() [3/7]
template<
class T, class... args_t>
writes data, from contiguous memory region into an existing, opened dataset specified byh5::ds_t descriptor Lower level template with generative programming paradigm constructs an optimal function respec to specified arguments
- Parameters
-
| ds | valid open h5::ds_t dataset descriptor |
| ptr | pointer to a memory region large enough to receive all requested elements |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Returns
- open
h5::ds_t dataset descriptor; throws h5::error on failure
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
The following arguments are context sensitive, may be passed in arbitrary order and with the exception of const T* pointing to the memory region being saved, the arguments are optional. By default the arguments are set to sensible values, and in most cases the function call will deliver good performance. With that in mind, the options below provide an easy high level fine tuning mechanism to get the best experience without calling HDF5 CAPI functions directly.
count — number of blocks selected in each dimension; combined with block gives the total selection shape in hyperslab selection; instead from this value the correct slab_count is derived considering the block size whenever applicable with a normalisation step: slab_count[i] = h5::count[i] / h5::block[i] stride — step between selected elements in each dimension; defaults to {1,1,...} (every element) block — size of each selected block in each dimension; defaults to {1,1,...} (single elements) offset — coordinates of the first element selected in file space; one value per dataset dimension (e.g. h5::offset{0,0,0} for rank-3) dcpl — dataset creation property list dxpl — data transfer property list
example:
◆ write() [4/7]
template<
class T, class... args_t,
class = std::enable_if_t<!std::is_pointer_v<std::decay_t<T>> || std::is_array_v<T>>>
writes data within an HDF5 container specified with h5::fd_t descriptor By default the HDF5 dataset size, the file space, is derived from the passed object properties, or may be explicitly specified with optional properties such as h5::count, h5::current_dims h5::max_dims, h5::stride, h5::block
This template specialization acts as a switchboard between objects with contiguous content, such as std::vector<int> and objects where the actual content maybe scattered in memory. In the altter case with the help of h5::gather operator, and O(n) complexity this template builds a vector of pointers to actual content, and delegates it to h5::write<element_t*>(.., ptr**) call.
- Parameters
-
| ds | valid open h5::ds_t dataset descriptor |
| ref | reference to a linear algebra object (armadillo, eigen, blitz, blaze, dlib, ublas) or std::vector<T> |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Returns
- open
h5::ds_t dataset descriptor; throws h5::error on failure
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
The following arguments are context sensitive, may be passed in arbitrary order and with the exception of const ref& object being saved, the arguments are optional. By default the arguments are set to sensible values, and in most cases the function call will deliver good performance. With that in mind, the options below provide an easy high level fine tuning mechanism to get the best experience without calling HDF5 CAPI functions directly.
current_dims — initial (current) dataset extent When omitted, the system computes the default value as follows h5::block{..} and h5::stride{..} given as: current_dims[i] = count[i] (stride[i] - block[i] + 1) + offset[i] and when only h5::count is available current_dims[i] = count[i] + offset[i] max_dims — maximum dataset extent; use H5S_UNLIMITED to mark an extendable dimension or H5S_UNLIMITED along the dimension intended to be extendable count — number of blocks selected in each dimension; combined with block gives the total selection shape in hyperslab selection; instead from this value the correct slab_count is derived considering the block size whenever applicable with a normalisation step: slab_count[i] = h5::count[i] / h5::block[i] stride — step between selected elements in each dimension; defaults to {1,1,...} (every element) block — size of each selected block in each dimension; defaults to {1,1,...} (single elements) offset — coordinates of the first element selected in file space; one value per dataset dimension (e.g. h5::offset{0,0,0} for rank-3) stride — step between selected elements in each dimension; defaults to {1,1,...} (every element) block — size of each selected block in each dimension; defaults to {1,1,...} (single elements) offset — coordinates of the first element selected in file space; one value per dataset dimension (e.g. h5::offset{0,0,0} for rank-3) dcpl — dataset creation property list dxpl — data transfer property list dapl — dataset access property list lcpl — link creation property list
example:
◆ write() [5/7]
writes data within an HDF5 container specified with h5::fd_t descriptor HDF5 dataset may or may not exist, in first case it is opened and in the latter created. The implemantation comes with sensible default arguments, which can be tuned with optional property list. By default the HDF5 dataset size, the file space, is derived from the passed object properties, or may be explicitly specified with optional properties such as h5::count, h5::current_dims h5::max_dims, h5::stride, h5::block
- Parameters
-
| fd | valid open h5::fd_t file descriptor |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| ref | reference to a linear algebra object (armadillo, eigen, blitz, blaze, dlib, ublas) or std::vector<T> |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Returns
- open
h5::ds_t dataset descriptor; throws h5::error on failure
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
The following arguments are context sensitive, may be passed in arbitrary order and with the exception of T object being saved, the arguments are optional. The arguments are set to sensible values, and in most cases will provide good performance by default, with that in mind, it is an easy high level fine tuning mechanism to get the best experience witout trading readability.
current_dims — initial (current) dataset extent When omitted, the system computes the default value as follows h5::block{..} and h5::stride{..} given as: current_dims[i] = count[i] (stride[i] - block[i] + 1) + offset[i] and when only h5::count is available current_dims[i] = count[i] + offset[i] max_dims — maximum dataset extent; use H5S_UNLIMITED to mark an extendable dimension or H5S_UNLIMITED along the dimension intended to be extendable
count — number of blocks selected in each dimension; combined with block gives the total selection shape in hyperslab selection; instead from this value the correct slab_count is derived considering the block size whenever applicable with a normalisation step: slab_count[i] = h5::count[i] / h5::block[i] stride — step between selected elements in each dimension; defaults to {1,1,...} (every element) block — size of each selected block in each dimension; defaults to {1,1,...} (single elements) offset — coordinates of the first element selected in file space; one value per dataset dimension (e.g. h5::offset{0,0,0} for rank-3) dcpl — dataset creation property list dxpl — data transfer property list dapl — dataset access property list lcpl — link creation property list
example:
◆ write() [6/7]
template<
class T, class... args_t,
class = std::enable_if_t<!std::is_pointer_v<std::decay_t<T>> && !h5::meta::is_sparse_v<std::decay_t<T>>>>
writes data within an HDF5 container specified with h5::fd_t descriptor HDF5 dataset may or may not exist, in first case it is opened and in the latter created. The implemantation comes with sensible default arguments, which can be tuned with optional property list. By default the HDF5 dataset size, the file space, is derived from the passed object properties, or may be explicitly specified with optional properties such as h5::count, h5::current_dims h5::max_dims, h5::stride, h5::block
- Parameters
-
| fd | valid open h5::fd_t file descriptor |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| ref | reference to a linear algebra object (armadillo, eigen, blitz, blaze, dlib, ublas) or std::vector<T> |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Returns
- open
h5::ds_t dataset descriptor; throws h5::error on failure
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
The following arguments are context sensitive, may be passed in arbitrary order and with the exception of T object being saved, the arguments are optional. The arguments are set to sensible values, and in most cases will provide good performance by default, with that in mind, it is an easy high level fine tuning mechanism to get the best experience witout trading readability.
current_dims — initial (current) dataset extent When omitted, the system computes the default value as follows h5::block{..} and h5::stride{..} given as: current_dims[i] = count[i] (stride[i] - block[i] + 1) + offset[i] and when only h5::count is available current_dims[i] = count[i] + offset[i] max_dims — maximum dataset extent; use H5S_UNLIMITED to mark an extendable dimension or H5S_UNLIMITED along the dimension intended to be extendable
count — number of blocks selected in each dimension; combined with block gives the total selection shape in hyperslab selection; instead from this value the correct slab_count is derived considering the block size whenever applicable with a normalisation step: slab_count[i] = h5::count[i] / h5::block[i] stride — step between selected elements in each dimension; defaults to {1,1,...} (every element) block — size of each selected block in each dimension; defaults to {1,1,...} (single elements) offset — coordinates of the first element selected in file space; one value per dataset dimension (e.g. h5::offset{0,0,0} for rank-3) dcpl — dataset creation property list dxpl — data transfer property list dapl — dataset access property list lcpl — link creation property list
example:
◆ write() [7/7]
template<class... args_t>
writes content of an object, collection of object or memory location to a possibly not yet existing dataset within an HDF5 container opened with flag H5F_ACC_RDWR By default the HDF5 dataset size, the file space, is derived from the passed object properties, or may be explicitly specified with optional properties such as h5::count, h5::current_dims h5::max_dims, h5::stride, h5::block
- Parameters
-
| file_path | path to the HDF5 container within the OS file system |
| dataset_path | location of the dataset within the HDF5 container (absolute or relative POSIX-style path) |
| args[,...] | comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the rest (offset, stride, count, block, dxpl, current_dims, max_dims, dcpl, lcpl, …) are context-sensitive optionals |
- Returns
- open
h5::ds_t dataset descriptor; throws h5::error on failure
- Template Parameters
-
| T | any of the Supported Types — elementary scalar, string, registered compound, STL container (sequence / associative / array-of), dense or sparse linalg container, mdspan view, or reference handle. Resolves to a storage_representation_t at compile time; the dispatch picks the matching read / write path. |
The following arguments are context sensitive, may be passed in arbitrary order and with the exception of const ref& or const T* object being saved/memory region pointed to, the arguments are optional. By default the arguments are set to sensible values, and in most cases the function call will deliver good performance. With that in mind, the options below provide an easy to use high level fine tuning mechanism to get the best experience without calling HDF5 CAPI functions directly.
current_dims — initial (current) dataset extent When omitted, the system computes the default value as follows h5::block{..} and h5::stride{..} given as: current_dims[i] = count[i] (stride[i] - block[i] + 1) + offset[i] and when only h5::count is available current_dims[i] = count[i] + offset[i] max_dims — maximum dataset extent; use H5S_UNLIMITED to mark an extendable dimension or H5S_UNLIMITED along the dimension intended to be extendable count — number of blocks selected in each dimension; combined with block gives the total selection shape in hyperslab selection; instead from this value the correct slab_count is derived considering the block size whenever applicable with a normalisation step: slab_count[i] = h5::count[i] / h5::block[i] stride — step between selected elements in each dimension; defaults to {1,1,...} (every element) block — size of each selected block in each dimension; defaults to {1,1,...} (single elements) offset — coordinates of the first element selected in file space; one value per dataset dimension (e.g. h5::offset{0,0,0} for rank-3) stride — step between selected elements in each dimension; defaults to {1,1,...} (every element) block — size of each selected block in each dimension; defaults to {1,1,...} (single elements) offset — coordinates of the first element selected in file space; one value per dataset dimension (e.g. h5::offset{0,0,0} for rank-3) dcpl — dataset creation property list dxpl — data transfer property list dapl — dataset access property list lcpl — link creation property list
example:
h5::ds_t ds =
h5::write(
"example.h5",
"path/chunked layout dataset", data,