h5 Namespace Reference

public namespace More...

Typedefs
using	cx_double = std::complex< double >
using	cx_float = std::complex< float >

Functions
template<class T , class hid_t , class... args_t>
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.
template<class hid_t >
void	adelete (const hid_t &parent, const std::string &name)
	Delete an attribute by name from a parent HDF5 object.
template<class hid_t >
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.
template<class T , class hid_t >
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.
template<class T >
void	awrite (const h5::at_t &attr, const T *ptr)
	Low-level attribute write — copies elements from ptr into an already-open h5::at_t.
template<class T , class hid_t , class... args_t>
h5::at_t	awrite (const hid_t &parent, const std::string &name, const T &ref, const h5::acpl_t &acpl=h5::default_acpl)
	Write an object as an attribute on a parent HDF5 object.
template<class T , class hid_t >
h5::at_t	awrite (const hid_t &parent, const std::string &name, const std::initializer_list< T > ref, const h5::acpl_t &acpl=h5::default_acpl)
	Write a brace-initialised list as an attribute.
h5::current_dims_t	get_extent (const h5::ds_t &ds)
	Returns the current extent (dimensions) of a dataset — the read-side mirror of h5::set_extent. For a rank-1 dataset h5::get_extent(ds)[0] is the length; static_cast<hsize_t>(h5::get_extent(ds)) is the total element count.
template<class T , class... args_t>
h5::ds_t	create (const h5::fd_t &fd, const std::string &dataset_path, args_t &&... args)
	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
template<class T , class... args_t>
h5::ds_t	create (const std::string &file_path, const std::string &dataset_path, args_t &&... args)
	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
const char **	gather (const std::vector< std::string > &ref, std::vector< const char * > &ptrs)
	gathers memory regions into a single set of pointers Objects may be classified by whether the content resides in contiguous memory location, making convenient to IO operation: only single call is needed; or scattered and we need a reliable mechanism to collect the content. h5::gather is a template mechanism to facilitate the latter process by finding and returning a set of element_t type pointers to the actual content of an object.
h5::ds_t	open (const h5::fd_t &fd, const std::string &path, const h5::dapl_t &dapl=h5::default_dapl)
	Open an existing HDF5 dataset by path.
template<class T , class... args_t>
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.
template<class T , class... args_t, class = std::enable_if_t<arg::tpos<const h5::count_t&, const args_t&...>::present>>
void	read (const h5::fd_t &fd, const std::string &dataset_path, T *ptr, args_t &&... args)
	Open a dataset by path and read elements into caller-allocated memory.
template<class T , class... args_t>
void	read (const std::string &file_path, const std::string &dataset_path, T *ptr, args_t &&... args)
	Open a file and dataset by path then read into caller-allocated memory.
template<class T , class... args_t>
void	read (const h5::ds_t &ds, T &ref, args_t &&... args)
	Read into a caller-allocated container or value of type T.
template<class T , class... args_t, class = std::enable_if_t<!h5::meta::is_sparse_v<std::decay_t<T>>>>
void	read (const h5::fd_t &fd, const std::string &dataset_path, T &ref, args_t &&... args)
	Open a dataset by path and read into a caller-allocated container or value.
template<class T , class... args_t, class = std::enable_if_t<!h5::meta::is_sparse_v<std::decay_t<T>>>>
void	read (const std::string &file_path, const std::string &dataset_path, T &ref, args_t &&... args)
	Open a file and dataset by path then read into a caller-allocated container.
template<class T , class... args_t>
T	read (const h5::ds_t &ds, args_t &&... args)
	Return-by-value read — materialise the dataset as a fresh T.
template<class T , class... args_t, class = std::enable_if_t<!h5::meta::is_sparse_v<std::decay_t<T>>>>
T	read (hid_t fd, const std::string &dataset_path, args_t &&... args)
	Open a dataset by path and return its contents as a fresh T.
template<class T , class... args_t, class = std::enable_if_t<!h5::meta::is_sparse_v<std::decay_t<T>>>>
T	read (const std::string &file_path, const std::string &dataset_path, args_t &&... args)
	Open a file + dataset by path and return contents as a fresh T.
template<typename T >
h5::ds_t	scatter (hid_t fd, const std::string &path, const T &obj)
	Generic scatter (write) template for tier-2+ types.
template<typename T >
void	gather (hid_t fd, const std::string &path, T &obj)
	Generic gather (read) template for tier-2+ types.
template<class T , class LOC , class = std::enable_if_t<h5::impl::is_valid_group_parent<LOC>::value && h5::meta::is_sparse_v<T>>>
h5::gr_t	write (const LOC &parent, const std::string &path, const T &src)
	Write a sparse matrix or vector as a CSC group.
template<class T , class LOC , class = std::enable_if_t<h5::impl::is_valid_group_parent<LOC>::value && h5::meta::is_sparse_v<T>>>
T	read (const LOC &parent, const std::string &path)
	Read a CSC group back into a sparse matrix or vector of type T.
template<class T >
void	write (const h5::ds_t &ds, const h5::sp_t &mem_space, const h5::sp_t &file_space, const h5::dxpl_t &dxpl, const T *ptr)
	write the memory content of const T* ptr with given mem_space into file_space of the dataset
template<class T , class... args_t>
h5::ds_t	write (const h5::ds_t &ds, const T *ptr, args_t &&... args)
	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
