Struct FileBuilder 

pub struct FileBuilder { /* private fields */ }

Builder for creating a new HDF5 file.

Example

use hdf5_pure::FileBuilder;
use hdf5_pure::AttrValue;

let mut builder = FileBuilder::new();
builder.create_dataset("data").with_f64_data(&[1.0, 2.0, 3.0]);
builder.set_attr("version", AttrValue::I64(1));
builder.write("output.h5").unwrap();

Implementations

impl FileBuilder

pub fn new() -> Self

Create a new file builder.

pub fn create_dataset(&mut self, name: &str) -> &mut FormatDatasetBuilder

Create a dataset at the root level. Returns a mutable reference to a DatasetBuilder for configuring data, shape, and attributes.

pub fn create_group(&mut self, name: &str) -> FormatGroupBuilder

Create a group builder. Call .finish() on the returned builder to complete it, then pass to add_group().

pub fn add_group(&mut self, group: FinishedGroup)

Add a finished group to the file.

pub fn with_userblock(&mut self, size: u64) -> &mut Self

Set the userblock size in bytes. Must be a power of two >= 512 or 0 (no userblock). The userblock region is filled with zeros. With the buffered finish, write your userblock data into bytes[0..size] afterwards; the streaming finish_to / write emit the zero-filled region directly, so overwrite the file’s first size bytes after the write instead.

pub fn with_libver_bounds(&mut self, low: LibVer, high: LibVer) -> &mut Self

Constrain the on-disk format version of the file, mirroring HDF5’s H5Pset_libver_bounds. The produced file must fall within [low, high], or finish / write fails with Error::Format wrapping FormatError::LibverBoundsUnsatisfiable.

This crate writes exactly one format — the version 3 superblock from HDF5 1.10 (LibVer::WRITER_OUTPUT) — so this is a compatibility assertion, not a format selector: a bound that excludes 1.10 (an upper bound older than it, or a lower bound newer than it) is rejected.

pub fn with_file_space_strategy( &mut self, strategy: FileSpaceStrategy, persist: bool, threshold: u64, ) -> &mut Self

Set the file-space management strategy, mirroring HDF5’s H5Pset_file_space_strategy. The strategy, persist flag, and free-space section threshold are recorded in the file’s superblock extension, so the reference C library and a later reopen observe the choice.

persist = true records that freed space should be tracked on disk across closes. A brand-new file has nothing to track, so this only records the intent; freeing space in a later EditSession then writes the on-disk free-space-manager blocks that survive a reopen.

pub fn with_file_space_page_size(&mut self, page_size: u64) -> &mut Self

Set the file-space page size, mirroring HDF5’s H5Pset_file_space_page_size. Recorded in the superblock extension.

pub fn set_attr(&mut self, name: &str, value: AttrValue)

Set an attribute on the root group.

pub fn finish(self) -> Result<Vec<u8>, Error>

Serialize the file to bytes in memory.

pub fn finish_to<W: Write>(self, w: W) -> Result<(), Error>

Serialize the file directly to a Write sink, without first buffering the whole file in memory.

Produces byte-for-byte the same file as finish, but a dataset staged for verbatim chunk streaming (repack’s out-of-core path) has its chunks pulled from the source and written one at a time, so peak memory stays bounded by a single chunk plus the file metadata rather than the whole dataset. The sink is written front-to-back, so it need not be seekable.

pub fn write<P: AsRef<Path>>(self, path: P) -> Result<(), Error>

Serialize and write the file to the given path.

Streams the file to disk (see finish_to), so a repack staging streamed chunks does not hold the whole output in memory.

Trait Implementations

impl Default for FileBuilder

fn default() -> Self

Returns the “default value” for a type.