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    ///
15    /// A `Complete` status means the current [`crate::Transcoder::transcode`]
16    /// call consumed every input unit visible from the supplied `input_index`.
17    /// Implementations must report [`NeedInput`](Self::NeedInput) for an
18    /// incomplete input tail and [`NeedOutput`](Self::NeedOutput) when output
19    /// capacity prevents further input consumption.
20    Complete,
21
22    /// More input is needed to complete the next output value.
23    ///
24    /// The transcoder does not consume incomplete input tails. The caller
25    /// should preserve `input[input_index..]`, refill the input buffer when
26    /// more data is available, or apply its EOF policy when the upstream
27    /// source is closed. Calling [`crate::Transcoder::finish`] does not pass
28    /// this tail back to the transcoder.
29    ///
30    /// - `required`: Current minimum total input units required before retrying
31    ///   from the current input position. A later retry may raise this lower
32    ///   bound.
33    NeedInput {
34        /// Current minimum total input units required before retrying from the
35        /// current input position. A later retry may raise this lower bound.
36        required: NonZeroUsize,
37    },
38
39    /// More output capacity is needed before conversion can continue.
40    ///
41    /// - `required`: Total output units required from the current output
42    ///   position.
43    NeedOutput {
44        /// Total output units required from the current output position.
45        required: NonZeroUsize,
46    },
47}
48
49impl TranscodeStatus {
50    /// Creates a status that requests more input.
51    ///
52    /// # Parameters
53    ///
54    /// - `required`: Current minimum total input units required before retrying
55    ///   from the current input position. A later retry may raise this lower
56    ///   bound.
57    ///
58    /// # Returns
59    ///
60    /// Returns a [`TranscodeStatus::NeedInput`] value.
61    #[inline(always)]
62    #[must_use]
63    pub const fn need_input(required: NonZeroUsize) -> Self {
64        Self::NeedInput { required }
65    }
66
67    /// Creates a status that requests more output capacity.
68    ///
69    /// # Parameters
70    ///
71    /// - `required`: Total output units required from the current output
72    ///   position.
73    ///
74    /// # Returns
75    ///
76    /// Returns a [`TranscodeStatus::NeedOutput`] value.
77    #[inline(always)]
78    #[must_use]
79    pub const fn need_output(required: NonZeroUsize) -> Self {
80        Self::NeedOutput { required }
81    }
82}
qubit_codec/transcode/transcode_status.rs

qubit_codec/transcode/
transcode_status.rs
