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    input_value: &'a Value,
33    input_index: usize,
34    output_index: usize,
35    available_output: usize,
36}
37
38impl<'a, Value> EncodeContext<'a, Value> {
39    /// Creates an encode policy context.
40    ///
41    /// # Parameters
42    ///
43    /// - `input_value`: Borrowed input value being encoded.
44    /// - `input_index`: Absolute input index of `input_value`.
45    /// - `output_index`: Absolute output index where writing begins.
46    /// - `available_output`: Output units writable from `output_index`.
47    ///
48    /// # Returns
49    ///
50    /// Returns a read-only encode context.
51    #[inline(always)]
52    #[must_use]
53    pub const fn new(input_value: &'a Value, input_index: usize, output_index: usize, available_output: usize) -> Self {
54        Self {
55            input_value,
56            input_index,
57            output_index,
58            available_output,
59        }
60    }
61
62    /// Returns the input value being encoded.
63    #[inline(always)]
64    #[must_use]
65    pub const fn input_value(&self) -> &Value {
66        self.input_value
67    }
68
69    /// Returns the absolute input index of the current value.
70    #[inline(always)]
71    #[must_use]
72    pub const fn input_index(&self) -> usize {
73        self.input_index
74    }
75
76    /// Returns the absolute output index where writing begins.
77    #[inline(always)]
78    #[must_use]
79    pub const fn output_index(&self) -> usize {
80        self.output_index
81    }
82
83    /// Returns output capacity visible to this encode attempt.
84    #[inline(always)]
85    #[must_use]
86    pub const fn available_output(&self) -> usize {
87        self.available_output
88    }
89}
qubit_codec/transcode/engine/encode_context.rs

qubit_codec/transcode/engine/
encode_context.rs
