Struct H5Group 

pub struct H5Group { /* private fields */ }

A handle to an HDF5 group.

Groups are containers for datasets and other groups. The root group is always available via H5File::root_group.

Implementations

impl H5Group

pub fn name(&self) -> &str

Return the name (path) of this group.

pub fn new_dataset<T: H5Type>(&self) -> DatasetBuilder<T>

Start building a new dataset in this group.

The dataset will be registered as a child of this group in the HDF5 file hierarchy.

pub fn create_group(&self, name: &str) -> Result<H5Group>

Create a sub-group within this group.

Creates a real HDF5 group with its own object header.

pub fn link(&self, link_name: &str, target_path: &str) -> Result<()>

Create a hard link in this group: an additional name link_name for the object that already exists at target_path.

No data is copied — the link and its target share one object, just as h5py / libhdf5 hard links do. target_path may be given with or without a leading / and must name an existing dataset or group. This is the NeXus-style way to expose a dataset at a second canonical location (e.g. /entry/data/data) without duplicating it.

use rust_hdf5::H5File;

let file = H5File::create("nexus.h5").unwrap();
let inst = file.root_group().create_group("instrument").unwrap();
inst.new_dataset::<f32>().shape(&[10]).create("data").unwrap();
let data = file.root_group().create_group("data").unwrap();
// /data/data is now a hard link to /instrument/data — no copy.
data.link("data", "/instrument/data").unwrap();

pub fn create_soft_link(&self, link_name: &str, target_path: &str) -> Result<()>

Create a soft link — H5Lcreate_soft, h5py’s h5py.SoftLink.

The link stores target_path as text and HDF5 resolves it on every traversal, so it may name an object that does not exist yet, or one that never will: unlike link, nothing is checked here and a dangling soft link is a legal file.

use rust_hdf5::H5File;

let file = H5File::create("soft.h5").unwrap();
file.new_dataset::<i32>().shape([8]).create("orig").unwrap();
file.root_group().create_soft_link("alias", "/orig").unwrap();

pub fn create_external_link( &self, link_name: &str, target_file: &str, target_path: &str, ) -> Result<()>

Create an external link — H5Lcreate_external, h5py’s h5py.ExternalLink.

The link names target_path inside target_file; neither is opened here, and libhdf5 resolves target_file against the directory holding this file, so a relative name is the portable form. As with create_soft_link the link may dangle: a file that is not there and an object that is not there are both legal.

use rust_hdf5::H5File;

let file = H5File::create("master.h5").unwrap();
file.root_group()
    .create_external_link("ext", "payload.h5", "/data")
    .unwrap();

pub fn commit_datatype( &self, name: &str, datatype: DatatypeMessage, ) -> Result<()>

Commit a datatype in this group under name — H5Tcommit2, h5py’s group["name"] = dtype.

The type becomes an object of its own, so datasets can be built on it with DatasetBuilder::committed_type and share one definition instead of each carrying a copy. A committed datatype no dataset ever uses is still a complete object, and h5py reads it back as a Datatype.

use rust_hdf5::H5File;
use rust_hdf5::format::messages::datatype::DatatypeMessage;

let file = H5File::create("committed.h5").unwrap();
let grp = file.create_group("types").unwrap();
grp.commit_datatype("temperature", DatatypeMessage::f64_type()).unwrap();

pub fn group(&self, name: &str) -> Result<H5Group>

Open an existing sub-group by name (read mode).

pub fn dataset_names(&self) -> Result<Vec<String>>

List dataset names that are direct children of this group.

pub fn write_vlen_strings( &self, name: &str, strings: &[&str], ) -> Result<H5Dataset>

Create a variable-length string dataset and write data within this group.

Returns a writer-mode handle to the created dataset so attributes can be attached to it (e.g. units, descriptions) just like a dataset created via new_dataset. The datatype declares UTF-8; write_vlen_strings_ascii is the ASCII-declaring twin, as on H5File.

pub fn write_vlen_strings_ascii( &self, name: &str, strings: &[&str], ) -> Result<H5Dataset>

Create a variable-length ASCII string dataset within this group.

The group-level twin of H5File::write_vlen_strings_ascii, with the same rejection of a string the ASCII declaration would misdescribe.

