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 {}