qubit_codec/transcode/engine/
encode_context.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// =============================================================================
8//! Read-only policy context for one buffered encode attempt.
9
10/// Read-only context supplied to an encode policy hook.
11///
12/// The engine retains ownership of the mutable output slice. Hooks can inspect
13/// the current value and cursor/capacity metadata, then return an
14/// [`crate::engine::EncodeUnencodableAction`] without being able to mutate
15/// output behind the engine's progress accounting.
16///
17/// # Type Parameters
18///
19/// - `Value`: Logical input value type.
20///
21/// # Examples
22///
23/// ```
24/// use qubit_codec::engine::EncodeContext;
25///
26/// let value = 7_u8;
27/// let context = EncodeContext::new(&value, 0, 0, 1);
28/// assert_eq!(context.input_value(), &7);
29/// ```
30#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
31pub struct EncodeContext<'a, Value> {
32    /// Value borrowed for the lifetime of this policy context.
33    input_value: &'a Value,
34    /// Absolute input position of the borrowed value.
35    input_index: usize,
36    /// Absolute output cursor at the start of the encode attempt.
37    output_index: usize,
38    /// Number of writable output units remaining at the cursor.
39    available_output: usize,
40}
41
42impl<'a, Value> EncodeContext<'a, Value> {
43    /// Creates an encode policy context.
44    ///
45    /// # Parameters
46    ///
47    /// - `input_value`: Borrowed input value being encoded.
48    /// - `input_index`: Absolute input index of `input_value`.
49    /// - `output_index`: Absolute output index where writing begins.
50    /// - `available_output`: Output units writable from `output_index`.
51    ///
52    /// # Returns
53    ///
54    /// Returns a read-only encode context.
55    #[inline]
56    #[must_use]
57    pub const fn new(input_value: &'a Value, input_index: usize, output_index: usize, available_output: usize) -> Self {
58        Self {
59            input_value,
60            input_index,
61            output_index,
62            available_output,
63        }
64    }
65
66    /// Returns the input value being encoded.
67    ///
68    /// # Returns
69    ///
70    /// The input value borrowed through this context without allocation.
71    #[inline]
72    #[must_use]
73    pub const fn input_value(&self) -> &Value {
74        self.input_value
75    }
76
77    /// Returns the absolute input index of the current value.
78    ///
79    /// # Returns
80    ///
81    /// The absolute position of the value in the input sequence.
82    #[inline]
83    #[must_use]
84    pub const fn input_index(&self) -> usize {
85        self.input_index
86    }
87
88    /// Returns the absolute output index where writing begins.
89    ///
90    /// # Returns
91    ///
92    /// The starting output cursor for this encode attempt.
93    #[inline]
94    #[must_use]
95    pub const fn output_index(&self) -> usize {
96        self.output_index
97    }
98
99    /// Returns output capacity visible to this encode attempt.
100    ///
101    /// # Returns
102    ///
103    /// The number of output units available from the starting cursor.
104    #[inline]
105    #[must_use]
106    pub const fn available_output(&self) -> usize {
107        self.available_output
108    }
109}
qubit_codec/transcode/engine/encode_context.rs

qubit_codec/transcode/engine/
encode_context.rs
