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

qubit_codec/transcode/engine/
encode_unencodable_action.rs
