qubit_io/coder/
coder_progress.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 ******************************************************************************/
10use super::CoderStatus;
11
12/// Counts how much work a [`crate::Coder`] completed before returning.
13#[derive(Clone, Copy, Debug, Eq, PartialEq)]
14pub struct CoderProgress {
15    /// Stop reason reported by the coder.
16    status: CoderStatus,
17    /// Number of input units consumed from the requested input index.
18    read: usize,
19    /// Number of output units written from the requested output index.
20    written: usize,
21}
22
23impl CoderProgress {
24    /// Creates a progress value.
25    ///
26    /// # Parameters
27    ///
28    /// - `status`: The reason conversion stopped.
29    /// - `read`: Number of input units consumed from the call's input index.
30    /// - `written`: Number of output units written from the call's output index.
31    ///
32    /// # Returns
33    ///
34    /// Returns a progress value carrying the supplied counters.
35    #[must_use]
36    #[inline]
37    pub const fn new(status: CoderStatus, read: usize, written: usize) -> Self {
38        Self { status, read, written }
39    }
40
41    /// Creates a completed progress value.
42    ///
43    /// # Parameters
44    ///
45    /// - `read`: Number of consumed input units.
46    /// - `written`: Number of produced output units.
47    ///
48    /// # Returns
49    ///
50    /// Returns a progress value whose status is [`CoderStatus::Complete`].
51    #[must_use]
52    #[inline]
53    pub const fn complete(read: usize, written: usize) -> Self {
54        Self::new(CoderStatus::Complete, read, written)
55    }
56
57    /// Returns the status that stopped conversion.
58    ///
59    /// # Returns
60    ///
61    /// Returns the stored [`CoderStatus`].
62    #[must_use]
63    #[inline]
64    pub const fn status(self) -> CoderStatus {
65        self.status
66    }
67
68    /// Returns the number of input units consumed by the call.
69    ///
70    /// # Returns
71    ///
72    /// Returns a count relative to the input index passed to the conversion call.
73    #[must_use]
74    #[inline]
75    pub const fn read(self) -> usize {
76        self.read
77    }
78
79    /// Returns the number of output units written by the call.
80    ///
81    /// # Returns
82    ///
83    /// Returns a count relative to the output index passed to the conversion call.
84    #[must_use]
85    #[inline]
86    pub const fn written(self) -> usize {
87        self.written
88    }
89
90    /// Returns the additional unit count required by the reported status.
91    ///
92    /// # Returns
93    ///
94    /// Returns `0` when conversion completed.
95    #[must_use]
96    #[inline]
97    pub const fn required(self) -> usize {
98        match self.status {
99            CoderStatus::Complete => 0,
100            CoderStatus::NeedInput { required, .. } => required,
101            CoderStatus::NeedOutput { required, .. } => required,
102        }
103    }
104
105    /// Returns the absolute boundary index associated with this status, if any.
106    ///
107    /// - For [`CoderStatus::NeedInput`], returns `input_index`.
108    /// - For [`CoderStatus::NeedOutput`], returns `output_index`.
109    /// - For [`CoderStatus::Complete`], returns `None`.
110    #[must_use]
111    #[inline]
112    pub const fn index(self) -> Option<usize> {
113        match self.status {
114            CoderStatus::Complete => None,
115            CoderStatus::NeedInput { input_index, .. } => Some(input_index),
116            CoderStatus::NeedOutput { output_index, .. } => Some(output_index),
117        }
118    }
119
120    /// Returns the number of available units at the reported status boundary.
121    ///
122    /// # Returns
123    ///
124    /// Returns `0` when conversion completed.
125    #[must_use]
126    #[inline]
127    pub const fn available(self) -> usize {
128        match self.status {
129            CoderStatus::Complete => 0,
130            CoderStatus::NeedInput { available, .. } => available,
131            CoderStatus::NeedOutput { available, .. } => available,
132        }
133    }
134}
qubit_io/coder/coder_progress.rs

qubit_io/coder/
coder_progress.rs
