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("batch item count exceeded: expected {expected}, observed at least {observed_at_least}")]
56    CountExceeded {
57        /// Declared item count.
58        expected: usize,
59        /// Lower bound of observed items.
60        observed_at_least: usize,
61        /// Result accumulated before the excess item was observed.
62        result: BatchProcessResult,
63    },
64}
65
66impl BatchProcessError {
67    /// Returns the partial result attached to this error.
68    ///
69    /// # Returns
70    ///
71    /// A shared reference to the partial batch process result.
72    #[inline]
73    pub const fn result(&self) -> &BatchProcessResult {
74        match self {
75            Self::CountShortfall { result, .. } | Self::CountExceeded { result, .. } => result,
76        }
77    }
78
79    /// Consumes this error and returns its partial result.
80    ///
81    /// # Returns
82    ///
83    /// The partial batch process result.
84    #[inline]
85    pub fn into_result(self) -> BatchProcessResult {
86        match self {
87            Self::CountShortfall { result, .. } | Self::CountExceeded { result, .. } => result,
88        }
89    }
90}
qubit_batch/process/batch_process_error.rs

qubit_batch/process/
batch_process_error.rs
