qubit_budget/string/
budgeted_string_error.rs

1// =============================================================================
2//    Copyright (c) 2025 - 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Errors returned by transactional string rendering.
9
10use std::collections::TryReserveError;
11use std::fmt::Debug;
12use std::fmt::Display;
13use std::string::FromUtf8Error;
14
15use thiserror::Error;
16
17use crate::resource::InsufficientBudgetError;
18use crate::resource::QuantityConversionError;
19
20/// Describes why a budgeted string rendering transaction failed.
21///
22/// # Type Parameters
23///
24/// * `R` - Caller-defined resource identity retained by limits and errors.
25/// * `E` - Error type returned by the caller-provided renderer.
26/// * `Q` - Exact unsigned quantity used for measurements and accounting.
27///
28/// # Examples
29///
30/// ```
31/// use qubit_budget::BudgetedStringError;
32///
33/// let error = BudgetedStringError::<&str, &str>::Render("render failed");
34/// assert!(matches!(error, BudgetedStringError::Render("render failed")));
35/// ```
36#[derive(Debug, Error)]
37#[must_use]
38pub enum BudgetedStringError<R, E, Q = u64>
39where
40    R: Debug,
41    E: Debug + Display,
42    Q: Copy + Debug,
43{
44    /// The rendered prefix exceeded the remaining resource budget.
45    #[error(transparent)]
46    Budget(
47        /// Exact resource, capacity, balance, and rejected request.
48        InsufficientBudgetError<R, Q>,
49    ),
50    /// The output buffer could not reserve the requested capacity.
51    #[error("string output allocation failed: {0}")]
52    Allocation(
53        /// Allocation failure returned by the output byte buffer.
54        #[source]
55        TryReserveError,
56    ),
57    /// The rendered UTF-8 byte length cannot be represented by the budget
58    /// quantity.
59    #[error("string byte measurement cannot be represented: {source}")]
60    Quantity {
61        /// Resource whose accounting required the conversion.
62        resource: R,
63        /// Failed quantity conversion.
64        #[source]
65        source: QuantityConversionError,
66    },
67    /// The renderer returned an error unrelated to the budget writer.
68    #[error("string renderer failed: {0}")]
69    Render(
70        /// Original error returned by the caller-provided renderer.
71        E,
72    ),
73    /// The renderer produced bytes that are not valid UTF-8.
74    #[error("rendered bytes are not valid UTF-8")]
75    InvalidUtf8(
76        /// UTF-8 conversion failure retaining the rendered bytes.
77        #[source]
78        FromUtf8Error,
79    ),
80    /// The rendered byte length overflowed `usize`.
81    #[error("rendered string length overflowed usize")]
82    LengthOverflow,
83}
qubit_budget/string/budgeted_string_error.rs

qubit_budget/string/
budgeted_string_error.rs
