Struct File 

pub struct File { /* private fields */ }

An open HDF5 file for reading.

Implementations

impl File

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

Open an HDF5 file from a filesystem path.

Reads the file into memory once. To follow a file that a concurrent single writer is appending to (SWMR), use File::open_swmr instead. To read a file larger than memory (e.g. on a 32-bit host) without buffering it, use File::open_streaming.

pub fn open_with_options<P: AsRef<Path>>( path: P, options: FileAccessOptions, ) -> Result<Self, Error>

Open an HDF5 file from a filesystem path with explicit access options.

Like open, this buffers the whole file in memory. Use open_streaming_with_options when the metadata cache budget should apply to lazy metadata reads.

pub fn open_streaming<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Open an HDF5 file for streaming reads, fetching regions on demand from the file instead of buffering it whole.

This lets a host read a file larger than its address space — the original motivation being 32-bit targets reading multi-gigabyte files (issue #27). Metadata and dataset chunks are read through a [ReadSeekSource], so peak memory stays close to one chunk plus the metadata being parsed.

Current limits (the buffered File::open has none of these): only latest-format (v2) groups resolve — a v1 symbol-table group on the path is rejected — and attribute reading on the streaming backend is not yet supported. Dataset reads (contiguous, compact, and all chunked index types) are fully supported.

pub fn open_streaming_with_options<P: AsRef<Path>>( path: P, options: FileAccessOptions, ) -> Result<Self, Error>

Open an HDF5 file for streaming reads with explicit access options.

pub fn open_swmr<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Open an HDF5 file for SWMR (single-writer/multiple-reader) reading.

Like File::open, but retains a live handle to the file so that File::refresh can re-read data appended by a concurrent writer (whether produced by this crate’s append writer, the reference HDF5 C library, or h5py in SWMR mode). The initial view is a consistent snapshot; call File::refresh to advance to a newer one.

Only the std build supports this (it requires a live filesystem handle); the in-memory File::from_bytes path cannot refresh.

pub fn open_swmr_with_options<P: AsRef<Path>>( path: P, options: FileAccessOptions, ) -> Result<Self, Error>

Open an HDF5 file for SWMR reading with explicit access options.

SWMR reads currently keep an in-memory mirror for refresh semantics, so only the per-dataset chunk-cache settings affect this backend.

pub fn from_bytes(data: Vec<u8>) -> Result<Self, Error>

Open an HDF5 file from an in-memory byte vector.

pub fn from_bytes_with_options( data: Vec<u8>, options: FileAccessOptions, ) -> Result<Self, Error>

Open an HDF5 file from an in-memory byte vector with explicit access options.

pub fn refresh(&mut self) -> Result<(), Error>

Re-read the file from disk to pick up data appended by a concurrent writer, then re-parse the superblock.

This is the SWMR reader’s refresh primitive (analogous to the C library’s H5Drefresh / h5py’s Dataset.refresh()): after it returns, newly fetched Dataset/Group handles observe the writer’s appended chunks and extended dimensions, because they re-parse object headers at their (stable) addresses against the refreshed bytes. Existing handles borrow &self, so they must be dropped before calling this; re-fetch them afterward.

Returns Error::SwmrUnsupported if the file was not opened with File::open_swmr. The superblock is checksum-validated on every re-read; a transient parse failure (a writer caught mid-flush) is retried a bounded number of times before being surfaced.

Cost: each call re-reads the entire file from disk (O(file size)). That keeps the implementation simple and correct, but when following a large, steadily growing log it is the cost paid per refresh; budget refresh frequency accordingly.

pub fn root(&self) -> Group<'_>

Returns a handle to the root group.

pub fn dataset(&self, path: &str) -> Result<Dataset<'_>, Error>

Resolve a path and return a Dataset handle.

The dataset uses the file-wide chunk-cache default (configured with FileAccessOptions::with_chunk_cache). To override the cache for this one dataset, use dataset_with_options.

pub fn dataset_with_options( &self, path: &str, options: DatasetAccessOptions, ) -> Result<Dataset<'_>, Error>

Resolve a path and return a Dataset handle, applying per-dataset DatasetAccessOptions that override file-wide access defaults.

This is the dataset-open-with-access-property-list path (HDF5’s DAPL): the options’ chunk cache corresponds to H5Pset_chunk_cache and takes precedence, for this dataset only, over the H5Pset_cache-style file-wide default.

pub fn group(&self, path: &str) -> Result<Group<'_>, Error>

Resolve a path and return a Group handle.

pub fn as_bytes(&self) -> &[u8]

Returns the raw file bytes for an in-memory file, or an empty slice for a streaming file (which has no whole-file buffer).

pub const fn access_options(&self) -> FileAccessOptions

Return the access options used when opening this file.

pub fn superblock(&self) -> &Superblock

Returns a reference to the parsed superblock.

pub fn file_space_strategy(&self) -> Option<FileSpaceStrategy>

The file-space management strategy this file records in its superblock extension (set with H5Pset_file_space_strategy), or None if the file records none — the default, which the C library also writes as “no message”. See file_space_info for the full record (persist flag, threshold, page size).

pub fn file_space_info(&self) -> Option<&FileSpaceInfo>

The full FileSpaceInfo recorded in this file’s superblock extension, if present and readable.

pub fn persisted_free_space(&self) -> Vec<(u64, u64)>

The free regions a file persists on disk in its free-space managers (when written with H5Pset_file_space_strategy(..., persist = true)), as (address, length) pairs sorted by address.

Empty when the file does not persist free space, or for the streaming backend (which does not load the manager blocks). The addresses are file offsets (relative to the base address); reading data is unaffected by the presence or absence of these managers.

pub fn file_size(&self) -> u64

The size of the underlying file in bytes (the HDF5 H5Fget_filesize).

This is the total byte length of the backing store — for a streaming file the length reported by its source, for an in-memory file the length of its buffer. It includes any userblock prefix and trailing bytes, so it may exceed the superblock’s logical end-of-file address; compare against Superblock::eof_address (reachable via File::superblock) to detect appended or unaccounted tail bytes.

pub fn libver_bound(&self) -> LibVer

The minimum library version required to read this file, derived from its superblock version (the low bound of HDF5’s H5Fget_libver_bounds).

A version 3 superblock, for example, reports LibVer::V110 because it was introduced in HDF5 1.10.

Trait Implementations

impl Debug for File

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.