Skip to main content

const_cbor/
error.rs

1//! Compact, allocation-free error codes.
2//!
3//! Every fallible operation in this crate returns [`Error`], a single byte
4//! identifying the failure class. Errors are `Copy`, `Eq`, `Ord`, and carry
5//! no formatting machinery; use [`Error::name`] for a static description.
6
7use core::fmt;
8
9/// A CBOR processing failure, represented as a compact numeric code.
10///
11/// Variant names use `SCREAMING_CASE` because they behave like named
12/// constants: each is a stable, single-byte protocol-level code.
13#[allow(non_camel_case_types)]
14#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
15#[repr(u8)]
16pub enum Error {
17    /// Output buffer had insufficient space for the encoded item.
18    OUT_OF_SPACE = 0,
19    /// Input ended before the current item was complete.
20    TRUNCATED = 1,
21    /// Initial byte encodes an additional-information value reserved for
22    /// indefinite lengths or future use (28–30), or a 64-bit argument on a
23    /// platform narrower than `u64`.
24    INVALID_ADDITIONAL_INFO = 2,
25    /// Value did not fit the requested Rust integer type.
26    INTEGER_OUT_OF_RANGE = 3,
27    /// Encountered item type differs from the expected type.
28    TYPE_MISMATCH = 4,
29    /// Text string payload is not valid UTF-8 (RFC 3629).
30    INVALID_UTF8 = 5,
31    /// Two-byte simple-value encoding used for a value below 32
32    /// (RFC 8949 §3.3 forbids this form).
33    INVALID_SIMPLE = 6,
34    /// Floating-point support is disabled (`float` feature off) but the
35    /// item is major type 7 with a floating-point representation.
36    FLOAT_UNSUPPORTED = 7,
37    /// A skipped structure nested deeper than [`crate::decode::SKIP_LIMIT`].
38    DEPTH_EXCEEDED = 8,
39    /// A break byte appeared where no indefinite item was open.
40    UNEXPECTED_BREAK = 9,
41    /// Indefinite-length support is disabled (`indefinite` feature off).
42    INDEFINITE_UNSUPPORTED = 10,
43}
44
45impl Error {
46    /// Static name of this error code.
47    #[inline(always)]
48    #[must_use]
49    pub const fn name(self) -> &'static str {
50        match self {
51            Self::OUT_OF_SPACE => "out of space",
52            Self::TRUNCATED => "truncated input",
53            Self::INVALID_ADDITIONAL_INFO => "invalid additional information",
54            Self::INTEGER_OUT_OF_RANGE => "integer out of range",
55            Self::TYPE_MISMATCH => "type mismatch",
56            Self::INVALID_UTF8 => "invalid utf-8",
57            Self::INVALID_SIMPLE => "invalid simple value",
58            Self::FLOAT_UNSUPPORTED => "float unsupported",
59            Self::DEPTH_EXCEEDED => "nesting depth exceeded",
60            Self::UNEXPECTED_BREAK => "unexpected break",
61            Self::INDEFINITE_UNSUPPORTED => "indefinite lengths unsupported",
62        }
63    }
64
65    /// Short reason string suitable for logging without formatting.
66    #[inline(always)]
67    #[must_use]
68    pub const fn describe(self) -> (&'static str, u8) {
69        (self.name(), self as u8)
70    }
71}
72
73impl fmt::Display for Error {
74    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
75        f.write_str(self.name())
76    }
77}
78
79// `core::error::Error` is stable since Rust 1.81, so the trait impl needs
80// no std dependency at all.
81impl core::error::Error for Error {}