Skip to main content

hdf5_rust/
error.rs

1//! Named errors. No string-only error type.
2
3use alloc::string::String;
4use core::fmt;
5
6/// Recoverable HDF5 failure. Public variants listed in the build spec are
7/// stable; additional variants describe truncated or malformed files.
8#[derive(Clone, Debug, PartialEq, Eq)]
9pub enum HDF5Error {
10    /// Bytes at the superblock location are not [`crate::HDF5_SIGNATURE`].
11    InvalidSignature,
12    /// Superblock or object-header version this crate does not read.
13    UnsupportedVersion(u8),
14    /// Chunk index this crate does not walk (paged extensible-array blocks,
15    /// or an index kind outside single / implicit / fixed / extensible / B-tree v1 / v2).
16    ChunkedNotSupported,
17    /// Filter this crate does not decode (SZIP, floating-point scale-offset,
18    /// n-bit array/compound, or an unknown filter id).
19    FilteredNotSupported,
20    /// Datatype cannot be written back (compound, big-endian, …).
21    UnsupportedDtype,
22    /// No object at `path`.
23    NotFound(String),
24    /// Append rank or trailing dimensions do not match the existing dataset.
25    ShapeMismatch,
26    /// File ended before a field was complete.
27    Truncated,
28    /// A header, checksum, or message failed validation.
29    InvalidHeader,
30    /// Dataspace rank is greater than [`crate::HDF5_MAX_DIMS`] (HDF5 format max is 32).
31    RankNotSupported,
32    /// Dataset datatype cannot satisfy the requested read (e.g. `read_f64` on F32).
33    TypeMismatch,
34    /// Group stores links in a fractal heap / dense index.
35    DenseGroupsNotSupported,
36    /// Link or attribute name exceeds [`crate::HDF5_MAX_NAME_LEN`].
37    NameTooLong,
38    /// I/O error from `std::fs` (feature `std`).
39    #[cfg(feature = "std")]
40    Io(String),
41}
42
43impl fmt::Display for HDF5Error {
44    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
45        match self {
46            Self::InvalidSignature => f.write_str("invalid HDF5 signature"),
47            Self::UnsupportedVersion(v) => write!(f, "unsupported HDF5 version {v}"),
48            Self::ChunkedNotSupported => f.write_str("chunked dataset not supported"),
49            Self::FilteredNotSupported => f.write_str("filtered HDF5 dataset not supported"),
50            Self::UnsupportedDtype => f.write_str("HDF5 datatype not supported"),
51            Self::NotFound(p) => write!(f, "HDF5 path not found: {p}"),
52            Self::ShapeMismatch => f.write_str("HDF5 dataspace shape mismatch"),
53            Self::Truncated => f.write_str("truncated HDF5 file"),
54            Self::InvalidHeader => f.write_str("invalid HDF5 header"),
55            Self::RankNotSupported => f.write_str("HDF5 rank not supported"),
56            Self::TypeMismatch => f.write_str("HDF5 datatype mismatch"),
57            Self::DenseGroupsNotSupported => f.write_str("dense HDF5 groups not supported"),
58            Self::NameTooLong => f.write_str("HDF5 name too long"),
59            #[cfg(feature = "std")]
60            Self::Io(s) => write!(f, "HDF5 I/O error: {s}"),
61        }
62    }
63}
64
65#[cfg(feature = "std")]
66impl std::error::Error for HDF5Error {}
67
68#[cfg(feature = "std")]
69impl From<std::io::Error> for HDF5Error {
70    fn from(e: std::io::Error) -> Self {
71        Self::Io(alloc::string::ToString::to_string(&e))
72    }
73}
74
75/// `Result` alias for this crate’s [`HDF5Error`].
76pub type Result<T> = core::result::Result<T, HDF5Error>;