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_create_properties( &mut self, properties: FileCreateProperties, ) -> &mut Self

Apply every creation property in properties at once — the fcpl analogue of handing a property list to H5Fcreate.

Each property is applied exactly as the individual setter would, so this overwrites any value set individually before the call. The two spellings interoperate: apply a shared FileCreateProperties first, then override one property for this file.

pub fn with_create_options( &mut self, properties: FileCreateProperties, ) -> &mut Self

👎Deprecated since 0.26.0:

renamed to with_create_properties

Former name of with_create_properties.

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

Set the userblock size in bytes: zero (no userblock), or a power of two of at least 512. The region is filled with zeros.

Any other size is refused by finish / finish_to / write with FormatError::InvalidUserblockSize. The size is the superblock’s base address, and a reader scans for the signature at 0, 512, 1024, and so on doubling — so an unaligned size would hide the superblock where nothing looks for it.

To put something in it, prefer with_userblock_content, which works on every output path. Patching the bytes afterwards only works with the buffered finish; the streaming finish_to / write have already emitted the region by the time they return.

pub fn with_userblock_content(&mut self, content: &[u8]) -> &mut Self

Set the bytes that occupy the head of the userblock region, so the writer emits them as part of the file. The remainder of the region stays zero-filled, and content longer than the userblock set by with_userblock is refused by every output path — finish, finish_to, and write — with FormatError::UserblockContentTooLarge.

Because the userblock leads the file in address order, this is what lets a wrapper format’s header — MATLAB v7.3’s, for instance — be produced by the non-seekable finish_to with no second pass.

Example

use hdf5_pure::FileBuilder;

let mut builder = FileBuilder::new();
builder.with_userblock(512);
builder.with_userblock_content(b"my wrapper format's header");
builder.create_dataset("x").with_f64_data(&[1.0, 2.0]);

let bytes = builder.finish().unwrap();
assert_eq!(&bytes[..26], b"my wrapper format's header");
// The rest of the region is zero-filled, and the HDF5 signature follows it.
assert!(bytes[26..512].iter().all(|&b| b == 0));
assert_eq!(&bytes[512..516], b"\x89HDF");

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 File::open_rw 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 and never seeked, so it can be a socket or a pipe as readily as a file. That is possible because the writer computes every object’s address before it emits a byte, rather than seeking back to patch addresses the way a backpatching writer would.

A failure partway leaves whatever was already written on the sink. With a non-seekable sink there is nothing to roll back, so a caller needing all-or-nothing should write to a temporary path and rename on success.

Example

use hdf5_pure::FileBuilder;

let build = || {
    let mut b = FileBuilder::new();
    b.create_dataset("x").with_f64_data(&[1.0, 2.0, 3.0]);
    b
};

let mut streamed: Vec<u8> = Vec::new();
build().finish_to(&mut streamed).unwrap();
assert_eq!(build().finish().unwrap(), streamed);

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.