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

qubit_codec/buffered/
transcode_status.rs
