qubit-codec 0.9.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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Encode context for one buffered encode attempt.

/// Context for one encode attempt inside a buffered encoder engine.
///
/// The context carries the current input value and output cursor. The hook
/// decides whether the value can be consumed with the visible output capacity
/// and reports that decision through [`crate::EncodeOutcome`].
///
/// # Type Parameters
///
/// - `Value`: Logical input value type.
/// - `Unit`: Encoded output unit type.
#[derive(Debug)]
pub struct EncodeContext<'a, Value, Unit> {
    input_value: &'a Value,
    input_index: usize,
    output: &'a mut [Unit],
    output_index: usize,
}

impl<'a, Value, Unit> EncodeContext<'a, Value, Unit> {
    /// Creates an encode context.
    ///
    /// # Parameters
    ///
    /// - `input_value`: Borrowed input value being encoded.
    /// - `input_index`: Absolute input index of `input_value`.
    /// - `output`: Complete output unit slice visible to the encoder.
    /// - `output_index`: Start position in `output` where writing begins.
    ///
    /// # Returns
    ///
    /// Returns an encode context.
    #[inline(always)]
    #[must_use]
    pub fn new(
        input_value: &'a Value,
        input_index: usize,
        output: &'a mut [Unit],
        output_index: usize,
    ) -> Self {
        Self {
            input_value,
            input_index,
            output,
            output_index,
        }
    }

    /// Returns the input value being encoded.
    ///
    /// # Returns
    ///
    /// Returns a shared reference to the current input value.
    #[inline(always)]
    #[must_use]
    pub fn input_value(&self) -> &Value {
        self.input_value
    }

    /// Returns the absolute input index of the current value.
    ///
    /// # Returns
    ///
    /// Returns the absolute input index.
    #[inline(always)]
    #[must_use]
    pub fn input_index(&self) -> usize {
        self.input_index
    }

    /// Returns the complete output unit slice visible to the encoder.
    ///
    /// # Returns
    ///
    /// Returns the output slice.
    #[inline(always)]
    #[must_use]
    pub fn output(&mut self) -> &mut [Unit] {
        self.output
    }

    /// Returns the start position in the output slice where writing begins.
    ///
    /// # Returns
    ///
    /// Returns the absolute output index.
    #[inline(always)]
    #[must_use]
    pub fn output_index(&self) -> usize {
        self.output_index
    }

    /// Returns writable output units from the current output index.
    ///
    /// # Returns
    ///
    /// Returns output capacity visible to this encode attempt.
    #[inline(always)]
    #[must_use]
    pub fn available_output(&self) -> usize {
        self.output.len().saturating_sub(self.output_index)
    }

    /// Consumes the context and returns all parts.
    ///
    /// Use this when you need simultaneous access to the input value reference
    /// and the mutable output slice, since Rust's borrow checker disallows
    /// taking `&self` and `&mut self` in the same expression.
    ///
    /// # Returns
    ///
    /// Returns `(input_value, input_index, output, output_index)`.
    #[inline(always)]
    #[must_use]
    pub fn into_parts(self) -> (&'a Value, usize, &'a mut [Unit], usize) {
        (
            self.input_value,
            self.input_index,
            self.output,
            self.output_index,
        )
    }
}