Struct H5File 

pub struct H5File { /* private fields */ }

An HDF5 file opened for reading or writing.

Datasets created from this file hold a shared reference to the underlying I/O handle, so the file does not need to outlive its datasets (they share ownership via reference counting).

Implementations

impl H5File

pub fn create<P: AsRef<Path>>(path: P) -> Result<Self>

Create a new HDF5 file at path. Truncates if the file already exists.

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Open an existing HDF5 file for reading.

pub fn open_rw<P: AsRef<Path>>(path: P) -> Result<Self>

Open an existing HDF5 file for appending new datasets.

Existing datasets are preserved. New datasets can be added and will be written after the current end of file. Existing chunked datasets can be extended with write_chunk and extend_dataset.

use rust_hdf5::H5File;
let file = H5File::open_rw("existing.h5").unwrap();
let ds = file.new_dataset::<f64>().shape(&[100]).create("new_data").unwrap();
ds.write_raw(&vec![0.0f64; 100]).unwrap();
file.close().unwrap();

pub fn options() -> H5FileOptions

Start building open options for an HDF5 file.

Use this to control file-locking behavior explicitly:

use rust_hdf5::{H5File, FileLocking};
// Open with locking disabled (e.g. on NFS without lock support).
let file = H5File::options()
    .locking(FileLocking::Disabled)
    .open_rw("existing.h5")
    .unwrap();

pub fn set_libver_latest(&self, latest: bool) -> Result<()>

Opt in to the latest file format for datasets created after this call — the equivalent of libhdf5’s H5Pset_libver_bounds(low = H5F_LIBVER_V200).

With latest set, filtered chunked datasets get a version-5 data layout message, whose chunk indexes store on-disk chunk sizes in fixed-width (sizeof_size, i.e. 8-byte) fields instead of fields sized from the uncompressed chunk size. That removes the overflow risk when a filter expands a chunk, but the file is only readable by libhdf5 ≥ 2.0 (h5py bundling hdf5 1.14 rejects it with “bad version number”).

Off by default; unfiltered and contiguous datasets are unaffected. Independent of this setting, a chunk larger than 4 GiB forces version 5 because version 4 cannot represent its size field, matching libhdf5.

Errors in read mode.

pub fn root_group(&self) -> H5Group

Return a handle to the root group.

The root group can be used to create datasets and sub-groups.

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

Create a group in the root of the file.

use rust_hdf5::H5File;
let file = H5File::create("groups.h5").unwrap();
let grp = file.create_group("detector").unwrap();

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

Start building a new dataset with the given element type.

This returns a fluent builder. Call .shape(...) to set dimensions and .create("name") to finalize.

let file = H5File::create("build.h5").unwrap();
let ds = file.new_dataset::<f64>().shape(&[3, 4]).create("matrix").unwrap();

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

Add a string attribute to the file (root group).

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 a numeric attribute to the file (root group).

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

Add a numeric (or bool) array attribute to the file (root group).

The values are written as a 1-D HDF5 array attribute (simple dataspace [values.len()], on-disk type T::hdf5_type()), 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 a numeric (or bool) N-dimensional array attribute to the file (root 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 a variable-length UTF-8 string array attribute to the file (root 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 a variable-length UTF-8 string N-dimensional array attribute to the file (root 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 attr_names(&self) -> Result<Vec<String>>

Return the names of file-level (root group) attributes.

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

Read a file-level string attribute.

pub fn is_writable(&self) -> bool

Check if the file is in write/append mode.

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

Create a variable-length string dataset and write data.

This is a convenience method for writing h5py-compatible vlen string datasets using global heap storage.

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

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

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

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.

Like write_vlen_strings, but stores the vlen references in chunked layout with the given filter pipeline (e.g., FilterPipeline::deflate(6) or FilterPipeline::zstd(3)). chunk_size is the number of strings per chunk.

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.

Use append_vlen_strings to add data. If pipeline is Some, chunks are compressed (e.g., Some(FilterPipeline::lz4())).

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

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

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

Delete a dataset by name. The dataset is unlinked on close; file space is not reclaimed.

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

Delete a group and all its child datasets/sub-groups. File space is not reclaimed.

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

Open an existing dataset by name (read mode).

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

Reopen an existing dataset by name in write mode.

dataset only works in read mode; in write mode a dataset is normally created via new_dataset. This returns a write-mode handle to a dataset created earlier in the same session, so you can attach attributes or append chunks to it without keeping the original handle around — e.g. to flush cached first/last values onto a dataset at file-close time.

Errors

Returns Hdf5Error::NotFound if no live dataset with that name exists, and an error in read mode (use dataset).

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

Return the names of all datasets in the root group.

Works in both read and write mode: in write mode, returns the names of datasets created so far; in read mode, returns the names discovered during file open.

pub fn close(self) -> Result<()>

Explicitly close the file. For a writer, this finalizes the file (writes superblock, headers, etc.). For a reader, this is a no-op.

The file is also auto-finalized on drop, but calling close() lets you handle errors.

pub fn close_no_sync(self) -> Result<()>

Close the file without a final fsync (write mode only).

Like close, this finalizes the file — object headers and superblock are written, so on return it is a complete, valid HDF5 file readable by any process — but the trailing sync_all (fsync) is skipped. The bytes are handed to the OS but are not guaranteed durable against power loss or an OS crash until the OS flushes its page cache.

This trades durability for speed (the fsync typically dominates close latency); use it for bulk output that can be regenerated. Prefer close when durability matters. Dropping the file without calling either finalizes durably.

For a reader or an already-closed file this is a no-op, matching close.

pub fn flush(&self) -> Result<()>

Flush the file to disk. Only meaningful in write mode.