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

qubit_codec/transcode/
transcode_status.rs
