qubit_codec/buffered/
buffered_convert_hooks.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! Policy hooks used by buffered convert engines.
11
12use super::{
13    buffered_decode_hooks::BufferedDecodeHooks,
14    buffered_encode_hooks::BufferedEncodeHooks,
15};
16use crate::Codec;
17
18/// Policy hooks for [`crate::BufferedConvertEngine`].
19///
20/// Convert hooks no longer own decoded pending values or the conversion loop.
21/// The engine owns source/target cursor state, retained decoded values, output
22/// capacity checks, and final progress reporting. Hooks only select the
23/// decode/encode policies used by the internal buffered engines and map their
24/// errors into one converter-level error type.
25///
26/// # Type Parameters
27///
28/// - `D`: Source-side decode codec owned by the converter engine.
29/// - `E`: Target-side encode codec owned by the converter engine.
30pub trait BufferedConvertHooks<D, E>
31where
32    D: Codec,
33    E: Codec<Value = D::Value>,
34{
35    /// Error type returned by the buffered converter.
36    type Error;
37
38    /// Error type returned by the selected decode hooks.
39    type DecodeError;
40
41    /// Error type returned by the selected encode hooks.
42    type EncodeError;
43
44    /// Decode policy hooks used by the internal buffered decoder.
45    type DecodeHooks: BufferedDecodeHooks<D, Error = Self::DecodeError>;
46
47    /// Encode policy hooks used by the internal buffered encoder.
48    type EncodeHooks: BufferedEncodeHooks<E, Error = Self::EncodeError>;
49
50    /// Creates decode policy hooks for the internal buffered decoder.
51    ///
52    /// # Parameters
53    ///
54    /// - `decode_codec`: Source codec owned by the converter engine.
55    /// - `encode_codec`: Target codec owned by the converter engine.
56    ///
57    /// # Returns
58    ///
59    /// Returns the decode hooks used by the internal buffered decoder.
60    fn create_decode_hooks(&self, decode_codec: &D, encode_codec: &E) -> Self::DecodeHooks;
61
62    /// Creates encode policy hooks for the internal buffered encoder.
63    ///
64    /// # Parameters
65    ///
66    /// - `decode_codec`: Source codec owned by the converter engine.
67    /// - `encode_codec`: Target codec owned by the converter engine.
68    ///
69    /// # Returns
70    ///
71    /// Returns the encode hooks used by the internal buffered encoder.
72    fn create_encode_hooks(&self, decode_codec: &D, encode_codec: &E) -> Self::EncodeHooks;
73
74    /// Maps a decode-engine error into the converter error type.
75    ///
76    /// # Parameters
77    ///
78    /// - `error`: Error returned by the selected decode hooks.
79    ///
80    /// # Returns
81    ///
82    /// Returns the converter-level error.
83    fn map_decode_error(&self, error: Self::DecodeError) -> Self::Error;
84
85    /// Maps an encode-engine error into the converter error type.
86    ///
87    /// # Parameters
88    ///
89    /// - `error`: Error returned by the selected encode hooks.
90    ///
91    /// # Returns
92    ///
93    /// Returns the converter-level error.
94    fn map_encode_error(&self, error: Self::EncodeError) -> Self::Error;
95
96    /// Builds an error for a caller-supplied source input index outside the input slice.
97    ///
98    /// The engine calls this hook before it reads source input. Keeping this
99    /// construction in the hook lets converter adapters preserve their concrete
100    /// error type without a separate public factory trait.
101    ///
102    /// # Parameters
103    ///
104    /// - `decode_codec`: Source codec owned by the engine.
105    /// - `index`: Invalid absolute input index supplied by the caller.
106    /// - `input_len`: Length of the input slice.
107    ///
108    /// # Returns
109    ///
110    /// Returns the hook-specific invalid-input-index error.
111    fn invalid_input_index(&self, decode_codec: &D, index: usize, input_len: usize) -> Self::Error;
112
113    /// Resets conversion-level hook-owned state.
114    ///
115    /// The common engine clears pending decoded values and resets internal
116    /// decode/encode engines separately.
117    #[inline(always)]
118    fn reset(&mut self) {}
119}
qubit_codec/buffered/buffered_convert_hooks.rs

qubit_codec/buffered/
buffered_convert_hooks.rs
