HDF5 attributes

Detailed Description

Templated attribute I/O on any parent that can carry metadata — files, groups, datasets, opaque objects, committed datatypes. Element type T follows the same dispatch as the dataset API (see Supported Types); attributes do not chunk, do not support partial I/O, and use the acpl property list family.

See also

H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI

Function Documentation

create()

template<class T, class hid_t, class... args_t>

h5::at_t h5::create ( const hid_t&  parent, const std::string&  path, args_t&&...  args  )

inline

Create a new attribute of element type T on a parent HDF5 object.

Attributes are small named metadata items attached to a parent object (file, group, dataset, opaque object, or committed datatype). h5::create allocates the on-disk slot — the value itself is later deposited with h5::awrite(parent, path, value) or read back with h5::aread<T>(parent, path). The element type T follows the same dispatch as the dataset API (see Supported Types): elementary scalar, registered compound, fixed or variable-length string, etc. Attributes do not chunk and do not support partial I/O, so neither h5::chunk{} nor offset/stride/count apply here.

Parameters

parent	open parent handle: raw hid_t, h5::gr_t, h5::ds_t, h5::ob_t, or h5::dt_t<T> — enforced at compile time via h5::impl::is_valid_attr. Note: typed h5::fd_t is not accepted directly; pass static_cast<::hid_t>(fd) to attach an attribute to the file root.
path	attribute name (UTF-8); resolved relative to parent.
args[,...]	comma-separated list of arguments in arbitrary order; only T object (or const T* for pointer overloads) is required — the optionals are h5::current_dims (attribute shape; defaults to scalar) and h5::acpl_t (attribute creation property list; defaults to H5P_ATTRIBUTE_CREATE). Attributes do not chunk and do not support partial I/O, so offset / stride / count / block / dxpl / max_dims / dcpl / lcpl do not apply.

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.
hid_t	deduced from the parent argument; must satisfy h5::impl::is_valid_attr<hid_t>::value.

Returns

h5::at_t RAII handle owning the new attribute id; closes automatically via H5Aclose on scope exit. Throws on failure.

The optional arguments are context-sensitive and may be passed in any order. By default the attribute is created with an empty (rank-0) shape and the default attribute creation property list:

• current_dims — initial (current) dataset extent Defaults to {0} — a scalar attribute. Pass a non-trivial extent for an array-valued attribute (e.g. h5::current_dims{8} for an 8-element vector attribute).

• acpl — attribute creation property list (h5::acpl_t); defaults to H5P_ATTRIBUTE_CREATE.

Exceptions

h5::error::io::attribute::create	on H5Acreate2 failure (parent does not exist, attribute already exists, type conversion error, etc.).
h5::error::property_list::misc	when an invalid acpl is supplied.

example: explicit pre-allocation — useful when the shape is non-default or you want the attribute slot to exist before any value is written. Most call sites skip h5::create<T> and let h5::awrite create-on-demand instead.

h5::fd_t fd = h5::open("file.h5", H5F_ACC_RDWR);
h5::ds_t ds = h5::open(fd, "/grid/data");
 
// rank-1 of 3 floats; deposit the value later with h5::awrite.
h5::create<float>(ds, "spacing", h5::current_dims{3});
 
// Scalar attribute on the file root — fd_t needs an explicit cast
// (h5::fd_t is not in is_valid_attr; raw ::hid_t is).
h5::create<double>(static_cast<::hid_t>(fd), "schema_version");
 
// Round-trip with h5::awrite / h5::aread:
h5::awrite(ds, "spacing", std::vector<float>{0.5f, 0.5f, 1.0f});
auto v = h5::aread<std::vector<float>>(ds, "spacing");

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::aread h5::awrite Handles, Descriptors, and Property Lists

Examples

arma.cpp, attributes.cpp, basics.cpp, blaze.cpp, blitz.cpp, collective.cpp, compound.cpp, container.cpp, cout.cpp, csv2hdf5.cpp, datasets.cpp, datatypes.cpp, detected.cpp, dlib.cpp, eigen.cpp, eigen3.cpp, file_per_rank.cpp, groups.cpp, independent.cpp, itpp.cpp, main.cpp, maps.cpp, mdspan.cpp, nested.cpp, optimized.cpp, packet_batches.cpp, packettable.cpp, pipeline.cpp, raw.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.

adelete()

template<class hid_t >

void h5::adelete ( const hid_t&  parent, const std::string&  name  )

inline

Delete an attribute by name from a parent HDF5 object.

Removes the named attribute from the on-disk representation of parent. The operation is final — there is no rollback once H5Adelete has succeeded.

Parameters

parent	open parent handle: raw hid_t, h5::gr_t, h5::ds_t, h5::ob_t, or h5::dt_t<T> — enforced at compile time via h5::impl::is_valid_attr. Typed h5::fd_t is not accepted directly; pass static_cast<::hid_t>(fd).
name	attribute name (UTF-8); resolved relative to parent.

Template Parameters

hid_t

deduced from the parent argument; must satisfy h5::impl::is_valid_attr<hid_t>::value.

