#[non_exhaustive]pub enum FormatError {
Show 111 variants
SignatureNotFound,
UnsupportedVersion(u8),
UnexpectedEof {
expected: usize,
available: usize,
},
InvalidOffsetSize(u8),
InvalidLengthSize(u8),
InvalidObjectHeaderSignature,
InvalidObjectHeaderVersion(u8),
UnsupportedMessage(u16),
InvalidDatatypeClass(u8),
InvalidDatatypeVersion {
class: u8,
version: u8,
},
ZeroSizedDatatype {
class: 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),
UnreadableFillValue,
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,
UnsupportedExternalStorage,
InvalidAttributeVersion(u8),
InvalidAttributeInfoVersion(u8),
InvalidSharedMessageVersion(u8),
InvalidAttributeFlags(u8),
UnsupportedSohmReference,
InvalidSohmTableVersion(u8),
InvalidSohmIndexCount(u8),
InvalidSohmTableSignature,
InvalidSohmListSignature,
InvalidSohmIndexKind(u8),
InvalidSohmBTreeType(u8),
InvalidSohmRecordLocation(u8),
SohmIndexMissing(u16),
SharedMessageMissing {
object_header_address: u64,
message_type: u16,
},
UnresolvedSharedMessage(u16),
UnknownCommittedDatatype(String),
CommittedDatatypeMismatch {
path: String,
user: String,
},
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: NonZeroUsize,
},
InvalidChunkGeometry(&'static str),
InvalidFilterPipelineVersion(u8),
UnsupportedFilter(u16),
FilterError(String),
Fletcher32Mismatch {
expected: u32,
computed: u32,
},
ChunkedReadError(String),
ChecksumMismatch {
expected: u32,
computed: u32,
},
NestingDepthExceeded,
UnsupportedZfp(String),
ValueTooLargeForPlatform {
value: u64,
target: &'static str,
},
OffsetOverflow {
offset: u64,
length: u64,
},
AddressBelowBase {
address: u64,
base: u64,
},
Source(String),
LibverBoundsUnsatisfiable {
writes: &'static str,
requested_low: &'static str,
requested_high: &'static str,
},
LibverTooOldForContent {
content: &'static str,
needs: &'static str,
writing: &'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,
},
ZeroFixedStringWidth,
FixedStringTooLong {
index: usize,
len: usize,
width: u32,
},
NumericElementTooWide {
size: usize,
},
}Expand description
Errors that can occur when parsing HDF5 binary format structures.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
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
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.
ZeroSizedDatatype
A datatype message in a file declares an element size of zero, which no HDF5 type has. Raised when the message is parsed, so the size every reader divides raw bytes by is never zero.
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.
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
CompoundFieldOverlap
Two compound fields overlap.
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.
UnreadableFillValue
The dataset’s Fill Value message could not be parsed, and a read needed it: part of the dataset’s storage was never allocated, so what those elements read as is undetermined. A dataset whose storage is fully allocated reads normally regardless of this message.
TypeMismatch
Type mismatch when reading data.
Fields
DataSizeMismatch
Data size mismatch.
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
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.
UnsupportedExternalStorage
A dataset’s element bytes live in files outside this one
(H5Pset_external, the External Data Files header message). Its layout
message is contiguous with the data address undefined — the same encoding
a never-written dataset carries — so reading the layout alone would answer
the fill value for every element of a dataset that holds data. This reader
does not follow the external files, so such a dataset is refused rather
than read as empty.
InvalidAttributeVersion(u8)
Invalid attribute message version.
InvalidAttributeInfoVersion(u8)
Invalid Attribute Info message version.
Invalid shared message version.
InvalidAttributeFlags(u8)
An attribute message’s flags byte set a bit the format does not define. Only bit 0 (shared datatype) and bit 1 (shared dataspace) exist, so any other bit means the message is not what it claims to be.
UnsupportedSohmReference
A message body is a reference to the file’s shared object header message
(SOHM) heap, and the parse that met it holds no shared-message table to
find it in: the file’s superblock extension carries no Shared Message
Table message, the table it names could not be read, or the parse was
handed a message body without the file it came from. A committed
(H5Tcommit) datatype is not stored in the heap — it references another
object header, and is resolved.
InvalidSohmTableVersion(u8)
A file’s shared-message table, or a Shared Message Table message naming it, declares a version this format does not define.
InvalidSohmIndexCount(u8)
A Shared Message Table message declares no indexes, or more than the eight the format allows. The count sizes the table’s own read, so a wrong one reads neighbouring bytes as index headers.
InvalidSohmTableSignature
The shared-message table does not start with its SMTB signature.
InvalidSohmListSignature
A shared-message list index does not start with its SMLI signature.
InvalidSohmIndexKind(u8)
A shared-message index header declares a storage kind that is neither a list (0) nor a version 2 B-tree (1).
InvalidSohmBTreeType(u8)
A shared-message index names a version 2 B-tree that is not a shared-message index (type 7). Carries the type it is.
InvalidSohmRecordLocation(u8)
A shared-message index record names a storage location that is neither the heap (0) nor an object header (1).
SohmIndexMissing(u16)
A message body references the shared-message heap, and no index of the file’s shared-message table covers that message type or has allocated a heap. Carries the raw type ID of the referenced message.
A shared message reference named an object header that holds no message of the referenced type.
A message body holds a reference to a shared message, and the parse that met it had no access to the file the reference addresses. Carries the raw type ID of the referenced message.
UnknownCommittedDatatype(String)
A dataset or attribute names a committed datatype at a path where the file being written places no such object.
CommittedDatatypeMismatch
A dataset or attribute names a committed datatype whose encoding differs from its own. The two would disagree about how to read the element bytes, and the committed one is what every reader would believe.
Fields
InvalidGlobalHeapSignature
Invalid global heap collection signature.
InvalidGlobalHeapVersion(u8)
Invalid global heap version.
GlobalHeapObjectNotFound
Global heap object not found.
VlDataError(String)
Variable-length data error.
VariableLengthElementLimitExceeded
A variable-length read exceeded its configured element limit.
Fields
VariableLengthByteLimitExceeded
A variable-length read exceeded its configured payload-byte limit.
Fields
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
element_size: NonZeroUsizeSize in bytes of one element (the dataset’s datatype size), used to report the mismatch in elements as well as bytes. Non-zero by type, so the division in the message is well defined.
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.
Fletcher32Mismatch
Fletcher32 checksum mismatch.
ChunkedReadError(String)
Chunked dataset read error.
ChecksumMismatch
CRC32C checksum mismatch.
NestingDepthExceeded
Maximum nesting/continuation depth exceeded (malformed data protection).
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
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
AddressBelowBase
An absolute file position lies below the superblock’s base address, so it
has no stored (base-relative) form: the bytes below the base are the
userblock, where no HDF5 structure can live. Reported instead of wrapping
the subtraction into a near-u64::MAX address.
Fields
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
admit no format this crate writes. It writes the 1.8 and 1.10 formats
(LibVer::WRITER_OLDEST through
LibVer::WRITER_DEFAULT), so an upper
bound older than 1.8, or one below the lower bound, is unsatisfiable. A
lower bound newer than 1.10 is not: it licenses newer encodings without
requiring them, and the 1.10 format satisfies it.
The fields carry the default format and the bounds asked for, as
LibVer::name labels.
Fields
LibverTooOldForContent
The file’s content needs a newer on-disk format than the requested library-version bounds allow, so writing it would silently produce a file the caller asked not to receive.
Reported rather than upgraded, because the bound exists to be relied on:
a MAT v7.3 file bounded to 1.8 so MATLAB can load it is worth less than
nothing if compressing it quietly restores the 1.10 format. content
names what forced the newer format and needs the format it forces, both
as LibVer::name labels.
Fields
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
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
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
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
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.
ZeroFixedStringWidth
A fixed-width string was asked for a declared width of zero. No HDF5 string datatype may be zero bytes wide: libhdf5 refuses one with “invalid datatype size”, and it does so while iterating the object’s members, so one such type takes its neighbours down with it.
Only an explicitly requested width raises this — a dataset’s through
DatasetBuilder::with_ascii_strings_sized
or its siblings, an attribute’s through
AttrValue::ascii_string_sized
or its siblings. A width derived from the values — every one of them
empty — is one byte rather than zero, since the empty string is
representable and it was only the datatype that was not.
FixedStringTooLong
An element handed to a fixed-width string dataset or attribute is longer than the width declared for it. Storing a prefix would read back later as a value the caller never wrote, and with no error to say so, which is why this refuses rather than truncates.
Fields
NumericElementTooWide
A numeric element in a file is wider than the 64-bit word the typed numeric readers model an element as.
Those readers assemble one element from its leading eight bytes, so a wider element would decode from part of itself: a 9-byte integer holding 2^64 read back as zero, indistinguishable from one that really holds zero. Which part survives depends on the byte order — under big-endian those leading bytes are the element’s most significant — so the whole class is refused rather than decoded for the orders that happen to work out (issue #361).
The bytes are still readable: Dataset::read_raw is unaffected, and an
attribute this refuses is omitted from attrs while attr_datatypes
still reports its type.
Trait Implementations§
Source§impl Clone for FormatError
impl Clone for FormatError
Source§fn clone(&self) -> FormatError
fn clone(&self) -> FormatError
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreSource§impl Debug for FormatError
impl Debug for FormatError
Source§impl Display for FormatError
impl Display for FormatError
impl Eq for FormatError
Source§impl Error for FormatError
Available on crate feature std only.
impl Error for FormatError
std only.1.30.0 · Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()
Source§impl From<FormatError> for Error
Available on crate feature std only.
impl From<FormatError> for Error
std only.