qubit_codec/transcode/engine/
transcode_convert_hooks.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//! Policy hooks used by buffered convert engines.
9
10use super::{
11    transcode_decode_hooks::TranscodeDecodeHooks,
12    transcode_encode_hooks::TranscodeEncodeHooks,
13};
14use crate::Codec;
15
16/// Policy hooks for [`crate::TranscodeConvertEngine`].
17///
18/// Convert hooks no longer own decoded pending values or the conversion loop.
19/// The engine owns source/target cursor state, retained decoded values, output
20/// capacity checks, and final progress reporting. Hooks only select the
21/// decode/encode policies used by the internal buffered engines and map their
22/// errors into one converter-level error type.
23///
24/// # Type Parameters
25///
26/// - `D`: Source-side decode codec owned by the converter engine.
27/// - `E`: Target-side encode codec owned by the converter engine.
28pub trait TranscodeConvertHooks<D, E>
29where
30    D: Codec,
31    E: Codec<Value = D::Value>,
32{
33    /// Domain error type returned by the buffered converter.
34    type Error;
35
36    /// Error type returned by the selected decode hooks.
37    type DecodeError;
38
39    /// Error type returned by the selected encode hooks.
40    type EncodeError;
41
42    /// Decode policy hooks used by the internal buffered decoder.
43    type DecodeHooks: TranscodeDecodeHooks<D, Error = Self::DecodeError>;
44
45    /// Encode policy hooks used by the internal buffered encoder.
46    type EncodeHooks: TranscodeEncodeHooks<E, Error = Self::EncodeError>;
47
48    /// Creates decode policy hooks for the internal buffered decoder.
49    ///
50    /// # Parameters
51    ///
52    /// - `decode_codec`: Source codec owned by the converter engine.
53    /// - `encode_codec`: Target codec owned by the converter engine.
54    ///
55    /// # Returns
56    ///
57    /// Returns the decode hooks used by the internal buffered decoder.
58    fn create_decode_hooks(
59        &self,
60        decode_codec: &D,
61        encode_codec: &E,
62    ) -> Self::DecodeHooks;
63
64    /// Creates encode policy hooks for the internal buffered encoder.
65    ///
66    /// # Parameters
67    ///
68    /// - `decode_codec`: Source codec owned by the converter engine.
69    /// - `encode_codec`: Target codec owned by the converter engine.
70    ///
71    /// # Returns
72    ///
73    /// Returns the encode hooks used by the internal buffered encoder.
74    fn create_encode_hooks(
75        &self,
76        decode_codec: &D,
77        encode_codec: &E,
78    ) -> Self::EncodeHooks;
79
80    /// Maps a decode-engine error into the converter error type.
81    ///
82    /// # Parameters
83    ///
84    /// - `error`: Error returned by the selected decode hooks.
85    ///
86    /// # Returns
87    ///
88    /// Returns the converter-level error.
89    fn map_decode_error(&self, error: Self::DecodeError) -> Self::Error;
90
91    /// Maps an encode-engine error into the converter error type.
92    ///
93    /// # Parameters
94    ///
95    /// - `error`: Error returned by the selected encode hooks.
96    ///
97    /// # Returns
98    ///
99    /// Returns the converter-level error.
100    fn map_encode_error(&self, error: Self::EncodeError) -> Self::Error;
101
102    /// Resets conversion-level hook-owned state.
103    ///
104    /// The common engine clears pending decoded values and resets internal
105    /// decode/encode engines separately.
106    #[inline(always)]
107    fn reset(&mut self) {}
108}
qubit_codec/transcode/engine/transcode_convert_hooks.rs

qubit_codec/transcode/engine/
transcode_convert_hooks.rs
