Struct RepackOptions

Source

pub struct RepackOptions { /* private fields */ }

Available on crate feature std only.

Expand description

Options controlling a repack.

Built with new and drop_path; the fields are private so a future option is an additive change.

Implementations§

Source §

impl RepackOptions

Source

pub fn new() -> Self

Options that drop nothing — a pure compaction copy.

Source

pub fn drop_path(self, path: &str) -> Self

Omits the object at path from the output, such as "grp/old", and its whole subtree where that object is a group.

path identifies an object whichever way it is spelled, as it does for Group::dataset.

Every path must identify an object in the source, and a path that identifies the root group is outside what a repack drops. repack reports Error::RepackUnsupported for either.

Chainable.

Source

pub fn drop_paths(&self) -> &[String]

Returns the paths this repack omits, each from the root group, in the order they were added.

Source

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

Write the output in the format these bounds select, rather than in the source’s own format. Same meaning as FileBuilder::with_libver_bounds: high picks the format, and content it cannot express is refused with FormatError::LibverTooOldForContent rather than written in a newer one.

A repack carries the source’s format forward by default, because compacting a file is not a request to re-target it — but it does upgrade where the content leaves no choice, since a chunked dataset needs the 1.10 chunk indices and there is no older one this crate writes. Set this to make the format a guarantee instead: an Earliest..=V18 bound turns that upgrade into an error, so a file that must stay loadable by an old reader says so rather than finding out later.

use hdf5_pure::{LibVer, RepackOptions, repack};

// Fails rather than producing a file MATLAB before R2021b cannot open.
let options = RepackOptions::new().with_libver_bounds(LibVer::Earliest, LibVer::V18);
repack("data.mat", "compact.mat", &options)?;

Chainable.

Source

pub fn libver_bounds(&self) -> Option<(LibVer, LibVer)>

The library-version bounds this repack will write to, or None when it carries the source’s format forward.

Source

pub fn reject_unknown_messages_only_a_writer_must_understand(self) -> Self

Rejects a source holding an object header message of a type this crate cannot name that only a decoder with write access must understand.

The flag is H5O_MSG_FLAG_FAIL_IF_UNKNOWN_AND_OPEN_FOR_WRITE, bit 3 of the message record’s flags. The source is opened read-only either way, and this option parses its object headers as a writer does, so repack reports FormatError::UnsupportedMessage with the message’s type before any byte reaches the destination. A message flagged H5O_MSG_FLAG_FAIL_IF_UNKNOWN_ALWAYS is rejected with this option and without it.

The default is what h5repack does. h5repack also reads its input read-only, and this crate rebuilds every object without a message it cannot name. This option is this crate’s own, and h5repack has no counterpart for it. Set it where a repack must fail on a message the source marked for a decoder with write access.

§Examples

use hdf5_pure::{File, RepackOptions, repack};

// Rejects a source holding a message flagged for a decoder with write access.
let options = RepackOptions::new().reject_unknown_messages_only_a_writer_must_understand();
repack(&src, &dst, &options)?;

assert_eq!(File::open(&dst)?.dataset("values")?.read_i32()?, vec![1, 2, 3]);