qubit_codec/transcode/transcode_progress.rs
1// =============================================================================
2// Copyright (c) 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8use core::num::NonZeroUsize;
9
10use super::TranscodeStatus;
11
12/// Counts how much work a [`crate::Transcoder`] completed before
13/// returning.
14#[derive(Clone, Copy, Debug, Eq, PartialEq)]
15pub struct TranscodeProgress {
16 /// Stop reason reported by the transcoder.
17 status: TranscodeStatus,
18 /// Number of input units consumed from the requested input index.
19 read: usize,
20 /// Number of output units written from the requested output index.
21 written: usize,
22}
23
24impl TranscodeProgress {
25 /// Creates a progress value.
26 ///
27 /// # Parameters
28 ///
29 /// - `status`: The reason conversion stopped.
30 /// - `read`: Number of input units consumed from the call's input index.
31 /// - `written`: Number of output units written from the call's output
32 /// index.
33 ///
34 /// # Returns
35 ///
36 /// Returns a progress value carrying the supplied counters.
37 #[must_use]
38 #[inline(always)]
39 pub const fn new(
40 status: TranscodeStatus,
41 read: usize,
42 written: usize,
43 ) -> Self {
44 Self {
45 status,
46 read,
47 written,
48 }
49 }
50
51 /// Creates a completed progress value.
52 ///
53 /// # Parameters
54 ///
55 /// - `read`: Number of consumed input units.
56 /// - `written`: Number of produced output units.
57 ///
58 /// # Returns
59 ///
60 /// Returns a progress value whose status is [`TranscodeStatus::Complete`].
61 #[must_use]
62 #[inline(always)]
63 pub const fn complete(read: usize, written: usize) -> Self {
64 Self::new(TranscodeStatus::Complete, read, written)
65 }
66
67 /// Creates progress that stopped because more input is needed.
68 ///
69 /// # Parameters
70 ///
71 /// - `input_index`: Absolute input boundary where conversion stopped.
72 /// - `additional`: Additional input units required to continue.
73 /// - `available`: Input units currently available at the boundary.
74 /// - `read`: Number of consumed input units.
75 /// - `written`: Number of produced output units.
76 ///
77 /// # Returns
78 ///
79 /// Returns a progress value with [`TranscodeStatus::NeedInput`].
80 #[must_use]
81 #[inline(always)]
82 pub const fn need_input(
83 input_index: usize,
84 additional: NonZeroUsize,
85 available: usize,
86 read: usize,
87 written: usize,
88 ) -> Self {
89 Self::new(
90 TranscodeStatus::need_input(input_index, additional, available),
91 read,
92 written,
93 )
94 }
95
96 /// Creates progress that stopped because more output capacity is needed.
97 ///
98 /// # Parameters
99 ///
100 /// - `output_index`: Absolute output boundary where conversion stopped.
101 /// - `additional`: Additional output units required to continue.
102 /// - `available`: Output units currently available at the boundary.
103 /// - `read`: Number of consumed input units.
104 /// - `written`: Number of produced output units.
105 ///
106 /// # Returns
107 ///
108 /// Returns a progress value with [`TranscodeStatus::NeedOutput`].
109 #[must_use]
110 #[inline(always)]
111 pub const fn need_output(
112 output_index: usize,
113 additional: NonZeroUsize,
114 available: usize,
115 read: usize,
116 written: usize,
117 ) -> Self {
118 Self::new(
119 TranscodeStatus::need_output(output_index, additional, available),
120 read,
121 written,
122 )
123 }
124
125 /// Returns the status that stopped conversion.
126 ///
127 /// # Returns
128 ///
129 /// Returns the stored [`TranscodeStatus`].
130 #[must_use]
131 #[inline(always)]
132 pub const fn status(self) -> TranscodeStatus {
133 self.status
134 }
135
136 /// Returns whether conversion consumed all currently supplied input.
137 ///
138 /// # Returns
139 ///
140 /// Returns `true` when the stored status is
141 /// [`TranscodeStatus::Complete`].
142 #[must_use]
143 #[inline(always)]
144 pub const fn is_complete(self) -> bool {
145 matches!(self.status, TranscodeStatus::Complete)
146 }
147
148 /// Returns whether conversion stopped because more input is needed.
149 ///
150 /// # Returns
151 ///
152 /// Returns `true` when the stored status is
153 /// [`TranscodeStatus::NeedInput`].
154 #[must_use]
155 #[inline(always)]
156 pub const fn is_need_input(self) -> bool {
157 matches!(self.status, TranscodeStatus::NeedInput { .. })
158 }
159
160 /// Returns whether conversion stopped because more output capacity is
161 /// needed.
162 ///
163 /// # Returns
164 ///
165 /// Returns `true` when the stored status is
166 /// [`TranscodeStatus::NeedOutput`].
167 #[must_use]
168 #[inline(always)]
169 pub const fn is_need_output(self) -> bool {
170 matches!(self.status, TranscodeStatus::NeedOutput { .. })
171 }
172
173 /// Returns the number of input units consumed by the call.
174 ///
175 /// # Returns
176 ///
177 /// Returns a count relative to the input index passed to the conversion
178 /// call.
179 #[must_use]
180 #[inline(always)]
181 pub const fn read(self) -> usize {
182 self.read
183 }
184
185 /// Returns the number of output units written by the call.
186 ///
187 /// # Returns
188 ///
189 /// Returns a count relative to the output index passed to the conversion
190 /// call.
191 #[must_use]
192 #[inline(always)]
193 pub const fn written(self) -> usize {
194 self.written
195 }
196}