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. If the call
35    /// started at `start` and returned `progress`, preserve
36    /// `input[start + progress.read()..]` before refilling the input buffer.
37    /// If the caller has already advanced its input cursor by
38    /// `progress.read()`, it can slice from that updated cursor directly.
39    /// Apply the EOF policy when the upstream source is closed. Calling
40    /// [`crate::Transcoder::finish`] does not pass this tail back to the
41    /// transcoder.
42    ///
43    /// - `required`: Current minimum total input units required before retrying
44    ///   from the current input position. A later retry may raise this lower
45    ///   bound.
46    NeedInput {
47        /// Current minimum total input units required before retrying from the
48        /// current input position. A later retry may raise this lower bound.
49        required: NonZeroUsize,
50    },
51
52    /// More output capacity is needed before conversion can continue.
53    ///
54    /// - `required`: Total output units required from the current output
55    ///   position.
56    NeedOutput {
57        /// Total output units required from the current output position.
58        required: NonZeroUsize,
59    },
60}
61
62impl TranscodeStatus {
63    /// Creates a status that requests more input.
64    ///
65    /// # Parameters
66    ///
67    /// - `required`: Current minimum total input units required before retrying
68    ///   from the current input position. A later retry may raise this lower
69    ///   bound.
70    ///
71    /// # Returns
72    ///
73    /// Returns a [`TranscodeStatus::NeedInput`] value.
74    #[inline]
75    #[must_use]
76    pub const fn need_input(required: NonZeroUsize) -> Self {
77        Self::NeedInput { required }
78    }
79
80    /// Creates a status that requests more output capacity.
81    ///
82    /// # Parameters
83    ///
84    /// - `required`: Total output units required from the current output
85    ///   position.
86    ///
87    /// # Returns
88    ///
89    /// Returns a [`TranscodeStatus::NeedOutput`] value.
90    #[inline]
91    #[must_use]
92    pub const fn need_output(required: NonZeroUsize) -> Self {
93        Self::NeedOutput { required }
94    }
95}
qubit_codec/transcode/transcode_status.rs

qubit_codec/transcode/
transcode_status.rs
