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#[must_use]
22#[derive(Clone, Copy, Debug, Eq, PartialEq)]
23pub enum TranscodeStatus {
24    /// All currently supplied input was consumed.
25    ///
26    /// A `Complete` status means the current [`crate::Transcoder::transcode`]
27    /// call consumed every input unit visible from the supplied `input_index`.
28    /// Implementations must report [`NeedInput`](Self::NeedInput) for an
29    /// incomplete input tail and [`NeedOutput`](Self::NeedOutput) when output
30    /// capacity prevents further input consumption.
31    Complete,
32
33    /// More input is needed to complete the next output value.
34    ///
35    /// The transcoder does not consume incomplete input tails. If the call
36    /// started at `start` and returned `progress`, preserve
37    /// `input[start + progress.read()..]` before refilling the input buffer.
38    /// If the caller has already advanced its input cursor by
39    /// `progress.read()`, it can slice from that updated cursor directly.
40    /// Apply the EOF policy when the upstream source is closed. Calling
41    /// [`crate::Transcoder::finish`] does not pass this tail back to the
42    /// transcoder.
43    ///
44    /// - `required`: Current minimum total input units required before retrying
45    ///   from the current input position. A later retry may raise this lower
46    ///   bound.
47    NeedInput {
48        /// Current minimum total input units required before retrying from the
49        /// current input position. A later retry may raise this lower bound.
50        required: NonZeroUsize,
51    },
52
53    /// More output capacity is needed before conversion can continue.
54    ///
55    /// - `required`: Total output units required from the current output
56    ///   position.
57    NeedOutput {
58        /// Total output units required from the current output position.
59        required: NonZeroUsize,
60    },
61}
62
63impl TranscodeStatus {
64    /// Creates a status that requests more input.
65    ///
66    /// # Parameters
67    ///
68    /// - `required`: Current minimum total input units required before retrying
69    ///   from the current input position. A later retry may raise this lower
70    ///   bound.
71    ///
72    /// # Returns
73    ///
74    /// Returns a [`TranscodeStatus::NeedInput`] value.
75    #[inline]
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    pub const fn need_output(required: NonZeroUsize) -> Self {
92        Self::NeedOutput { required }
93    }
94}
qubit_codec/transcode/transcode_status.rs

qubit_codec/transcode/
transcode_status.rs
