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

qubit_codec/transcode/engine/
encode_unencodable_action.rs
