Skip to main content

heic_rs/
error.rs

1//! The crate's hand-written error type.
2//!
3//! No `thiserror`: this crate is `no_std` by construction, and the error type
4//! carries only `'static` strings and integers so that reporting a failure
5//! never allocates.
6
7use core::fmt;
8
9/// Everything that can go wrong while reading a HEIF file.
10#[derive(Debug, Clone, PartialEq, Eq)]
11#[non_exhaustive]
12pub enum Error {
13    /// The file ended in the middle of a structure that was still being read.
14    Truncated(&'static str),
15    /// A structure was present but its contents violate the format.
16    Malformed(&'static str),
17    /// The file is well formed but asks for something this build cannot do.
18    Unsupported(&'static str),
19    /// A box required to make sense of the file is absent.
20    MissingBox(&'static str),
21    /// An item id referenced from elsewhere does not exist.
22    MissingItem(u32),
23    /// A coded slice named a VPS, SPS or PPS the `hvcC` record did not carry.
24    MissingParameterSet(&'static str),
25    /// A `dimg` derivation chain refers back to itself.
26    CyclicDerivation(u32),
27    /// The declared image is larger than [`DecodeOptions::max_pixels`].
28    ///
29    /// [`DecodeOptions::max_pixels`]: crate::DecodeOptions::max_pixels
30    PixelLimit {
31        /// Pixels the file asks for.
32        pixels: u64,
33        /// Pixels the caller allowed.
34        max_pixels: u64,
35    },
36    /// A filesystem failure from the `io` module. Never produced by the
37    /// decoding path, which performs no I/O.
38    #[cfg(feature = "std")]
39    Io(std::io::ErrorKind),
40    /// A box declared a size that cannot be honoured on this machine.
41    BoxTooLarge {
42        /// The four-character box type.
43        boxtype: [u8; 4],
44        /// The size the box declared.
45        size: u64,
46    },
47}
48
49impl Error {
50    /// The four-character code as text, for display purposes.
51    fn fourcc(code: &[u8; 4]) -> &str {
52        core::str::from_utf8(code).unwrap_or("????")
53    }
54}
55
56impl fmt::Display for Error {
57    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
58        match self {
59            Error::Truncated(what) => write!(f, "truncated file: ran out of bytes reading {what}"),
60            Error::Malformed(what) => write!(f, "malformed file: {what}"),
61            Error::Unsupported(what) => write!(f, "unsupported: {what}"),
62            Error::MissingBox(what) => write!(f, "required box `{what}` is missing"),
63            Error::MissingItem(id) => write!(f, "item {id} is referenced but not present"),
64            Error::MissingParameterSet(what) => {
65                write!(
66                    f,
67                    "the bitstream names a {what} that the file does not carry"
68                )
69            }
70            Error::CyclicDerivation(id) => {
71                write!(f, "item {id} derives from itself, directly or indirectly")
72            }
73            Error::PixelLimit { pixels, max_pixels } => write!(
74                f,
75                "image would be {pixels} pixels, above the {max_pixels} pixel limit"
76            ),
77            #[cfg(feature = "std")]
78            Error::Io(kind) => write!(f, "i/o error: {kind}"),
79            Error::BoxTooLarge { boxtype, size } => write!(
80                f,
81                "box `{}` declares an implausible size of {size} bytes",
82                Self::fourcc(boxtype)
83            ),
84        }
85    }
86}
87
88#[cfg(feature = "std")]
89impl std::error::Error for Error {}
90
91#[cfg(feature = "std")]
92impl From<std::io::Error> for Error {
93    fn from(e: std::io::Error) -> Error {
94        Error::Io(e.kind())
95    }
96}
97
98/// Shorthand for results carried through this crate.
99pub type Result<T> = core::result::Result<T, Error>;