pub struct DatasetAccess { /* private fields */ }Expand description
The dataset access properties this crate models — libhdf5’s
H5P_DATASET_ACCESS property list, as much of it as affects reading.
virtual_view and
virtual_printf_gap govern how a virtual
dataset’s extent is resolved when it is opened
(H5D__virtual_set_extent_unlim, H5Dvirtual.c:1386);
virtual_prefix and
efile_prefix say where the other files a
dataset’s data lives in are looked for. None of them is stored in the
file: opening a dataset without naming them reads it exactly as
libhdf5’s default dapl does.
Pass one to H5File::dataset_with.
use rust_hdf5::{DatasetAccess, H5File, VirtualView};
let file = H5File::open("vds.h5").unwrap();
let access = DatasetAccess::new()
.virtual_view(VirtualView::LastAvailable)
.virtual_printf_gap(2);
let ds = file.dataset_with("vds", access).unwrap();Implementations§
Source§impl DatasetAccess
impl DatasetAccess
Sourcepub fn new() -> Self
pub fn new() -> Self
A property list holding libhdf5’s defaults —
VirtualView::LastAvailable and a printf gap of 0, the values
H5D_ACS_VDS_VIEW_DEF and H5D_ACS_VDS_PRINTF_GAP_DEF register
(H5Pdapl.c:62, :67).
Sourcepub fn virtual_view(self, view: VirtualView) -> Self
pub fn virtual_view(self, view: VirtualView) -> Self
H5Pset_virtual_view (H5Pdapl.c:1067). The two legal values are the
two VirtualView variants, so the “not a valid bounds option”
argument check that call makes has nothing to reject here.
Sourcepub fn virtual_printf_gap(self, gap: u64) -> Self
pub fn virtual_printf_gap(self, gap: u64) -> Self
H5Pset_virtual_printf_gap (H5Pdapl.c:1207): how many consecutive
missing printf-named source datasets the extent resolution looks past
before it stops. 0 — the default — stops at the first one missing.
u64::MAX is libhdf5’s HSIZE_UNDEF, which that call rejects as “not
a valid printf gap size”; here the rejection surfaces from the open
that uses the property, since a builder method has no way to report
it.
Sourcepub fn view(&self) -> VirtualView
pub fn view(&self) -> VirtualView
H5Pget_virtual_view (H5Pdapl.c:1102).
Sourcepub fn virtual_prefix(self, prefix: impl Into<String>) -> Self
pub fn virtual_prefix(self, prefix: impl Into<String>) -> Self
H5Pset_virtual_prefix (H5Pdapl.c:1478): a directory a virtual
dataset’s source file names are looked for under, before the
virtual file’s own directory and after HDF5_VDS_PREFIX.
It is the third step of H5F_prefix_open_file’s search order
(H5Fint.c:938-950), and it is reached only when HDF5_VDS_PREFIX is
unset or empty: H5D__build_file_prefix reads the environment first
and falls back to this property (H5Dint.c:1077-1082), so an
environment prefix shadows this one outright rather than being tried
alongside it.
A leading ${ORIGIN} stands for the directory holding the virtual
dataset’s own file (H5Dint.c:1105-1113), and "." or "" means “no
prefix” (:1096-1100), both exactly as for the environment variable.
Like the other two, this is a dataset access property that is never stored in the file, and the first open of a virtual dataset fixes it for every open that overlaps it.
Sourcepub fn efile_prefix(self, prefix: impl Into<String>) -> Self
pub fn efile_prefix(self, prefix: impl Into<String>) -> Self
H5Pset_efile_prefix (H5Pdapl.c:1392): a directory the raw data
files of a dataset stored through an external file list are looked
for under.
This one takes no search at all, unlike the other two prefixes:
H5D__efl_read joins the prefix to the stored name with
H5_combine_path and opens exactly that one path (H5Defl.c:315-317).
With no prefix in force the stored name is used as written, so a
relative one resolves against the process’s current directory and
not against the directory holding the HDF5 file — measured under
libhdf5 1.14.6 and 2.0.0: a raw data file next to the HDF5 file is
not found, while the same name under the current directory is.
It shares virtual_prefix’s expansion rules,
because both are built by H5D__build_file_prefix: HDF5_EXTFILE_PREFIX
shadows this property outright rather than merely preceding it
(H5Dint.c:1084-1090), a leading ${ORIGIN} stands for the directory
holding the HDF5 file (:1105-1113), and "." or "" means no prefix
(:1098-1102).
§A second open must name the same one
Where a mismatched virtual_prefix is
silently ignored by the second open, a mismatched external file prefix
is an error: H5D_open compares the expanded prefix against the one
the already-open dataset resolved under and refuses the open when they
differ (H5Dint.c:1533-1545). Expanded, so two opens that differ only
in a property the environment shadows still agree. Closing every
handle releases the answer, and the next open sets its own.
Sourcepub fn printf_gap(&self) -> u64
pub fn printf_gap(&self) -> u64
H5Pget_virtual_printf_gap (H5Pdapl.c:1243) — the value set, not the
one the extent resolution ends up using; see
VirtualView::FirstMissing.
Sourcepub fn virtual_prefix_value(&self) -> Option<&str>
pub fn virtual_prefix_value(&self) -> Option<&str>
H5Pget_virtual_prefix (H5Pdapl.c:1510) — the property as set, before
HDF5_VDS_PREFIX gets to shadow it and before ${ORIGIN} is
expanded. None is H5D_ACS_VDS_PREFIX_DEF, a null prefix
(H5Pdapl.c:72).
Sourcepub fn efile_prefix_value(&self) -> Option<&str>
pub fn efile_prefix_value(&self) -> Option<&str>
H5Pget_efile_prefix (H5Pdapl.c:1422) — the property as set, before
HDF5_EXTFILE_PREFIX gets to shadow it and before ${ORIGIN} is
expanded. None is H5D_ACS_EFILE_PREFIX_DEF, a null prefix
(H5Pdapl.c:90).