qubit_codec/transcode/engine/
encode_unencodable_action.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//! Unencodable-value actions returned by buffered encoder policy hooks.
9
10use crate::Codec;
11
12/// Unencodable-value action for a codec-backed encode hook.
13///
14/// This alias uses the codec's [`Codec::Value`] as the replacement payload
15/// type, keeping hook signatures tied to the codec they serve.
16///
17/// # Type Parameters
18///
19/// - `C`: Codec whose associated `Value` is carried by replacement actions.
20pub type EncodeUnencodableActionOf<C> = EncodeUnencodableAction<<C as Codec>::Value>;
21
22/// Action selected after a codec reports an unencodable input value.
23///
24/// Normal encodable values are handled by the encode engine itself. Hook
25/// implementations return this action only for values outside the codec's
26/// encodable domain.
27///
28/// # Type Parameters
29///
30/// - `Value`: Logical input value type accepted by the codec.
31///
32/// # Examples
33///
34/// ```
35/// use qubit_codec::engine::EncodeUnencodableAction;
36///
37/// let action = EncodeUnencodableAction::replace(0_u8);
38/// assert!(matches!(action, EncodeUnencodableAction::Replace { value: 0 }));
39/// ```
40#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
41#[non_exhaustive]
42#[must_use]
43pub enum EncodeUnencodableAction<Value> {
44    /// Reject the current input value.
45    ///
46    /// The encode engine reports [`crate::TranscodeEncodeError::Unencodable`]
47    /// at the current input index.
48    Reject,
49
50    /// Consume the current input value without producing output.
51    Skip,
52
53    /// Encode a replacement value and consume the current input value.
54    ///
55    /// The replacement must be encodable by the same codec. Returning an
56    /// unencodable replacement is a hook contract violation and panics in the
57    /// encode engine.
58    Replace {
59        /// Replacement value to encode.
60        value: Value,
61    },
62}
63
64impl<Value> EncodeUnencodableAction<Value> {
65    /// Creates a reject action.
66    ///
67    /// # Returns
68    ///
69    /// Returns [`Self::Reject`].
70    #[inline]
71    pub const fn reject() -> Self {
72        Self::Reject
73    }
74
75    /// Creates a replacement action.
76    ///
77    /// # Parameters
78    ///
79    /// - `value`: Replacement value to encode.
80    ///
81    /// # Returns
82    ///
83    /// Returns [`Self::Replace`] carrying `value`.
84    #[inline]
85    pub const fn replace(value: Value) -> Self {
86        Self::Replace { value }
87    }
88}
qubit_codec/transcode/engine/encode_unencodable_action.rs

qubit_codec/transcode/engine/
encode_unencodable_action.rs