template<class T , class... args_t, class = std::enable_if_t<!std::is_pointer_v<std::decay_t<T>> || std::is_array_v<T>>>
h5::ds_t	write (const h5::ds_t &ds, const T &ref, args_t &&... args)
	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.
template<std::size_t N, class... args_t>
h5::ds_t	write (const h5::fd_t &fd, const std::string &dataset_path, const char(&ref)[N], args_t &&... args)
	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
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>>>>
h5::ds_t	write (const h5::fd_t &fd, const std::string &dataset_path, const T &ref, args_t &&... args)
	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
template<class... args_t>
h5::ds_t	write (const std::string &file_path, const std::string &dataset_path, args_t &&... args)
	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
void	mute ()
	removes default error handler preventing diagnostic error messages printed for direct CAPI calls. This is a thread safe implementation. Read on Error Handling/Exceptions
void	unmute ()
	restores previously saved error handler with h5::mute Read on Error Handling/Exceptions
h5::fd_t	create (const std::string &path, unsigned flags, const h5::fcpl_t &fcpl=h5::default_fcpl, const h5::fapl_t &fapl=h5::default_fapl)
	creates an HDF5 file with given set of properties and returns a managed h5::fd_t resource handle. Depending on active conversion policy h5::fd_t may be passed implicitly,explicitly or not at all to HDF5 CAPI calls.
h5::fd_t	open (const std::string &path, unsigned flags, const h5::fapl_t &fapl=h5::default_fapl)
template<class HID_T >
std::enable_if_t< h5::impl::is_valid_group_parent< HID_T >::value, h5::gr_t >	gcreate (const HID_T &parent, const std::string &path, const h5::lcpl_t &lcpl=h5::default_lcpl)
	Creates an HDF5 group and returns a managed h5::gr_t handle.
template<class HID_T >
std::enable_if_t< h5::impl::is_valid_group_parent< HID_T >::value, h5::gr_t >	gopen (const HID_T &parent, const std::string &path)
	Opens an existing HDF5 group and returns a managed h5::gr_t handle.

Detailed Description

public namespace

impl::property_group<H5Pset_property, args...> args... ::= all argument types except the first this hid_t prop_ID since it is implicitly passed by template class.

Typedef Documentation

cx_double

using h5::cx_double = typedef std::complex<double>

scientific type

cx_float

using h5::cx_float = typedef std::complex<float>

scientific type

Function Documentation

gather() [1/2]

const char ** h5::gather ( const std::vector< std::string >&  ref, std::vector< const char* >&  ptrs  )

inline

gathers memory regions into a single set of pointers Objects may be classified by whether the content resides in contiguous memory location, making convenient to IO operation: only single call is needed; or scattered and we need a reliable mechanism to collect the content.
h5::gather is a template mechanism to facilitate the latter process by finding and returning a set of element_t type pointers to the actual content of an object.

Parameters

ref	reference to a linear algebra object (armadillo, eigen, blitz, blaze, dlib, ublas) or std::vector<T>
ptrs	vector receiving element pointers into the gathered content

Returns

ptr the same element_t pointer passed to the call (the in-out parameter is returned unchanged for chaining)

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.

scatter()

template<typename T >

h5::ds_t h5::scatter ( hid_t  fd, const std::string&  path, const T&  obj  )

inline

Generic scatter (write) template for tier-2+ types.

The primary template has no definition. h5cpp-compiler emits specializations that open/create the dataset, build the row_t mirror, and call h5::detail::write_one_row.

Template Parameters

T	user-defined struct type with heap-indirection fields

Returns

h5::ds_t the dataset handle (for chaining)

Examples

compound.cpp, and reflection.cpp.

gather() [2/2]

template<typename T >

void h5::gather ( hid_t  fd, const std::string&  path, T&  obj  )

inline

Generic gather (read) template for tier-2+ types.

The primary template has no definition. h5cpp-compiler emits specializations that open the dataset, read a row via h5::detail::read_one_row, and copy VLEN data into the user's containers.

Template Parameters

T	user-defined struct type with heap-indirection fields

gcreate()

template<class HID_T >

std::enable_if_t< h5::impl::is_valid_group_parent< HID_T >::value, h5::gr_t > h5::gcreate ( const HID_T&  parent, const std::string&  path, const h5::lcpl_t&  lcpl = h5::default_lcpl  )

inline

Creates an HDF5 group and returns a managed h5::gr_t handle.

Accepts a file or group as parent. The optional lcpl controls link creation semantics (character encoding, intermediate path creation). h5::default_lcpl enables UTF-8 encoding and intermediate group creation, which is almost always the right default.

h5::gr_t gr = h5::gcreate(fd, "sensors/imu");          // intermediate path created
h5::gr_t sub = h5::gcreate(gr, "channel_0");            // nested under existing group

Examples

attributes.cpp, container.cpp, cout.cpp, and groups.cpp.

gopen()

template<class HID_T >

std::enable_if_t< h5::impl::is_valid_group_parent< HID_T >::value, h5::gr_t > h5::gopen ( const HID_T&  parent, const std::string&  path  )

inline

Opens an existing HDF5 group and returns a managed h5::gr_t handle.

h5::gr_t gr = h5::gopen(fd, "/sensors/imu");
h5::awrite(gr, "sample_rate", 200.0);

Examples

groups.cpp.