feature, add object references and attribute references (HDF5 1.12+ reference overhaul)

[steven-varga]

Summary

Complete h5cpp's coverage of the HDF5 1.12 reference overhaul: add factories and dispatch for object references (H5R_OBJECT2), attribute references (H5R_ATTR), and cross-file references, on top of the h5::reference_t handle that already ships.

What already shipped (v1.12.6)

These parts of the original scope are done — no further work needed:

• h5::reference_t unified handle wrapping H5R_ref_t, with rule-of-five RAII (H5Rdestroy / H5Rcopy). Lives in h5cpp/H5Tall.hpp. Landed via core, unify and extend core I/O, types, and container mappers #274 in v1.12.6.
• Region references (H5R_DATASET_REGION) via h5::reference(fd, "ds", h5::offset{…}, h5::count{…}) — the legacy pre-1.12 path now wrapped under the new handle. Demonstrated in examples/reference/reference.cpp.
• The pre-1.12 fallback path (hdset_reg_ref_t) is preserved for HDF5 < 1.12 builds.

What's still pending

The 1.12 overhaul added three categories of references on top of region references:

1. Object references (H5R_OBJECT2)

Point to any HDF5 object — datasets, groups, named types, attributes' parents — without selection. Replace the legacy H5R_OBJECT 8-byte refs with the unified 64-byte opaque.

2. Attribute references (H5R_ATTR) — new in 1.12

Point to a specific attribute on an object. No pre-1.12 equivalent.

3. Cross-file references — new in 1.12

A reference that carries the source file path; resolving it re-opens the source file transparently.

HDF5 APIs to wrap

• H5Rcreate_object(file, path, oapl) → h5::reference_t (object form)
• H5Rcreate_attr(file, path, attr_name, oapl) → h5::reference_t (attr form)
• H5Ropen_object, H5Ropen_attr, H5Ropen_region (the resolvers)
• H5Rget_type, H5Rget_obj_name, H5Rget_attr_name, H5Rget_file_name
• H5Requal (equality)

Proposed h5cpp API

// Object reference — point to a dataset, group, etc.
h5::reference_t obj_ref = h5::reference(fd, "/sensors/imu");

// Attribute reference — point to a specific attribute on an object.
h5::reference_t attr_ref = h5::reference(fd, "/sensors/imu", h5::attr{"calibration_date"});

// Cross-file reference — same surface, source file path baked in.
h5::reference_t ext_ref = h5::reference(fd, "external://other.h5/dataset");

// Resolve back to a handle.
h5::ds_t   ds   = h5::resolve<h5::ds_t>(fd, obj_ref);
h5::at_t   attr = h5::resolve<h5::at_t>(fd, attr_ref);

// Inspect.
auto type = h5::reference_type(ref);   // object | attribute | region | external
auto name = h5::reference_name(ref);   // "/sensors/imu"

Acceptance criteria

• h5::reference(loc, path) object-reference factory backed by H5Rcreate_object
• h5::reference(loc, path, h5::attr{name}) attribute-reference factory backed by H5Rcreate_attr
• Cross-file reference factory + resolution (handles the source-file re-open transparently)
• h5::resolve<T>(loc, ref) dispatching to H5Ropen_object / H5Ropen_attr / H5Ropen_region based on H5Rget_type
• h5::reference_type, h5::reference_name, h5::reference_file introspection helpers
• Equality operator via H5Requal
• Tests covering: object refs, attribute refs, cross-file refs, round-trip via dataset I/O
• examples/reference/reference.cpp extended (or split) to demonstrate all three new categories alongside the existing region-reference demo