qubit_codec/
codec_error.rs

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

qubit_codec/
codec_error.rs
