Module selection 

Serialized H5S dataspace-selection decoder.

H5S_select_deserialize (H5Sselect.c) and its per-type callbacks (H5Sall.c, H5Snone.c, H5Shyper.c) define a small self-describing wire format for “which elements of a dataspace are selected”. It shows up embedded inside other structures — a Virtual Dataset mapping entry (H5Dvirtual.c H5D__virtual_load_layout) carries two of them per mapping, and a region reference embeds one too — so this module decodes only the selection bytes themselves and knows nothing about either caller.

Binary layout, common header:

sel_type: u32 LE (0 = none, 1 = points, 2 = hyperslabs, 3 = all)

followed by a type-specific body.

All / None body (version is always 1):

version:  u32 LE (= 1)
reserved: 8 bytes

Point body (H5S__point_deserialize, H5Spoint.c):

version: u32 LE (1 or 2)
if version >= 2: enc_size: 1 byte (2, 4, or 8 bytes)
else (version == 1): padding: 4 bytes, length: 4 bytes, enc_size = 4
rank: u32 LE
num_points: enc_size bytes LE
num_points * rank * { coordinate }, each enc_size bytes LE (point-major,
coordinate-minor — point 0's rank coordinates, then point 1's, ...)

The version-1 length field records the byte count from rank to the end of the point list (8 + num_points * rank * 4); this module does not validate it on decode (H5S__point_deserialize doesn’t either), but Selection::encode reproduces the exact value libhdf5 writes there, since a byte-for-byte comparison against a captured image needs it.

Hyperslab body:

version: u32 LE (1, 2, or 3)
if version >= 2: flags: 1 byte (bit 0 = REGULAR)
if version >= 3: enc_size: 1 byte (tag 0x02/0x04/0x08 => 2/4/8 bytes)
else if version == 2: reserved: 4 bytes, enc_size = 8
else (version == 1): reserved: 8 bytes, enc_size = 4
rank: u32 LE
if the REGULAR flag is set (only possible for version >= 2):
  rank * { start, stride, count, block }, each enc_size bytes LE
  (an all-ones count or block of that width means H5S_UNLIMITED)
else (block list, any version):
  num_blocks: enc_size bytes LE
  num_blocks * { rank * start_coord, rank * end_coord }, each
  enc_size bytes LE (absolute element coordinates, end inclusive,
  blocks combined by union)

Empirically confirmed against libhdf5 1.14.6 (h5py’s VirtualLayout writes hyperslab selections in the version-1 block-list form — with exactly one block — even for a selection that is mathematically a single regular block; see the test h5py_single_block_selection_is_version_one).

Structs

HyperslabBlock

One block of a hyperslab block-list selection: inclusive start..=end element coordinates, one pair per dimension.

PointSelection

An explicit list of selected element coordinates (H5S_SEL_POINTS): one rank-length coordinate vector per point, in selection order. Selection order is significant for a pointwise iterator (it is the linear order in which elements are visited), so callers must not reorder points.

RegularHyperslab

A regular (start, stride, count, block) hyperslab: one tuple per dimension. count/block may hold UNLIMITED.

Enums

Hyperslab

The two wire forms a hyperslab selection can take (H5S__hyper_deserialize, H5Shyper.c): a single compact (start, stride, count, block) tuple per dimension, or an explicit list of blocks combined by union. libhdf5 always writes the block-list form for a selection made of exactly one block — including h5py’s VirtualLayout — so both forms are real on-disk data, not just alternates on paper.

Selection

A decoded H5S dataspace selection.

Constants

UNLIMITED

Sentinel marking a hyperslab count or block value as unlimited/growable (H5S_UNLIMITED, numerically HSIZE_UNDEF — H5Spublic.h / H5public.h).