pub fn write_vlen_bytes(&self, name: &str, items: &[&[u8]]) -> Result<H5Dataset>

Create a variable-length byte-array dataset and write data within this group.

Each &[u8] becomes one element of variable length, stored as a vlen sequence of u8. h5py reads it back as an array of uint8 arrays. Returns a writer-mode handle so attributes can be attached, like write_vlen_strings.

The u8 case of write_vlen_numeric.

pub fn write_vlen_numeric<T: H5Type>( &self, name: &str, items: &[&[T]], ) -> Result<H5Dataset>

Create a variable-length numeric-sequence dataset within this group.

The group-level twin of H5File::write_vlen_numeric.

pub fn write_vlen_strings_compressed( &self, name: &str, strings: &[&str], chunk_size: usize, pipeline: FilterPipeline, ) -> Result<H5Dataset>

Create a chunked, compressed variable-length string dataset within this group.

Returns a writer-mode handle to the created dataset so attributes can be attached to it, like write_vlen_strings.

pub fn create_appendable_vlen_dataset( &self, name: &str, chunk_size: usize, pipeline: Option<FilterPipeline>, ) -> Result<H5Dataset>

Create an empty chunked vlen string dataset ready for incremental appends.

Returns a writer-mode handle to the created dataset so attributes can be attached before or between append_vlen_strings calls.

pub fn append_vlen_strings(&self, name: &str, strings: &[&str]) -> Result<()>

Append variable-length strings to an existing chunked vlen string dataset.

pub fn dataset_writer(&self, name: &str) -> Result<H5Dataset>

Reopen a writer-mode handle to a dataset in this group by name.

Mirrors H5File::dataset_writer but resolves name relative to this group, so a dataset created here (including via the vlen-string helpers) can be reopened to attach attributes or append chunks. name is the link name within this group.

pub fn dataset_writer_with( &self, name: &str, access: DatasetAccess, ) -> Result<H5Dataset>

dataset_writer under named dataset-access properties, mirroring H5File::dataset_writer_with — which is where the properties that reach a write are described.

pub fn group_names(&self) -> Result<Vec<String>>

List sub-group names that are direct children of this group.

pub fn link_names(&self) -> Result<Vec<String>>

List every link that is a direct child of this group — hard, soft and external alike, in name order.

This is the listing of links (H5Lget_name_by_idx, h5py’s grp.keys()), not of the objects they reach: dataset_names and group_names answer the object question, and a soft or external link appears here whether or not its target resolves. Pair it with link_class to tell the kinds apart.

pub fn named_datatype_names(&self) -> Result<Vec<String>>

The committed (named) datatypes that are direct children of this group, in the order the catalog holds them.

pub fn named_datatype(&self, name: &str) -> Result<H5NamedDatatype>

Open a committed (named) datatype that is a child of this group.

pub fn link_class(&self, name: &str) -> Result<LinkClass>

The class of the link name in this group, carrying the value H5Lget_val returns for the classes that have one — the target path of a soft link, the file and path of an external link.

Errors

Hdf5Error::NotFound when this group holds no link of that name.

pub fn unreadable_reason(&self, name: &str) -> Result<Option<String>>

Why the dataset name in this group cannot be read, or None when it can be.

A dataset whose datatype (or any other message its payload depends on) this crate cannot decode is still listed by dataset_names — the file contains it — and this says what stands in the way. Opening it through H5File::dataset fails with Hdf5Error::Unsupported carrying the same text.

pub fn set_attr_string(&self, name: &str, value: &str) -> Result<()>

Add (or replace) a string attribute on this group.

This is the standard way to mark a NeXus class, e.g. grp.set_attr_string("NX_class", "NXdetector"). The value is stored as a variable-length UTF-8 string (read back as a Python str by h5py), not a fixed-length string.

pub fn set_attr_numeric<T: H5Type>(&self, name: &str, value: &T) -> Result<()>

Add (or replace) a numeric scalar attribute on this group.

pub fn set_attr_array_numeric<T: H5Type>( &self, name: &str, values: &[T], ) -> Result<()>

Add (or replace) a numeric (or bool) array attribute on this group.

