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. Calling [`crate::Transcoder::finish`] does not pass
22    /// this tail back to the transcoder.
23    ///
24    /// - `input_index`: Absolute input index where input ended while decoding.
25    /// - `required`: Total input units required from the current input
26    ///   position.
27    /// - `available`: Number of input units currently available from the
28    ///   current input position.
29    NeedInput {
30        /// Absolute input index where input ended.
31        input_index: usize,
32        /// Total input units required from the current input position.
33        required: NonZeroUsize,
34        /// Number of input units currently available.
35        available: usize,
36    },
37
38    /// More output capacity is needed before conversion can continue.
39    ///
40    /// - `output_index`: Absolute output index where output ended while
41    ///   decoding.
42    /// - `required`: Total output units required from the current output
43    ///   position.
44    /// - `available`: Number of output units currently available from the
45    ///   current output position.
46    NeedOutput {
47        /// Absolute output index where output ended.
48        output_index: usize,
49        /// Total output units required from the current output position.
50        required: NonZeroUsize,
51        /// Number of output units currently available.
52        available: usize,
53    },
54}
55
56impl TranscodeStatus {
57    /// Creates a status that requests more input.
58    ///
59    /// # Parameters
60    ///
61    /// - `input_index`: Absolute input boundary where conversion stopped.
62    /// - `required`: Total input units required from the current input
63    ///   position.
64    /// - `available`: Input units currently available at the boundary.
65    ///
66    /// # Returns
67    ///
68    /// Returns a [`TranscodeStatus::NeedInput`] value.
69    #[inline(always)]
70    #[must_use]
71    pub const fn need_input(
72        input_index: usize,
73        required: NonZeroUsize,
74        available: usize,
75    ) -> Self {
76        Self::NeedInput {
77            input_index,
78            required,
79            available,
80        }
81    }
82
83    /// Creates a status that requests more output capacity.
84    ///
85    /// # Parameters
86    ///
87    /// - `output_index`: Absolute output boundary where conversion stopped.
88    /// - `required`: Total output units required from the current output
89    ///   position.
90    /// - `available`: Output units currently available at the boundary.
91    ///
92    /// # Returns
93    ///
94    /// Returns a [`TranscodeStatus::NeedOutput`] value.
95    #[inline(always)]
96    #[must_use]
97    pub const fn need_output(
98        output_index: usize,
99        required: NonZeroUsize,
100        available: usize,
101    ) -> Self {
102        Self::NeedOutput {
103            output_index,
104            required,
105            available,
106        }
107    }
108}
qubit_codec/transcode/transcode_status.rs

qubit_codec/transcode/
transcode_status.rs
