Enum FormatError 

#[non_exhaustive]
pub enum FormatError {
    SignatureNotFound,
    UnsupportedVersion(u8),
    UnexpectedEof {
        expected: usize,
        available: usize,
    },
    InvalidOffsetSize(u8),
    InvalidLengthSize(u8),
    InvalidObjectHeaderSignature,
    InvalidObjectHeaderVersion(u8),
    UnsupportedMessage(u16),
    InvalidDatatypeClass(u8),
    InvalidDatatypeVersion {
        class: u8,
        version: u8,
    },
    InvalidStringPadding(u8),
    InvalidCharacterSet(u8),
    InvalidByteOrder(u8),
    InvalidReferenceType(u8),
    InvalidFileSpaceStrategy(u8),
    UnsupportedFileSpaceInfoVersion(u8),
    InvalidFileSpacePageSize(u64),
    UserblockNotPageAligned(u64, u64),
    InvalidUserblockSize(u64),
    UserblockContentTooLarge {
        content: u64,
        userblock: u64,
    },
    InvalidFreeSpaceManager,
    EnumBaseNotInteger,
    EnumMemberValueSize(String, u32, usize),
    EnumMemberValueRange(String, i64, u32),
    InvalidCompoundSize,
    EmptyCompoundType,
    DuplicateCompoundField(String),
    CompoundFieldOutOfBounds {
        name: String,
        offset: u64,
        field_size: u32,
        compound_size: u32,
    },
    CompoundFieldOverlap {
        first: String,
        second: String,
    },
    CompoundFieldMissing(String),
    CompoundFieldTypeMismatch(String),
    InvalidDataspaceVersion(u8),
    InvalidDataspaceType(u8),
    InvalidLayoutVersion(u8),
    InvalidLayoutClass(u8),
    NoDataAllocated,
    TypeMismatch {
        expected: &'static str,
        actual: &'static str,
    },
    DataSizeMismatch {
        expected: usize,
        actual: usize,
    },
    InvalidLocalHeapSignature,
    InvalidLocalHeapVersion(u8),
    InvalidBTreeSignature,
    InvalidBTreeNodeType(u8),
    InvalidSymbolTableNodeSignature,
    InvalidSymbolTableNodeVersion(u8),
    PathNotFound(String),
    InvalidLinkVersion(u8),
    InvalidLinkType(u8),
    InvalidLinkInfoVersion(u8),
    InvalidBTreeV2Signature,
    InvalidBTreeV2Version(u8),
    InvalidFractalHeapSignature,
    InvalidFractalHeapVersion(u8),
    InvalidHeapIdType(u8),
    HugeObjectNotFound(u64),
    UnexpectedHugeObjectBTree {
        tree_type: u8,
        record_size: usize,
        required: usize,
    },
    UnsupportedFilteredHeapObject,
    UnsupportedVirtualLayout,
    InvalidAttributeVersion(u8),
    InvalidAttributeInfoVersion(u8),
    InvalidSharedMessageVersion(u8),
    InvalidGlobalHeapSignature,
    InvalidGlobalHeapVersion(u8),
    GlobalHeapObjectNotFound {
        collection_address: u64,
        index: u16,
    },
    VlDataError(String),
    VariableLengthElementLimitExceeded {
        limit: usize,
        actual: u64,
    },
    VariableLengthByteLimitExceeded {
        limit: usize,
        required: u64,
    },
    SerializationError(String),
    DatasetMissingData,
    DatasetMissingShape,
    ShapeDataMismatch {
        expected: usize,
        actual: usize,
        element_size: usize,
    },
    InvalidChunkGeometry(&'static str),
    InvalidFilterPipelineVersion(u8),
    UnsupportedFilter(u16),
    FilterError(String),
    CompressionError(String),
    Fletcher32Mismatch {
        expected: u32,
        computed: u32,
    },
    ChunkedReadError(String),
    ChunkAssemblyError(String),
    ChecksumMismatch {
        expected: u32,
        computed: u32,
    },
    NestingDepthExceeded,
    DuplicateDatasetName(String),
    UnsupportedZfp(String),
    ValueTooLargeForPlatform {
        value: u64,
        target: &'static str,
    },
    OffsetOverflow {
        offset: u64,
        length: u64,
    },
    Source(String),
    LibverBoundsUnsatisfiable {
        writes: &'static str,
        requested_low: &'static str,
        requested_high: &'static str,
    },
    InvalidObjectReference(u64),
    UnsupportedFillValueVersion(u8),
    FillValueSizeMismatch {
        expected: usize,
        actual: usize,
    },
    AttributeMessageTooLarge {
        name: String,
        size: usize,
    },
    ObjectHeaderMessageTooLarge {
        message_type: u16,
        size: usize,
    },
    AttributeFieldTooLong {
        name: String,
        field: &'static str,
        size: usize,
        limit: usize,
    },
    DenseAttributeHeapTooLarge {
        limit: u64,
    },
}

Errors that can occur when parsing HDF5 binary format structures.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

SignatureNotFound

The HDF5 magic signature was not found at any valid offset.

UnsupportedVersion(u8)

The superblock version is not supported.

UnexpectedEof

Unexpected end of data.

Fields

expected: usize

Number of bytes expected.

available: usize

Number of bytes actually available.

InvalidOffsetSize(u8)

Invalid offset size (must be 2, 4, or 8).

InvalidLengthSize(u8)

Invalid length size (must be 2, 4, or 8).

InvalidObjectHeaderSignature

Invalid object header signature.

InvalidObjectHeaderVersion(u8)

Invalid object header version.

UnsupportedMessage(u16)

Unknown message type that is marked as must-understand.

InvalidDatatypeClass(u8)

Invalid datatype class.

InvalidDatatypeVersion

Invalid datatype version for a given class.

Fields

class: u8

The type class.

version: u8

The version found.

InvalidStringPadding(u8)

Invalid string padding type.

InvalidCharacterSet(u8)

Invalid character set.

InvalidByteOrder(u8)

Invalid byte order.

InvalidReferenceType(u8)

Invalid reference type.

InvalidFileSpaceStrategy(u8)

Invalid file-space management strategy code in a File Space Info message.

UnsupportedFileSpaceInfoVersion(u8)

Unsupported File Space Info message version (only version 1 is handled).

InvalidFileSpacePageSize(u64)

A paged file-space strategy was requested with a page size the writer cannot use: it must be a power of two of at least 512 bytes.

UserblockNotPageAligned(u64, u64)

A paged file-space strategy was requested alongside a userblock that is not a whole number of pages. File-space pages are measured from the file base, so the two boundaries coincide only when the userblock divides by the page size: (userblock bytes, page size).

InvalidUserblockSize(u64)

A userblock size the format does not define: it must be zero, or a power of two of at least 512 bytes. A reader looks for the superblock at 0, 512, 1024, and so on doubling, so any other size produces a file nothing can open.

UserblockContentTooLarge

More userblock content was supplied than the userblock region holds. The overflow would displace the superblock, so it is refused rather than truncated.

Fields

content: u64

Bytes supplied.

userblock: u64

Bytes the userblock region holds.

InvalidFreeSpaceManager

A free-space manager block (FSHD/FSSE) is malformed.

EnumBaseNotInteger

An enumeration datatype was built over a base type that is not an integer. HDF5 enumerations must have a fixed-point base.

EnumMemberValueSize(String, u32, usize)

An enumeration member’s value does not occupy exactly the base type’s size: (member name, expected bytes, actual bytes).

EnumMemberValueRange(String, i64, u32)

An enumeration member’s integer value does not fit in the base type: (member name, value, base size in bytes).

InvalidCompoundSize

A compound datatype has a zero total size.

EmptyCompoundType

A compound datatype contains no fields.

DuplicateCompoundField(String)

A compound datatype contains the same field name more than once.

CompoundFieldOutOfBounds

A compound field extends past the declared compound size.

Fields

name: String

Field name.

offset: u64

Field byte offset.

field_size: u32

Field size in bytes.

compound_size: u32

Declared compound size in bytes.

CompoundFieldOverlap

Two compound fields overlap.

Fields

first: String

Earlier field in byte order.

second: String

Later field in byte order.

CompoundFieldMissing(String)

A named compound field was not present.

CompoundFieldTypeMismatch(String)

A compound field has an incompatible datatype.

InvalidDataspaceVersion(u8)

Invalid dataspace version.

InvalidDataspaceType(u8)

Invalid dataspace type.

InvalidLayoutVersion(u8)

Invalid data layout version.

InvalidLayoutClass(u8)

Invalid data layout class.

NoDataAllocated

No data allocated for contiguous layout.

TypeMismatch

Type mismatch when reading data.

Fields

expected: &'static str

Expected type description.

actual: &'static str

Actual type description.

DataSizeMismatch

Data size mismatch.

Fields

expected: usize

Expected size in bytes.

actual: usize

Actual size in bytes.

InvalidLocalHeapSignature

Invalid local heap signature.

InvalidLocalHeapVersion(u8)

Invalid local heap version.

InvalidBTreeSignature

Invalid B-tree v1 signature.

InvalidBTreeNodeType(u8)

Invalid B-tree node type.

InvalidSymbolTableNodeSignature

Invalid symbol table node signature.

InvalidSymbolTableNodeVersion(u8)

Invalid symbol table node version.

PathNotFound(String)

Path not found during group traversal.

InvalidLinkVersion(u8)

Invalid Link message version.

InvalidLinkType(u8)

Invalid link type code.

InvalidLinkInfoVersion(u8)

Invalid Link Info message version.

InvalidBTreeV2Signature

Invalid B-tree v2 signature.

InvalidBTreeV2Version(u8)

Invalid B-tree v2 version.

InvalidFractalHeapSignature

Invalid fractal heap signature.

InvalidFractalHeapVersion(u8)

Invalid fractal heap version.

InvalidHeapIdType(u8)

Invalid heap ID type.

HugeObjectNotFound(u64)

A fractal-heap “huge” object’s heap ID referenced a B-tree key that is not present in the heap’s huge-objects v2 B-tree.

UnexpectedHugeObjectBTree

A fractal heap’s huge-objects v2 B-tree is not the indirectly accessed, non-filtered layout (record type 1) this reader decodes: either the tree declares a different record type, or its records are too short to hold that one. Reading its records as that layout would decode an object ID out of another field’s bytes.

Fields

tree_type: u8

The record type the B-tree declares.

record_size: usize

The record size the B-tree declares, in bytes.

required: usize

The bytes a type-1 record needs: address + length + object ID.

UnsupportedFilteredHeapObject

A fractal-heap object lives in an I/O-filter-encoded heap (filtered managed or huge storage), whose filtered bytes this reader does not decode. Link and attribute heaps are never filtered, so this does not arise for them.

UnsupportedVirtualLayout

A dataset uses the Virtual (VDS) data layout, which maps its elements to regions of other datasets, possibly in other files. This reader does not yet resolve virtual mappings, so such a dataset is refused rather than read as empty or wrong.

InvalidAttributeVersion(u8)

Invalid attribute message version.

InvalidAttributeInfoVersion(u8)

Invalid Attribute Info message version.

InvalidSharedMessageVersion(u8)

Invalid shared message version.

InvalidGlobalHeapSignature

Invalid global heap collection signature.

InvalidGlobalHeapVersion(u8)

Invalid global heap version.

GlobalHeapObjectNotFound

Global heap object not found.

Fields

collection_address: u64

Address of the collection.

index: u16

Index that was not found.

VlDataError(String)

Variable-length data error.

VariableLengthElementLimitExceeded

A variable-length read exceeded its configured element limit.

Fields

limit: usize

Maximum number of elements permitted by the caller.

actual: u64

Number of elements present in the selected data.

VariableLengthByteLimitExceeded

A variable-length read exceeded its configured payload-byte limit.

Fields

limit: usize

Maximum number of payload bytes permitted by the caller.

required: u64

Number of payload bytes required by the selected data.

SerializationError(String)

Serialization error.

DatasetMissingData

Dataset is missing data.

DatasetMissingShape

Dataset is missing shape.

ShapeDataMismatch

The dataset’s element count implied by its shape does not match the amount of data supplied (shape.product() * element_size != data.len()).

Fields

expected: usize

Number of data bytes the shape requires (product(shape) * element_size).

actual: usize

Number of data bytes actually supplied.

element_size: usize

Size in bytes of one element (the dataset’s datatype size). Always non-zero; used to report the mismatch in elements as well as bytes.

InvalidChunkGeometry(&'static str)

A chunked/filtered/extensible dataset’s chunk geometry is invalid — for example chunk dimensions whose rank disagrees with the shape, a zero chunk dimension, a maximum shape whose rank disagrees with the shape or that is smaller than the current shape, or chunking requested on a scalar dataset. Reported up front so a malformed request is refused instead of panicking in the chunk splitter or producing an unreadable dataset. The payload is a human-readable reason.

InvalidFilterPipelineVersion(u8)

Invalid filter pipeline version.

UnsupportedFilter(u16)

Unsupported filter ID.

FilterError(String)

Filter processing error, including a stream that failed to decode. Every filter in the pipeline — shuffle, scale-offset, LZF, deflate — reports a bad chunk with this variant, so “this chunk did not decode” is one match arm rather than one per compressor. The payload names the filter.

CompressionError(String)

Compression error.

Fletcher32Mismatch

Fletcher32 checksum mismatch.

Fields

expected: u32

Expected checksum.

computed: u32

Computed checksum.

ChunkedReadError(String)

Chunked dataset read error.

ChunkAssemblyError(String)

Chunk assembly error.

ChecksumMismatch

CRC32C checksum mismatch.

Fields

expected: u32

The checksum stored in the file.

computed: u32

The checksum we computed.

NestingDepthExceeded

Maximum nesting/continuation depth exceeded (malformed data protection).

DuplicateDatasetName(String)

Duplicate dataset name detected during parallel metadata merge.

UnsupportedZfp(String)

ZFP filter configuration is invalid (e.g. missing element type, rank out of range).

ValueTooLargeForPlatform

A file-derived 64-bit value (an offset, length, size, or element count) does not fit in the target integer type on this platform. This is the guard that replaces silent as usize / as u32 truncation: on a 32-bit host, usize is 32 bits, so an HDF5 offset or length above usize::MAX would otherwise wrap and read the wrong bytes. The original value is preserved for diagnostics, and target names the type we tried to narrow to (e.g. "usize", "u32").

Fields

value: u64

The original 64-bit value read from the file.

target: &'static str

The platform integer type the value could not fit into.

OffsetOverflow

Two file-derived values (typically an offset and a length) overflow u64 when added to form a slice bound. Reported instead of wrapping so a malformed file cannot produce a wrapped or out-of-range index.

Fields

offset: u64

First operand (typically the base offset/address).

length: u64

Second operand (typically the length/size).

Source(String)

A random-access byte source failed to supply the requested bytes. The string carries a backend-specific reason (e.g. an underlying std::io::Error rendered to text), so this stays no_std/alloc-friendly and free of an std::io dependency.

LibverBoundsUnsatisfiable

The library-version bounds requested via FileBuilder::with_libver_bounds cannot be satisfied. This crate’s writer emits exactly one on-disk format (the version 3 / HDF5 1.10 superblock), so a bound that excludes it — an upper bound older than 1.10, or a lower bound newer than 1.10 — is unsatisfiable. The fields carry the format produced and the bounds asked for, as LibVer::name labels.

Fields

writes: &'static str

The library-version label of the format this crate writes.

requested_low: &'static str

The requested lower bound.

requested_high: &'static str

The requested upper bound.

InvalidObjectReference(u64)

An HDF5 object reference (H5R_OBJECT) could not be resolved to an object: the stored address is null or undefined (HADDR_UNDEF), or it does not point at a group or dataset object header. The payload is the stored (base-relative) address, preserved for diagnostics.

UnsupportedFillValueVersion(u8)

A Fill Value message (0x0005) has an on-disk version this crate does not recognize (only 1, 2, and 3 are defined). The payload is the version byte found.

FillValueSizeMismatch

A user-supplied fill value’s byte width does not match the dataset’s datatype element size (for example a u8 fill value on an i32 dataset). The fields carry the datatype element size and the fill value size, both in bytes.

Fields

expected: usize

The dataset datatype’s element size in bytes.

actual: usize

The supplied fill value’s size in bytes.

AttributeMessageTooLarge

An attribute’s serialized message is larger than the version 2 object header’s 2-byte message-size field can describe, so it cannot be stored as a compact (in-header) attribute. Refused rather than written, because a truncated size field would desynchronize every message after it. The fields carry the attribute name and its serialized message size in bytes; the limit is OBJECT_HEADER_MESSAGE_MAX.

A backstop rather than an outcome you should expect to see: the whole-file writer selects dense (fractal-heap) storage for exactly the attributes that would trip this, so no input reaches it today. It stays because the limit it describes is a real property of the object header, and any future path that must keep an attribute compact needs it.

Fields

name: String

The attribute’s name.

size: usize

The attribute message’s serialized size in bytes.

ObjectHeaderMessageTooLarge

An object-header message is larger than the version 2 object header’s 2-byte message-size field can describe. This is the whole-file writer’s backstop against emitting a truncated size field, covering every message it builds; callers that can name the offending object (for example an attribute) report a more specific error first. The in-place editor encodes headers separately and refuses the same condition with Error::EditUnsupported. The fields carry the message type code and the message’s serialized size in bytes; the limit is OBJECT_HEADER_MESSAGE_MAX.

Fields

message_type: u16

The header message’s type code (see the HDF5 message type table).

size: usize

The message’s serialized size in bytes.

AttributeFieldTooLong

An attribute’s name, datatype or dataspace is longer than the attribute message can describe: each of the three has a 2-byte length field, so a longer one would truncate and produce a message that decodes as something else. Refused rather than written.

This bounds the attribute’s description, not its data. An attribute whose data is arbitrarily large is written to dense storage as a fractal-heap huge object.

Reported by the whole-file writer (including through repack), which sends any attribute too large for an object-header message to dense storage and so reaches this check.

In practice field is always "name". Every attribute this crate writes is built from an AttrValue — including the ones repack carries over, which it refuses outright if it cannot represent them — and no variant of it produces a datatype past 20 bytes or a dataspace past 12, whatever the data. The other two are still checked, because the message encodes all three lengths the same way, and named rather than merged so that a datatype which does one day reach the limit is diagnosable from the error rather than mistaken for a long name.

Fields

name: String

The attribute’s name.

field: &'static str

Which of the message’s three 2-byte length fields overflowed: "name", "datatype" or "dataspace". Diagnostic detail rather than a discriminator to branch on, since only "name" is reachable today.

size: usize

That field’s encoded length in bytes.

limit: usize

The largest length the message can describe, in bytes.

DenseAttributeHeapTooLarge

An object’s attributes need more space than a dense attribute heap can address: its offsets are 40 bits wide, so the blocks holding the attributes cannot span more than limit bytes between them. Reaching this takes about a terabyte of attributes on a single object.

A set that fits the heap but not the host reports FormatError::ValueTooLargeForPlatform instead, so the limit named here is always the one that actually applied.

Fields

limit: u64

The heap address space, in bytes.

Trait Implementations

impl Clone for FormatError

fn clone(&self) -> FormatError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FormatError

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

Formats the value using the given formatter.

impl Display for FormatError

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

Formats the value using the given formatter.

impl Eq for FormatError

impl Error for FormatError

Available on crate feature std only.

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<FormatError> for Error

Available on crate feature std only.

fn from(e: FormatError) -> Self

Converts to this type from the input type.

impl From<FormatError> for MatError

fn from(e: FormatError) -> Self

Converts to this type from the input type.

impl PartialEq for FormatError

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for FormatError