|
H5CPP
v1.14.0
Modern C++ templates for HDF5 serial and parallel I/O
|
|
The single reference for every public h5cpp wrapper type — what it wraps, what close function it calls, how it's constructed, and where to find it. Linked from the RAII Handles and Property Lists overview pages, the Conversion Policy page, and the cookbook leaves where the types are used.
Every entry in the tables below is an h5::impl::detail::hid_t<…> specialisation — same RAII contract, refcount semantics, and conversion policy across the board. See RAII Handles for the common contract and Conversion Policy for the conversion mechanism the wrappers share.
First-class HDF5 objects with their own ID space, refcount, and dedicated close function. RAII-managed; both implicit and explicit conversion to / from hid_t are enabled by default (Conversion Policy). All seven specialise the h5::impl::detail::hid_t template at <…, true, true, hdf5_class>.
| Alias | HDF5 close | Wraps | Typical factory |
|---|---|---|---|
h5::fd_t | H5Fclose | file descriptor | h5::open(path, flags), h5::create(path, flags) |
h5::ds_t | H5Dclose | dataset | h5::open(fd, name), h5::create<T>(fd, name, …) |
h5::gr_t | H5Gclose | group | h5::gopen(fd, name), h5::gcreate(fd, name) |
h5::at_t | H5Aclose | attribute | h5::acreate, ds["name"] bracket access |
h5::ob_t | H5Oclose | generic HDF5 object (file / dataset / group / named-type) | internal; rarely instantiated directly |
h5::sp_t | H5Sclose | dataspace | h5::get_space(ds), h5::create_simple(...) |
h5::dt_t<T> (template) | H5Tclose | datatype for T | default-constructed: h5::dt_t<int>{} looks up the cached HDF5 type for T |
h5::ds_t, h5::gr_t, and h5::ob_t expose an operator[](const char*) that returns a transient h5::at_t carrying the parent handle and the attribute name. Combined with at_t::operator=(V) and the templated at_t::operator V() const, this gives a symmetric Python-dict-like API for attribute I/O without leaving expression syntax:
The bracket form is sugar over the free-function surface; both write the same on-disk bytes as h5::awrite(gr, "title", ...) and read the same value as h5::aread<T>(gr, "title"). Type V follows the same dispatch matrix as the rest of the I/O API (see Supported Types). The conversion excludes hid_t so plain static_cast<::hid_t>(at_t) still resolves to the inherited handle accessor.
Caveats:
auto v = gr["x"] deduces at_t, not the attribute value; the implicit conversion needs a concrete LHS type to fire.at_t only carries ds + name; if the parent handle is closed before the conversion runs, the read throws h5::error::io::attribute::read.Specialisations with both conversion directions deleted at the type level (operator hid_t() const = delete;) so a stray pass to a raw HDF5 C call fails to compile. Used by the FAPL-scoped async executor (h5::async::create / h5::async::open); the handle carries a std::shared_ptr<executor_t> so operation overloads can reach the executor thread without round-tripping through HDF5's property machinery. See Async mode — conversion deleted at the type level for the diagnostic shape.
| Alias | HDF5 close | Wraps | Constructed by |
|---|---|---|---|
h5::async::fd_t | H5Fclose | file descriptor (async-mode) | h5::async::create(path, flags), h5::async::open(path, flags) |
h5::async::ds_t | H5Dclose | dataset (async-mode) | inherited from parent h5::async::fd_t via TAD |
h5::async::gr_t | H5Gclose | group (async-mode) | inherited from parent |
h5::async::at_t | H5Aclose | attribute (async-mode) | inherited from parent |
h5::async::ob_t | H5Oclose | generic object (async-mode) | inherited from parent |
| Alias | Wraps | Notes |
|---|---|---|
h5::reference_t | HDF5 H5R_ref_t (1.12+) or hdset_reg_ref_t (pre-1.12) | Rule-of-five RAII: H5Rdestroy on destruction, H5Rcopy on copy. The pre-1.12 path stores a value type and needs no explicit close. Lives in h5cpp/H5Tall.hpp. |
All wrap an hid_t with H5Pclose as the close function. The h5::default_* constants are H5P_DEFAULT singletons, so omitting a property-list argument gives baseline HDF5 behaviour.
| Alias | HDF5 property class | Default constant | Setters / domain |
|---|---|---|---|
h5::fapl_t | file access | h5::default_fapl | driver selection, parallel I/O, ROS3, threads, libver bounds |
h5::fcpl_t | file creation | h5::default_fcpl | user block, sizes, sym_k, istore_k, shared messages |
h5::dapl_t | dataset access | (H5P_DEFAULT) | chunk cache, virtual-view, efile_prefix |
h5::dcpl_t | dataset creation | h5::default_dcpl | chunk, layout, filters (gzip / szip / shuffle / fletcher32 / nbit), fill value, allocation |
h5::dxpl_t | data transfer | h5::default_dxpl | buffer size, type-conversion callback, MPIO mode |
h5::lcpl_t | link creation | h5::default_lcpl | character set (UTF-8 by default), create-intermediate-groups |
h5::lapl_t | link access | (H5P_DEFAULT) | NLINKS bound, ELINK file-cache, ELINK callback |
h5::gcpl_t | group creation | (H5P_DEFAULT) | link phase change, estimated num-links |
h5::gapl_t | group access | (H5P_DEFAULT) | (no public setters in current h5cpp surface) |
h5::tcpl_t | type (datatype) creation | (H5P_DEFAULT) | used internally by H5Tcreate paths |
h5::tapl_t | type (datatype) access | (H5P_DEFAULT) | used internally by H5Topen paths |
h5::acpl_t | attribute creation | h5::default_acpl | character set for attribute names |
h5::ocpl_t | object creation | (H5P_DEFAULT) | attr phase change, track times |
h5::ocrl_t | object copy | (H5P_DEFAULT) | copy flags (shallow / expand-soft-link / merge-committed-types) |
h5::fmpl_t | file mount | (H5P_DEFAULT) | (currently used internally only) |
h5::scpl_t | string creation | (H5P_DEFAULT) | (reserved for future use) |
Property lists compose with operator|. Each setter (e.g. h5::chunk{N}, h5::gzip{level}, h5::threads{8}, h5::ros3{...}) returns the matching property-list wrapper:
Strongly-typed wrappers around HDF5's hsize_t[H5CPP_MAX_RANK] dimension arrays. Not RAII handles (no HDF5 resource to close), but part of the public API surface and used at every h5::read / h5::write / h5::create call site.
| Type | Argument name at the call site | Meaning |
|---|---|---|
h5::current_dims_t | current_dims | initial (current) dataset extent at creation |
h5::max_dims_t | max_dims | maximum dataset extent; H5S_UNLIMITED marks extendable |
h5::dims_t | (general dims) | generic dimension descriptor used by helpers |
h5::chunk_t | chunk | chunk shape for chunked storage |
h5::offset_t | offset | first-element coordinates of a hyperslab selection |
h5::stride_t | stride | step between selected elements per dimension |
h5::count_t | count | number of blocks per dimension |
h5::block_t | block | block size per dimension |
All eight are aliases of h5::impl::array<impl::*_t> (see h5cpp/H5Sall.hpp:102-109) — a strong-typedef pattern that lets the same set of integers be tagged with their semantic role, so h5::write(fd, "x", v, h5::offset{0,0}, h5::count{4,4}) couldn't accidentally swap offset and count.
The core template is in h5cpp/H5Iall.hpp — h5::impl::detail::hid_t<T, capi_close, from_capi, to_capi, hdf5_class>. Public aliases are emitted by the H5CPP__def{hid,pid,did,aid}_t macros in the same file (lines 325-345) which stamp one struct impl::T_ final {} tag per alias to keep the types distinct at overload-resolution time.
The five template parameters in summary:
| Parameter | Role |
|---|---|
T | tag type; one empty struct per public alias so h5::fd_t and h5::gr_t are distinct overload targets |
capi_close | the HDF5 close function (H5Fclose, H5Dclose, H5Pclose, …) |
from_capi | whether hid_t → wrapper construction is enabled (Conversion Policy) |
to_capi | whether wrapper → hid_t conversion is enabled (Conversion Policy) |
hdf5_class | selects a specialisation that adds class-specific members (e.g. the attribute specialisation carries the parent dataset's hid_t for ds[name] subscript access) |