Enum Selection

Source

pub enum Selection {
    None,
    All,
    Hyperslab {
        rank: usize,
        form: Hyperslab,
    },
    Points(PointSelection),
}

Expand description

A decoded H5S dataspace selection.

Variants§

§

None

H5S_SEL_NONE: no elements selected.

§

All

H5S_SEL_ALL: every element of whatever dataspace this selection is later bound against.

§

Hyperslab

H5S_SEL_HYPERSLABS.

Fields

§rank: usize

§form: Hyperslab

§

Implementations§

Source §

impl Selection

Source

pub fn decode(buf: &[u8]) -> FormatResult<(Self, usize)>

Decode one serialized selection from the front of buf.

Returns the selection and the number of bytes consumed; buf may have trailing bytes belonging to whatever follows (a VDS mapping entry decodes a source selection immediately followed by a virtual selection out of the same buffer, for instance).

Source

pub fn to_boxes(&self, dims: &[u64]) -> FormatResult<Vec<(Vec<u64>, Vec<u64>)>>

Decompose this selection into (start, count) boxes — each dims.len() elements wide — whose union is exactly the selected elements, with no overlap between boxes. dims supplies the full extent for Selection::All and must match a hyperslab’s rank; it is not otherwise consulted (coordinates are absolute, so this does not clip an out-of-range block against dims — a caller that needs that validates it itself).

Err for a regular hyperslab whose count or block holds UNLIMITED: an unbounded dimension cannot become a finite box without a growable-dataset extent this call does not have.

Source

pub fn encode(&self) -> FormatResult<Vec<u8>>

Encode this selection into its H5S_select_serialize wire form (H5Sselect.c and the per-type callbacks in H5Sall.c/H5Snone.c/ H5Spoint.c/H5Shyper.c).

This module has no file context (no libver bounds), so it always targets the version libhdf5 itself picks for the default low format-version bound (H5F_LIBVER_V18, H5F_ACS_LIBVER_LOW_BOUND_DEF in H5Pfapl.c) with no huge counts or coordinates: version 1 for points, and version 1 (the block-list wire form) for hyperslabs — H5S__hyper_get_version_enc_size picks version 1 for any hyperslab (regular or not) whenever the low bound is below H5F_LIBVER_V112, so Hyperslab::Regular is decomposed into blocks first (Selection::to_boxes’s own expansion) rather than written with the version-2/3 REGULAR flag. Confirmed byte-for-byte against libhdf5-captured H5Sencode2 images — see selection_matches_libhdf5_image in this module’s tests.

A selection that cannot be expressed in that version-1, 4-byte-wide form — more than u32::MAX points/blocks, or a coordinate that does not fit u32 — is FormatError::UnsupportedFeature, not silently truncated.

Source

pub fn unlim_dim(&self) -> Option<usize>

The one dimension this selection grows in, or None when it is bounded — H5S_get_select_unlim_dim. Only a regular hyperslab can carry H5S_UNLIMITED at all (H5Sselect_hyperslab refuses it for every other form), so every other selection answers None.

Source

pub fn clip_unlimited(&self, clip_size: u64) -> FormatResult<Self>

This selection with its unlimited dimension clipped to an extent of clip_size — H5S_hyper_clip_unlim (H5Shyper.c), which is how a virtual dataset’s unlimited mapping becomes the finite one a read walks.

The result is a block list rather than a regular hyperslab because the last block may be cut in half by the extent: upstream builds a span tree and intersects it with clip_size for exactly that case, and an explicit block list is the same set of elements. A selection that clips away to nothing becomes Selection::None; a bounded selection is returned unchanged.

Source

pub fn bounds(&self) -> Option<(Vec<u64>, Vec<u64>)>

The inclusive bounding box of the selection — H5Sget_select_bounds — or None when the selection has no bounds of its own: Selection::All takes the extent it is bound against, Selection::None selects nothing, and a regular hyperslab with an UNLIMITED count or block has no upper bound until a growable extent supplies one.