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    /// Item violates RFC 8949 section 4.2 preferred/deterministic
44    /// serialization: non-minimal argument width, non-shortest float,
45    /// indefinite length, unsorted or duplicate map keys, or a non-preferred
46    /// bignum. Produced only by [`crate::deterministic`] (`deterministic`
47    /// feature); ordinary decoding accepts all well-formed forms.
48    NOT_CANONICAL = 11,
49}
50
51impl Error {
52    /// Static name of this error code.
53    #[inline(always)]
54    #[must_use]
55    pub const fn name(self) -> &'static str {
56        match self {
57            Self::OUT_OF_SPACE => "out of space",
58            Self::TRUNCATED => "truncated input",
59            Self::INVALID_ADDITIONAL_INFO => "invalid additional information",
60            Self::INTEGER_OUT_OF_RANGE => "integer out of range",
61            Self::TYPE_MISMATCH => "type mismatch",
62            Self::INVALID_UTF8 => "invalid utf-8",
63            Self::INVALID_SIMPLE => "invalid simple value",
64            Self::FLOAT_UNSUPPORTED => "float unsupported",
65            Self::DEPTH_EXCEEDED => "nesting depth exceeded",
66            Self::UNEXPECTED_BREAK => "unexpected break",
67            Self::INDEFINITE_UNSUPPORTED => "indefinite lengths unsupported",
68            Self::NOT_CANONICAL => "not canonical",
69        }
70    }
71
72    /// Short reason string suitable for logging without formatting.
73    #[inline(always)]
74    #[must_use]
75    pub const fn describe(self) -> (&'static str, u8) {
76        (self.name(), self as u8)
77    }
78}
79
80impl fmt::Display for Error {
81    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
82        f.write_str(self.name())
83    }
84}
85
86// `core::error::Error` is stable since Rust 1.81, so the trait impl needs
87// no std dependency at all.
88impl core::error::Error for Error {}