qubit-codec 0.17.4

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

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Unencodable-value actions returned by buffered encoder policy hooks.

use crate::Codec;

/// Unencodable-value action for a codec-backed encode hook.
///
/// This alias uses the codec's [`Codec::Value`] as the replacement payload
/// type, keeping hook signatures tied to the codec they serve.
///
/// # Type Parameters
///
/// - `C`: Codec whose associated `Value` is carried by replacement actions.
pub type EncodeUnencodableActionOf<C> = EncodeUnencodableAction<<C as Codec>::Value>;

/// Action selected after a codec reports an unencodable input value.
///
/// Normal encodable values are handled by the encode engine itself. Hook
/// implementations return this action only for values outside the codec's
/// encodable domain.
///
/// # Type Parameters
///
/// - `Value`: Logical input value type accepted by the codec.
///
/// # Examples
///
/// ```
/// use qubit_codec::engine::EncodeUnencodableAction;
///
/// let action = EncodeUnencodableAction::replace(0_u8);
/// assert!(matches!(action, EncodeUnencodableAction::Replace { value: 0 }));
/// ```
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
#[must_use]
pub enum EncodeUnencodableAction<Value> {
    /// Reject the current input value.
    ///
    /// The encode engine reports [`crate::TranscodeEncodeError::Unencodable`]
    /// at the current input index.
    Reject,

    /// Consume the current input value without producing output.
    Skip,

    /// Encode a replacement value and consume the current input value.
    ///
    /// The replacement must be encodable by the same codec. Returning an
    /// unencodable replacement is a hook contract violation and panics in the
    /// encode engine.
    Replace {
        /// Replacement value to encode.
        value: Value,
    },
}

impl<Value> EncodeUnencodableAction<Value> {
    /// Creates a reject action.
    ///
    /// # Returns
    ///
    /// Returns [`Self::Reject`].
    #[inline]
    pub const fn reject() -> Self {
        Self::Reject
    }

    /// Creates a replacement action.
    ///
    /// # Parameters
    ///
    /// - `value`: Replacement value to encode.
    ///
    /// # Returns
    ///
    /// Returns [`Self::Replace`] carrying `value`.
    #[inline]
    pub const fn replace(value: Value) -> Self {
        Self::Replace { value }
    }
}