hdf5_pure/
file_create_properties.rs

1//! File-creation properties as one reusable value — the `fcpl` analogue.
2
3use crate::file_space_info::FileSpaceStrategy;
4use crate::libver::LibVer;
5
6/// File-creation properties applied when writing a new HDF5 file.
7///
8/// This is the `hdf5-pure` analogue of an HDF5 **file creation property list**
9/// (`fcpl`): one value carrying every creation-time setting, so application code
10/// can define a file layout once and reuse it everywhere it writes, instead of
11/// repeating a builder call chain and keeping the copies in sync.
12///
13/// The `Properties` suffix means the type stands in for one whole HDF5 property
14/// list, so every setting on it has a C counterpart to look up. It is a stand-in
15/// and not a port: a plain `Copy` value, with no handle to create or close, no
16/// runtime property registry, and no setter that can fail. `fcpl` and each
17/// `H5Pset_*` it models are doc aliases, so a search for either lands here.
18///
19/// One setting crosses the class line. `H5Pset_libver_bounds` is officially a
20/// *file access* property, but this crate checks the bound as the file is
21/// written, so [`with_libver_bounds`](Self::with_libver_bounds) lives here with
22/// the other write-time settings rather than on
23/// [`FileAccessProperties`](crate::FileAccessProperties).
24///
25/// Pass it to [`FileBuilder::with_create_properties`](crate::FileBuilder::with_create_properties)
26/// or [`File::create_with_options`](crate::File::create_with_options). The
27/// equivalent [`FileBuilder`](crate::FileBuilder) methods set the same fields one
28/// at a time and interoperate freely with this.
29///
30/// Values are recorded as given and checked when the file is written, not when
31/// the properties are built — the value is inert data, so an illegal page size
32/// is reported by `finish`/`write` rather than here. Note that a non-paged
33/// userblock size is currently **not** validated against HDF5's power-of-two
34/// rule; see the property-support reference for the exact coverage.
35///
36/// See the [property-support reference] for the full property-by-property map.
37///
38/// [property-support reference]: https://github.com/stephenberry/hdf5-pure/blob/main/docs/reference/property-support.md
39///
40/// # Examples
41///
42/// ```no_run
43/// use hdf5_pure::{FileCreateProperties, FileSpaceStrategy};
44///
45/// // Define the layout once...
46/// fn paged_layout() -> FileCreateProperties {
47///     FileCreateProperties::new()
48///         .with_file_space_strategy(FileSpaceStrategy::Page, true, 1)
49///         .with_file_space_page_size(8192)
50/// }
51///
52/// // ...and reuse it across every write path.
53/// let mut builder = hdf5_pure::FileBuilder::new();
54/// builder.with_create_properties(paged_layout());
55/// builder.create_dataset("data").with_f64_data(&[1.0, 2.0]);
56/// builder.write("out.h5").unwrap();
57/// ```
58#[derive(Debug, Clone, Copy, PartialEq, Eq)]
59#[doc(alias = "fcpl")]
60pub struct FileCreateProperties {
61    userblock: u64,
62    libver_bounds: Option<(LibVer, LibVer)>,
63    file_space_strategy: Option<(FileSpaceStrategy, bool, u64)>,
64    file_space_page_size: Option<u64>,
65}
66
67/// Former name of [`FileCreateProperties`].
68#[deprecated(
69    since = "0.26.0",
70    note = "renamed to `FileCreateProperties`: a type standing in for a whole HDF5 property list now carries the `Properties` suffix"
71)]
72pub type FileCreateOptions = FileCreateProperties;
73
74impl FileCreateProperties {
75    /// A value carrying the crate's default creation behavior: no userblock,
76    /// no library-version bounds, and the writer's default file-space handling.
77    pub const fn new() -> Self {
78        Self {
79            userblock: 0,
80            libver_bounds: None,
81            file_space_strategy: None,
82            file_space_page_size: None,
83        }
84    }
85
86    /// Reserve a zero-filled userblock of `size` bytes before the superblock.
87    ///
88    /// HDF5 requires a power of two `>= 512`, or 0 for no userblock; the check
89    /// runs when the file is written. See
90    /// [`FileBuilder::with_userblock`](crate::FileBuilder::with_userblock) for how
91    /// to fill the region afterward.
92    #[doc(alias = "H5Pset_userblock")]
93    pub const fn with_userblock(mut self, size: u64) -> Self {
94        self.userblock = size;
95        self
96    }
97
98    /// Constrain the on-disk format version to `[low, high]`.
99    ///
100    /// This crate writes exactly one format, so the bound is a compatibility
101    /// assertion rather than a format selector — see
102    /// [`FileBuilder::with_libver_bounds`](crate::FileBuilder::with_libver_bounds).
103    ///
104    /// HDF5 classes `H5Pset_libver_bounds` as a *file access* property; it sits
105    /// here because this crate checks the bound at write time.
106    #[doc(alias = "H5Pset_libver_bounds")]
107    pub const fn with_libver_bounds(mut self, low: LibVer, high: LibVer) -> Self {
108        self.libver_bounds = Some((low, high));
109        self
110    }
111
112    /// Set the file-space management strategy, whether free space persists across
113    /// close, and the smallest free-space section tracked.
114    #[doc(alias = "H5Pset_file_space_strategy")]
115    pub const fn with_file_space_strategy(
116        mut self,
117        strategy: FileSpaceStrategy,
118        persist: bool,
119        threshold: u64,
120    ) -> Self {
121        self.file_space_strategy = Some((strategy, persist, threshold));
122        self
123    }
124
125    /// Set the file-space page size, the allocation quantum under
126    /// [`FileSpaceStrategy::Page`].
127    #[doc(alias = "H5Pset_file_space_page_size")]
128    pub const fn with_file_space_page_size(mut self, page_size: u64) -> Self {
129        self.file_space_page_size = Some(page_size);
130        self
131    }
132
133    /// Return the configured userblock size in bytes (0 for none).
134    pub const fn userblock(&self) -> u64 {
135        self.userblock
136    }
137
138    /// Return the configured library-version bounds, if any.
139    pub const fn libver_bounds(&self) -> Option<(LibVer, LibVer)> {
140        self.libver_bounds
141    }
142
143    /// Return the configured file-space strategy, persist flag, and threshold, if
144    /// any.
145    pub const fn file_space_strategy(&self) -> Option<(FileSpaceStrategy, bool, u64)> {
146        self.file_space_strategy
147    }
148
149    /// Return the configured file-space page size, if any.
150    pub const fn file_space_page_size(&self) -> Option<u64> {
151        self.file_space_page_size
152    }
153}
154
155impl Default for FileCreateProperties {
156    fn default() -> Self {
157        Self::new()
158    }
159}
hdf5_pure/file_create_properties.rs

hdf5_pure/
file_create_properties.rs