Returns

void — failures are reported by throwing.

Exceptions

h5::error::io::attribute::delete_

on H5Adelete failure (attribute does not exist, parent invalid, write access denied).

example:

h5::ds_t ds = h5::open(fd, "/grid/data");
h5::adelete(ds, "stale_marker");

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::create h5::open Handles, Descriptors, and Property Lists

open()

template<class hid_t >

h5::at_t h5::open ( const hid_t&  parent, const std::string&  path, const h5::acpl_t&  acpl = h5::default_acpl  )

inline

Open an existing attribute by name on a parent HDF5 object.

Lookup is by attribute name relative to parent. The returned h5::at_t is RAII-managed; the underlying CAPI handle is closed via H5Aclose on scope exit. Use h5::aread to retrieve the value, or pass the handle to h5::awrite overloads that take an already-open attribute.

Parameters

parent	open parent handle: raw hid_t, h5::gr_t, h5::ds_t, h5::ob_t, or h5::dt_t<T> — enforced at compile time via h5::impl::is_valid_attr. Typed h5::fd_t is not accepted directly; pass static_cast<::hid_t>(fd).
path	attribute name (UTF-8); resolved relative to parent.
acpl	attribute creation property list (h5::acpl_t); defaults to h5::default_acpl.

Template Parameters

hid_t

deduced from the parent argument; must satisfy h5::impl::is_valid_attr<hid_t>::value.

Returns

h5::at_t RAII handle owning the opened attribute id; closes automatically via H5Aclose on scope exit. Throws on failure.

Exceptions

h5::error::io::attribute::open

on H5Aopen failure (attribute not present, parent does not exist, invalid acpl).

example:

h5::fd_t fd = h5::open("file.h5", H5F_ACC_RDONLY);
h5::ds_t ds = h5::open(fd, "/grid/data");
h5::at_t att = h5::open(ds, "spacing");
auto axes = h5::aread<std::vector<float>>(ds, "spacing");

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::aread h5::awrite Handles, Descriptors, and Property Lists

Examples

collective.cpp, cout.cpp, file_per_rank.cpp, independent.cpp, itpp.cpp, pipeline.cpp, reference.cpp, s3.cpp, string.cpp, throughput.cpp, and utf.cpp.

aread()

template<class T, class hid_t >

T h5::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.

T follows the same dispatch as the dataset API (see Supported Types): elementary scalar, registered compound, fixed or variable-length string, STL container, linear-algebra container, std::tuple, std::pair, std::complex, etc. The on-disk type must be compatible with T; HDF5 has no fixed-length / VLEN string conversion, so a fixed-length string attribute can be read into std::string but not into a std::vector of VLEN strings unless the disk type was VLEN.

Attributes do not chunk and do not support partial I/O; the full value is materialised in memory.

Parameters

ds	open parent handle: raw hid_t, h5::gr_t, h5::ds_t, h5::ob_t, or h5::dt_t<T> — enforced at compile time via h5::impl::is_valid_attr. Typed h5::fd_t is not accepted directly; pass static_cast<::hid_t>(fd).
name	attribute name (UTF-8); resolved relative to parent.
acpl	attribute creation property list (h5::acpl_t); defaults to h5::default_acpl.

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.
hid_t	deduced from the parent argument; must satisfy h5::impl::is_valid_attr<hid_t>::value.

Returns

fully constructed object of type T populated with the attribute's value.

Exceptions

h5::error::io::attribute::open	if the attribute is not present.
h5::error::io::attribute::read	on H5Aread failure (type conversion error, unsupported on-disk shape, etc.).

example: read what was written by h5::awrite. Type T determines how the on-disk value is materialised; it must be compatible with the attribute's stored datatype.

h5::fd_t fd = h5::open("file.h5", H5F_ACC_RDONLY);
h5::ds_t ds = h5::open(fd, "/grid/data");
 
auto version = h5::aread<double>(ds, "schema_version");              // scalar
auto spacing = h5::aread<std::vector<float>>(ds, "spacing");         // rank-1
auto label   = h5::aread<std::string>(ds, "label");                  // VLEN string
 
// Bracket-syntax sugar — implicit conversion picks T from the LHS.
std::string label2 = ds["label"];

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::create h5::open h5::awrite Handles, Descriptors, and Property Lists

Examples

arma.cpp, attributes.cpp, basics.cpp, blaze.cpp, blitz.cpp, collective.cpp, compound.cpp, container.cpp, cout.cpp, csv2hdf5.cpp, datasets.cpp, datatypes.cpp, detected.cpp, dlib.cpp, eigen.cpp, eigen3.cpp, file_per_rank.cpp, groups.cpp, independent.cpp, itpp.cpp, main.cpp, maps.cpp, mdspan.cpp, nested.cpp, optimized.cpp, packet_batches.cpp, packettable.cpp, pipeline.cpp, raw.cpp, reference.cpp, reflection.cpp, s3.cpp, sequences.cpp, sets.cpp, smart_ptr.cpp, string.cpp, strings.cpp, throughput.cpp, transform.cpp, tuples_pairs.cpp, ublas.cpp, and utf.cpp.

