qubit_codec_misc/
misc_codec_error.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Shared codec error type.
9
10use std::string::FromUtf8Error;
11
12use thiserror::Error;
13
14/// Result alias returned by codec operations.
15pub type MiscCodecResult<T> = Result<T, MiscCodecError>;
16
17/// Error returned by codec operations.
18#[derive(Debug, Error)]
19pub enum MiscCodecError {
20    /// Input ended before a complete codec value was available.
21    #[error(
22        "incomplete input: required {required} units, available {available}"
23    )]
24    Incomplete {
25        /// Total units required from the current decode start.
26        required: usize,
27        /// Units currently available from the current decode start.
28        available: usize,
29    },
30
31    /// A configured prefix was required but missing.
32    #[error("missing required prefix '{prefix}'")]
33    MissingPrefix {
34        /// Required prefix.
35        prefix: String,
36    },
37
38    /// Input contained a digit that is invalid for the requested radix.
39    #[error("invalid radix-{radix} digit '{character}' at index {index}")]
40    InvalidDigit {
41        /// Numeric radix expected by the codec.
42        radix: u32,
43        /// Character byte index in the original input.
44        index: usize,
45        /// Invalid character.
46        character: char,
47    },
48
49    /// Input length does not satisfy a codec requirement.
50    #[error("invalid length for {context}: expected {expected}, got {actual}")]
51    InvalidLength {
52        /// Human-readable input part whose length was invalid.
53        context: &'static str,
54        /// Human-readable length requirement.
55        expected: String,
56        /// Actual length observed by the codec.
57        actual: usize,
58    },
59
60    /// Input contained a malformed or unsupported escape sequence.
61    #[error("invalid escape {escape:?} at index {index}: {reason}")]
62    InvalidEscape {
63        /// Byte index of the escape marker in the original input.
64        index: usize,
65        /// Escape sequence fragment that caused the error.
66        escape: String,
67        /// Human-readable reason the escape was rejected.
68        reason: String,
69    },
70
71    /// Input contained a character that cannot appear in that context.
72    #[error("invalid character '{character}' at index {index}: {reason}")]
73    InvalidCharacter {
74        /// Character byte index in the original input.
75        index: usize,
76        /// Invalid character.
77        character: char,
78        /// Human-readable reason the character was rejected.
79        reason: String,
80    },
81
82    /// Input was rejected by a codec-specific validator.
83    #[error("invalid {codec} input: {reason}")]
84    InvalidInput {
85        /// Stable codec name, such as `base64`.
86        codec: &'static str,
87        /// Human-readable reason reported by the codec.
88        reason: String,
89    },
90
91    /// Decoded bytes were not valid UTF-8.
92    #[error("decoded bytes are not valid UTF-8: {source}")]
93    InvalidUtf8 {
94        /// Underlying UTF-8 conversion error.
95        #[from]
96        source: FromUtf8Error,
97    },
98}
qubit_codec_misc/misc_codec_error.rs

qubit_codec_misc/
misc_codec_error.rs
