Struct FileCreateProperties 

pub struct FileCreateProperties { /* private fields */ }

File-creation properties applied when writing a new HDF5 file.

This is the hdf5-pure analogue of an HDF5 file creation property list (fcpl): one value carrying every creation-time setting, so application code can define a file layout once and reuse it everywhere it writes, instead of repeating a builder call chain and keeping the copies in sync.

The Properties suffix means the type stands in for one whole HDF5 property list, so every setting on it has a C counterpart to look up. It is a stand-in and not a port: a plain Copy value, with no handle to create or close, no runtime property registry, and no setter that can fail. fcpl and each H5Pset_* it models are doc aliases, so a search for either lands here.

One setting crosses the class line. H5Pset_libver_bounds is officially a file access property, but this crate checks the bound as the file is written, so with_libver_bounds lives here with the other write-time settings rather than on FileAccessProperties.

Pass it to FileBuilder::with_create_properties or File::create_with_options. The equivalent FileBuilder methods set the same fields one at a time and interoperate freely with this.

Values are recorded as given and checked when the file is written, not when the properties are built — the value is inert data, so an illegal page size is reported by finish/write rather than here. Note that a non-paged userblock size is currently not validated against HDF5’s power-of-two rule; see the property-support reference for the exact coverage.

See the property-support reference for the full property-by-property map.

Examples

use hdf5_pure::{FileCreateProperties, FileSpaceStrategy};

// Define the layout once...
fn paged_layout() -> FileCreateProperties {
    FileCreateProperties::new()
        .with_file_space_strategy(FileSpaceStrategy::Page, true, 1)
        .with_file_space_page_size(8192)
}

// ...and reuse it across every write path.
let mut builder = hdf5_pure::FileBuilder::new();
builder.with_create_properties(paged_layout());
builder.create_dataset("data").with_f64_data(&[1.0, 2.0]);
builder.write("out.h5").unwrap();

Implementations

impl FileCreateProperties

pub const fn new() -> Self

A value carrying the crate’s default creation behavior: no userblock, no library-version bounds, and the writer’s default file-space handling.

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

Reserve a zero-filled userblock of size bytes before the superblock.

HDF5 requires a power of two >= 512, or 0 for no userblock; the check runs when the file is written. See FileBuilder::with_userblock for how to fill the region afterward.

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

Constrain the on-disk format version to [low, high].

high selects the format: Earliest..=V18 writes the HDF5 1.8 one and anything reaching 1.10 writes the 1.10 one, so this changes the bytes of every file the properties are applied to. Content the chosen format cannot express is refused with FormatError::LibverTooOldForContent rather than silently upgraded — see FileBuilder::with_libver_bounds for which content that is.

low only rules formats out, licensing newer encodings without requiring them, so a lower bound of V112, V114 or LATEST writes the 1.10 format rather than being refused — provided high reaches it. An inverted range such as V114..=V110 is refused with FormatError::LibverBoundsUnsatisfiable.

HDF5 classes H5Pset_libver_bounds as a file access property; it sits here because this crate resolves the bound at write time.

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

Set the file-space management strategy, whether free space persists across close, and the smallest free-space section tracked.

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

Set the file-space page size, the allocation quantum under FileSpaceStrategy::Page.

pub const fn userblock(&self) -> u64

Return the configured userblock size in bytes (0 for none).

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

Return the configured library-version bounds, if any.

pub const fn file_space_strategy( &self, ) -> Option<(FileSpaceStrategy, bool, u64)>

Return the configured file-space strategy, persist flag, and threshold, if any.

pub const fn file_space_page_size(&self) -> Option<u64>

Return the configured file-space page size, if any.

Trait Implementations

impl Clone for FileCreateProperties

fn clone(&self) -> FileCreateProperties

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for FileCreateProperties

impl Debug for FileCreateProperties

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

Formats the value using the given formatter.

impl Default for FileCreateProperties

fn default() -> Self

Returns the “default value” for a type.

impl Eq for FileCreateProperties

impl PartialEq for FileCreateProperties

fn eq(&self, other: &FileCreateProperties) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for FileCreateProperties