qubit_codec/transcode/
transcode_status.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
10/// Reports why a [`crate::Transcoder`] stopped converting input.
11#[derive(Clone, Copy, Debug, Eq, PartialEq)]
12pub enum TranscodeStatus {
13    /// All currently supplied input was consumed.
14    Complete,
15
16    /// More input is needed to complete the next output value.
17    ///
18    /// The transcoder does not consume incomplete input tails. The caller
19    /// should preserve `input[input_index..]`, refill the input buffer when
20    /// more data is available, or apply its EOF policy when the upstream
21    /// source is closed.
22    ///
23    /// - `input_index`: Absolute input index where input ended while decoding.
24    /// - `additional`: Number of additional input units required to continue.
25    /// - `available`: Number of input units currently available from the
26    ///   current input position.
27    NeedInput {
28        /// Absolute input index where input ended.
29        input_index: usize,
30        /// Number of additional input units required to continue.
31        additional: NonZeroUsize,
32        /// Number of input units currently available.
33        available: usize,
34    },
35
36    /// More output capacity is needed before conversion can continue.
37    ///
38    /// - `output_index`: Absolute output index where output ended while
39    ///   decoding.
40    /// - `additional`: Number of additional output units required to continue.
41    /// - `available`: Number of output units currently available from the
42    ///   current output position.
43    NeedOutput {
44        /// Absolute output index where output ended.
45        output_index: usize,
46        /// Number of additional output units required to continue.
47        additional: NonZeroUsize,
48        /// Number of output units currently available.
49        available: usize,
50    },
51}
52
53impl TranscodeStatus {
54    /// Creates a status that requests more input.
55    ///
56    /// # Parameters
57    ///
58    /// - `input_index`: Absolute input boundary where conversion stopped.
59    /// - `additional`: Additional input units required to continue.
60    /// - `available`: Input units currently available at the boundary.
61    ///
62    /// # Returns
63    ///
64    /// Returns a [`TranscodeStatus::NeedInput`] value.
65    #[must_use]
66    #[inline(always)]
67    pub const fn need_input(
68        input_index: usize,
69        additional: NonZeroUsize,
70        available: usize,
71    ) -> Self {
72        Self::NeedInput {
73            input_index,
74            additional,
75            available,
76        }
77    }
78
79    /// Creates a status that requests more output capacity.
80    ///
81    /// # Parameters
82    ///
83    /// - `output_index`: Absolute output boundary where conversion stopped.
84    /// - `additional`: Additional output units required to continue.
85    /// - `available`: Output units currently available at the boundary.
86    ///
87    /// # Returns
88    ///
89    /// Returns a [`TranscodeStatus::NeedOutput`] value.
90    #[must_use]
91    #[inline(always)]
92    pub const fn need_output(
93        output_index: usize,
94        additional: NonZeroUsize,
95        available: usize,
96    ) -> Self {
97        Self::NeedOutput {
98            output_index,
99            additional,
100            available,
101        }
102    }
103}
qubit_codec/transcode/transcode_status.rs

qubit_codec/transcode/
transcode_status.rs