awrite() [1/3]

template<class T >

void h5::awrite ( const h5::at_t&  attr, const T*  ptr  )

inline

Low-level attribute write — copies elements from ptr into an already-open h5::at_t.

Used internally by the dispatched h5::awrite(parent, name, ref, ...) overloads when they need to write through a pre-built attribute handle (composite, contiguous, iter-staging branches). The HDF5 datatype is deduced from T via h5::dt_t<T>.

Callers typically use the high-level dispatched overload below rather than calling this directly.

Parameters

attr	open h5::at_t handle obtained from h5::create or h5::open; must be valid for write.
ptr	pointer to a memory region holding at least the attribute's element count of values of type T.

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 — failures are reported by throwing h5::error::io::attribute::write.

Exceptions

h5::error::io::attribute::write

on H5Awrite failure (handle invalid, type-conversion error, etc.).

Examples

attributes.cpp, cout.cpp, groups.cpp, and string.cpp.

awrite() [2/3]

template<class T, class hid_t, class... args_t>

h5::at_t h5::awrite ( const hid_t&  parent, const std::string&  name, const T&  ref, const h5::acpl_t&  acpl = h5::default_acpl  )

inline

Write an object as an attribute on a parent HDF5 object.

Creates the attribute if it does not exist, opens it if it does, then writes ref into it. Element type T follows the same dispatch as the dataset API (see Supported Types): scalar, registered compound, string (fixed or VLEN), STL container, linear-algebra container, tuple, pair, complex, etc.

Attributes do not chunk and do not support partial I/O; the attribute's shape is derived from ref via access_traits_t<T>::size.

Parameters

parent	open parent handle: raw hid_t, h5::gr_t, h5::ds_t, h5::ob_t, or h5::dt_t<T> — enforced at compile time via h5::impl::is_valid_attr. Typed h5::fd_t is not accepted directly; pass static_cast<::hid_t>(fd).
name	attribute name (UTF-8); resolved relative to parent.
ref	value to write; type T determines on-disk layout.
acpl	attribute creation property list (h5::acpl_t); defaults to h5::default_acpl.

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.
hid_t	deduced from the parent argument; must satisfy h5::impl::is_valid_attr<hid_t>::value.

Returns

h5::at_t RAII handle owning the (now-populated) attribute id.

Exceptions

h5::error::io::attribute::write	on H5Awrite failure.
h5::error::io::attribute::create	if the attribute didn't exist and creation failed.

example: create-on-demand round-trip. Each awrite call here creates the attribute if it doesn't exist, then writes the value (shape derived from the value's access_traits_t::size).

h5::fd_t fd = h5::open("file.h5", H5F_ACC_RDWR);
h5::ds_t ds = h5::open(fd, "/grid/data");
 
// Three attributes of distinct kinds — scalar, vector, string.
h5::awrite(ds, "schema_version", 1.4);                            // double scalar
h5::awrite(ds, "spacing", std::vector<float>{0.5f, 0.5f, 1.0f});  // rank-1, 3 floats
h5::awrite(ds, "label", std::string{"u32"});                      // VLEN string
 
// Bracket-syntax sugar over the same dispatch — see h5::ds_t::operator[].
ds["axes"] = {1, 2, 3};                                           // 3 ints
 
// Read these back with h5::aread<T>(ds, "name").

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::create h5::open h5::aread Handles, Descriptors, and Property Lists

awrite() [3/3]

template<class T, class hid_t >

h5::at_t h5::awrite ( const hid_t&  parent, const std::string&  name, const std::initializer_list< T >  ref, const h5::acpl_t&  acpl = h5::default_acpl  )

inline

Write a brace-initialised list as an attribute.

Convenience overload for the brace-list form h5::awrite(parent, "x", {1, 2, 3}). The list is materialised internally and written through the standard dispatched path; on-disk shape is rank-1 of the list's element type.

Parameters

parent	open parent handle: raw hid_t, h5::gr_t, h5::ds_t, h5::ob_t, or h5::dt_t<T> — enforced at compile time via h5::impl::is_valid_attr.
name	attribute name (UTF-8); resolved relative to parent.
ref	std::initializer_list<T> to write.
acpl	attribute creation property list (h5::acpl_t); defaults to h5::default_acpl.

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.
hid_t	deduced from the parent argument; must satisfy h5::impl::is_valid_attr<hid_t>::value.

Returns

h5::at_t RAII handle owning the (now-populated) attribute id.

Exceptions

h5::error::io::attribute::write	on H5Awrite failure.
h5::error::io::attribute::create	if the attribute didn't exist and creation failed.

example:

h5::ds_t ds = h5::open(fd, "/grid/data");
h5::awrite(ds, "axes", {1, 2, 3});       // int  attribute, rank-1, length 3
h5::awrite(ds, "spacing", {0.5f, 1.0f}); // float attribute, rank-1, length 2

See also

h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t