j2k_core/
error.rs

1// SPDX-License-Identifier: Apache-2.0
2
3use crate::{pixel::PixelFormat, sample::SampleType};
4
5/// Buffer validation and copy errors.
6#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
7pub enum BufferError {
8    /// Destination buffer is too small for the requested output.
9    #[error("output buffer too small: required {required} bytes, have {have}")]
10    OutputTooSmall {
11        /// Required destination length in bytes.
12        required: usize,
13        /// Actual destination length in bytes.
14        have: usize,
15    },
16    /// Source buffer is too small for the requested copy/decode.
17    #[error("input buffer too small: required {required} bytes, have {have}")]
18    InputTooSmall {
19        /// Required source length in bytes.
20        required: usize,
21        /// Actual source length in bytes.
22        have: usize,
23    },
24    /// A byte-count computation overflowed.
25    #[error("buffer size overflow while computing {what}")]
26    SizeOverflow {
27        /// Name of the size being computed.
28        what: &'static str,
29    },
30    /// A requested allocation exceeds the configured safety cap.
31    #[error("{what} allocation too large: requested {requested} bytes, cap {cap}")]
32    AllocationTooLarge {
33        /// Requested byte count.
34        requested: usize,
35        /// Configured byte cap.
36        cap: usize,
37        /// Name of the allocation being checked.
38        what: &'static str,
39    },
40    /// Output stride cannot hold one decoded row.
41    #[error("stride {stride} is smaller than row width {row_bytes}")]
42    StrideTooSmall {
43        /// Required row width in bytes.
44        row_bytes: usize,
45        /// Supplied stride in bytes.
46        stride: usize,
47    },
48    /// Output stride does not meet backend alignment requirements.
49    #[error("stride {stride} is not aligned to {align}")]
50    StrideNotAligned {
51        /// Supplied stride in bytes.
52        stride: usize,
53        /// Required byte alignment.
54        align: usize,
55    },
56    /// Requested pixel format uses a different sample width than the row type.
57    #[error("pixel format {fmt:?} does not match sample type {sample_type:?}")]
58    SampleTypeMismatch {
59        /// Requested output pixel format.
60        fmt: PixelFormat,
61        /// Sample type accepted by the current sink or buffer.
62        sample_type: SampleType,
63    },
64}
65
66/// Generic malformed or truncated input errors.
67#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
68pub enum InputError {
69    /// Input ended before a required fixed-size read.
70    #[error("input too short: need {need} bytes, have {have}")]
71    TooShort {
72        /// Required byte count.
73        need: usize,
74        /// Available byte count.
75        have: usize,
76    },
77    /// Input ended while reading a named segment.
78    #[error("input truncated at offset {offset} while reading {segment}")]
79    TruncatedAt {
80        /// Byte offset where truncation was detected.
81        offset: usize,
82        /// Name of the segment being read.
83        segment: &'static str,
84    },
85}
86
87/// Error for a valid request that is not implemented yet.
88#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
89#[error("not yet implemented: {what}")]
90pub struct NotImplemented {
91    /// Feature or path that is not implemented.
92    pub what: &'static str,
93}
94
95/// Error for input or options unsupported by the current codec.
96#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
97#[error("unsupported: {what}")]
98pub struct Unsupported {
99    /// Unsupported feature or option.
100    pub what: &'static str,
101}
102
103/// Shared error classification used by facade traits.
104pub trait CodecError: core::error::Error + Send + Sync + 'static {
105    /// True when the error indicates truncated input.
106    fn is_truncated(&self) -> bool;
107    /// True when the error indicates an unimplemented supported surface.
108    fn is_not_implemented(&self) -> bool;
109    /// True when the error indicates unsupported input or options.
110    fn is_unsupported(&self) -> bool;
111    /// True when the error indicates caller buffer sizing or layout problems.
112    fn is_buffer_error(&self) -> bool;
113}
j2k_core/error.rs

j2k_core/
error.rs