The values are written as a 1-D HDF5 array attribute (simple dataspace [values.len()]), read back by h5py as a numpy array — the array counterpart of set_attr_numeric. For a multi-dimensional shape use set_attr_array_numeric_nd.

pub fn set_attr_array_numeric_nd<T: H5Type>( &self, name: &str, values: &[T], shape: &[usize], ) -> Result<()>

Add (or replace) a numeric (or bool) N-dimensional array attribute on this group.

shape gives the dataspace dimensions; values is the row-major data and its length must equal the product of shape (an empty shape is a scalar, requiring exactly one value). Read back by h5py as a numpy array of that shape. set_attr_array_numeric is the 1-D convenience form.

pub fn set_attr_string_array(&self, name: &str, values: &[&str]) -> Result<()>

Add (or replace) a variable-length UTF-8 string array attribute on this group, read back by h5py as a 1-D array of str — the array counterpart of set_attr_string. For a multi-dimensional shape use set_attr_string_array_nd.

pub fn set_attr_string_array_nd( &self, name: &str, values: &[&str], shape: &[usize], ) -> Result<()>

Add (or replace) a variable-length UTF-8 string N-dimensional array attribute on this group.

shape gives the dataspace dimensions; values is the row-major data and its length must equal the product of shape (an empty shape is a scalar, requiring exactly one value). Read back by h5py as a numpy array of Python str with that shape. set_attr_string_array is the 1-D convenience form.

pub fn set_attr_object_reference(&self, name: &str, path: &str) -> Result<()>

Add (or replace) an object-reference attribute on this group — h5py’s g.attrs['owner'] = f['/data'].ref.

path names a dataset or a group (/ is the root group) and must already exist. The attribute takes the scalar shape h5py gives a single reference; set_attr_object_references is the array form. What reaches the file is the target’s object header address, which is assigned when the file is finalized.

pub fn set_attr_object_references( &self, name: &str, paths: &[&str], ) -> Result<()>

Add (or replace) a 1-D array of object references as an attribute on this group — the array counterpart of set_attr_object_reference.

pub fn attr_names(&self) -> Result<Vec<String>>

List this group’s attribute names (read mode).

pub fn attr_creation_order(&self) -> Result<CreationOrder>

This group’s own attribute creation-order policy — the equivalent of H5Pget_attr_creation_order(gid.get_create_plist()) — - when neither TRACKED nor INDEXED is set, and never derived from whether the group currently holds any attributes: a group can track creation order and still be empty (read mode).

pub fn attr_storage(&self) -> Result<AttributeStorage>

This group’s own compact-vs-dense attribute storage — the equivalent of h5py.h5o.get_info(gid.id).meta_size.attr.index_size being nonzero.

pub fn header_attr_count(&self) -> Result<u64>

This group’s own object-header attribute count — the equivalent of h5py.h5o.get_info(gid.id).num_attrs, which need not equal attr_names’s length when the set could not be read whole.

pub fn link_creation_order(&self) -> Result<CreationOrder>

This group’s own link creation-order policy — the equivalent of H5Pget_link_creation_order(gid.get_create_plist()). A fact about the group’s own Link Info message, independent of attr_creation_order: a group can track one without the other.

pub fn link_storage(&self) -> Result<LinkStorage>

This group’s own link storage kind — the equivalent of libhdf5’s H5Gget_info(gid).storage_type: SymbolTable for a pre-1.8 group (a v1 B-tree plus local heap, present regardless of the object header’s own version), Compact while links live as messages in the header, or Dense once the phase change moves the whole set into a fractal heap plus name index.

pub fn attr_unreadable_reason(&self, name: &str) -> Result<Option<String>>

Why this group’s attribute name cannot be read, or None when it can be. The attribute counterpart of unreadable_reason’s shape for datasets: an attribute this crate cannot decode stays in attr_names and answers here.

pub fn attrs_unreadable_reason(&self) -> Result<Option<String>>

Why this group’s attribute set cannot be listed, or None when it can be.

The object-scope counterpart of attr_unreadable_reason: a failure that belongs to no single name — a dense set whose heap or name index will not read — leaves nothing to list, so attr_names returns it as an error and this reports it without one.

pub fn attr_string(&self, name: &str) -> Result<String>

Read one of this group’s attributes as a string (read mode).