qubit-codec 0.8.0

Core codec traits and buffer conversion primitives for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Internal encode-step result used by buffered encoders.

use core::num::NonZeroUsize;

use super::super::transcode_progress::TranscodeProgress;
use super::encode_state::EncodeState;

/// Result of one prepared value encode attempt.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub(in crate::transcode) enum EncodeStep {
    /// The value was fully written.
    Written {
        /// Output units written by the encode hook.
        written: usize,
    },
    /// The value could not be written because output capacity is insufficient.
    NeedOutput {
        /// Additional output units required to continue.
        additional: NonZeroUsize,
        /// Output units available at the stop boundary.
        available: usize,
    },
}

impl EncodeStep {
    /// Creates a successful encode step.
    ///
    /// # Parameters
    ///
    /// - `written`: Output units written by the encode hook.
    ///
    /// # Returns
    ///
    /// Returns a step that consumed one logical input value.
    #[inline(always)]
    pub(in crate::transcode) const fn written(written: usize) -> Self {
        Self::Written { written }
    }

    /// Creates an output-starved encode step.
    ///
    /// # Parameters
    ///
    /// - `required`: Output units required by the prepared encode plan.
    /// - `available`: Output units currently writable at the output cursor.
    ///
    /// # Returns
    ///
    /// Returns a step describing the missing output capacity.
    #[inline(always)]
    pub(in crate::transcode) fn need_output(
        required: usize,
        available: usize,
    ) -> Self {
        let additional = qubit_io::nz!(required - available);
        Self::NeedOutput {
            additional,
            available,
        }
    }

    /// Applies this step to the current encode state.
    ///
    /// # Parameters
    ///
    /// - `state`: Active encode call state.
    ///
    /// # Returns
    ///
    /// Returns stop progress when more output is required, otherwise `None`.
    #[inline]
    pub(in crate::transcode) fn apply_to_state<Value, Unit>(
        self,
        state: &mut EncodeState<'_, Value, Unit>,
    ) -> Option<TranscodeProgress> {
        match self {
            Self::Written { written } => {
                state.accept_written_value(written);
                None
            }
            Self::NeedOutput {
                additional,
                available,
            } => Some(state.need_output_progress_with(additional, available)),
        }
    }
}