qubit_batch/process/
batch_process_error.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10use thiserror::Error;
11
12use super::BatchProcessResult;
13
14/// Error returned by built-in consumer-backed batch processors.
15///
16/// The error variants report mismatches between the declared item count and the
17/// number of items yielded by the input source. Each variant carries the partial
18/// result accumulated before the mismatch was detected.
19///
20/// ```rust
21/// use qubit_batch::{
22///     BatchProcessError,
23///     BatchProcessor,
24///     SequentialBatchProcessor,
25/// };
26///
27/// let mut processor = SequentialBatchProcessor::new(|_item: &i32| {});
28/// let error = processor
29///     .process_with_count([1], 2)
30///     .expect_err("iterator should yield fewer items than declared");
31///
32/// match error {
33///     BatchProcessError::CountShortfall { expected, actual, result } => {
34///         assert_eq!(expected, 2);
35///         assert_eq!(actual, 1);
36///         assert_eq!(result.completed_count(), 1);
37///     }
38///     BatchProcessError::CountExceeded { .. } => unreachable!(),
39/// }
40/// ```
41#[derive(Debug, Clone, Error, PartialEq, Eq)]
42pub enum BatchProcessError {
43    /// The input source ended before the declared item count was reached.
44    #[error("batch item count shortfall: expected {expected}, actual {actual}")]
45    CountShortfall {
46        /// Declared item count.
47        expected: usize,
48        /// Actual number of items observed from the source.
49        actual: usize,
50        /// Result accumulated before the shortfall was reported.
51        result: BatchProcessResult,
52    },
53
54    /// The input source yielded more items than the declared item count.
55    #[error(
56        "batch item count exceeded: expected {expected}, observed at least {observed_at_least}"
57    )]
58    CountExceeded {
59        /// Declared item count.
60        expected: usize,
61        /// Lower bound of observed items.
62        observed_at_least: usize,
63        /// Result accumulated before the excess item was observed.
64        result: BatchProcessResult,
65    },
66}
67
68impl BatchProcessError {
69    /// Returns the partial result attached to this error.
70    ///
71    /// # Returns
72    ///
73    /// A shared reference to the partial batch process result.
74    #[inline]
75    pub const fn result(&self) -> &BatchProcessResult {
76        match self {
77            Self::CountShortfall { result, .. } | Self::CountExceeded { result, .. } => result,
78        }
79    }
80
81    /// Consumes this error and returns its partial result.
82    ///
83    /// # Returns
84    ///
85    /// The partial batch process result.
86    #[inline]
87    pub fn into_result(self) -> BatchProcessResult {
88        match self {
89            Self::CountShortfall { result, .. } | Self::CountExceeded { result, .. } => result,
90        }
91    }
92}
qubit_batch/process/batch_process_error.rs

qubit_batch/process/
batch_process_error.rs
