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

qubit_codec/transcode/engine/
encode_unencodable_action.rs
