qubit-codec 0.8.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

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Policy hooks used by buffered convert engines.

use super::{
    transcode_decode_hooks::TranscodeDecodeHooks,
    transcode_encode_hooks::TranscodeEncodeHooks,
};
use crate::Codec;

/// Policy hooks for [`crate::TranscodeConvertEngine`].
///
/// Convert hooks no longer own decoded pending values or the conversion loop.
/// The engine owns source/target cursor state, retained decoded values, output
/// capacity checks, and final progress reporting. Hooks only select the
/// decode/encode policies used by the internal buffered engines and map their
/// errors into one converter-level error type.
///
/// # Type Parameters
///
/// - `D`: Source-side decode codec owned by the converter engine.
/// - `E`: Target-side encode codec owned by the converter engine.
pub trait TranscodeConvertHooks<D, E>
where
    D: Codec,
    E: Codec<Value = D::Value>,
{
    /// Domain error type returned by the buffered converter.
    type Error;

    /// Error type returned by the selected decode hooks.
    type DecodeError;

    /// Error type returned by the selected encode hooks.
    type EncodeError;

    /// Decode policy hooks used by the internal buffered decoder.
    type DecodeHooks: TranscodeDecodeHooks<D, Error = Self::DecodeError>;

    /// Encode policy hooks used by the internal buffered encoder.
    type EncodeHooks: TranscodeEncodeHooks<E, Error = Self::EncodeError>;

    /// Creates decode policy hooks for the internal buffered decoder.
    ///
    /// # Parameters
    ///
    /// - `decode_codec`: Source codec owned by the converter engine.
    /// - `encode_codec`: Target codec owned by the converter engine.
    ///
    /// # Returns
    ///
    /// Returns the decode hooks used by the internal buffered decoder.
    fn create_decode_hooks(
        &self,
        decode_codec: &D,
        encode_codec: &E,
    ) -> Self::DecodeHooks;

    /// Creates encode policy hooks for the internal buffered encoder.
    ///
    /// # Parameters
    ///
    /// - `decode_codec`: Source codec owned by the converter engine.
    /// - `encode_codec`: Target codec owned by the converter engine.
    ///
    /// # Returns
    ///
    /// Returns the encode hooks used by the internal buffered encoder.
    fn create_encode_hooks(
        &self,
        decode_codec: &D,
        encode_codec: &E,
    ) -> Self::EncodeHooks;

    /// Maps a decode-engine error into the converter error type.
    ///
    /// # Parameters
    ///
    /// - `error`: Error returned by the selected decode hooks.
    ///
    /// # Returns
    ///
    /// Returns the converter-level error.
    fn map_decode_error(&self, error: Self::DecodeError) -> Self::Error;

    /// Maps an encode-engine error into the converter error type.
    ///
    /// # Parameters
    ///
    /// - `error`: Error returned by the selected encode hooks.
    ///
    /// # Returns
    ///
    /// Returns the converter-level error.
    fn map_encode_error(&self, error: Self::EncodeError) -> Self::Error;

    /// Resets conversion-level hook-owned state.
    ///
    /// The common engine clears pending decoded values and resets internal
    /// decode/encode engines separately.
    #[inline(always)]
    fn reset(&mut self) {}
}