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
89
90
91
92
93
94
95
96

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

use core::num::NonZeroUsize;

/// Action selected after a codec reports invalid encoded input.
///
/// While the stream is open, incomplete input is not an invalid-input policy
/// action. Codecs report it with [`crate::DecodeFailure::Incomplete`], and the
/// decode engine converts it into [`crate::TranscodeStatus::NeedInput`]. After
/// upstream EOF, [`crate::Transcoder::transcode_eof`] asks the codec to resolve
/// a trailing incomplete sequence through [`crate::Codec::decode_eof`]; if it
/// remains incomplete, the engine calls
/// [`crate::engine::DecodeIncompleteAction`] through
/// [`crate::engine::TranscodeDecodeHooks::handle_incomplete_decode`].
///
/// # Type Parameters
///
/// - `Value`: Decoded output value type.
///
/// # Examples
///
/// ```
/// use core::num::NonZeroUsize;
///
/// use qubit_codec::engine::DecodeInvalidAction;
///
/// let action = DecodeInvalidAction::<u8>::Skip {
///     consumed: NonZeroUsize::new(1).unwrap(),
/// };
/// assert!(matches!(action, DecodeInvalidAction::Skip { .. }));
/// ```
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
#[must_use]
pub enum DecodeInvalidAction<Value> {
    /// Reject the current invalid input.
    ///
    /// The decode engine reports the original codec decode error as
    /// [`crate::TranscodeDecodeError::Domain`] at the current input index.
    Reject,

    /// Consume invalid input without producing output.
    ///
    /// `consumed` must not exceed the hook context's available input count.
    /// Over-consuming is a hook contract violation and panics in the engine.
    Skip {
        /// Source units to consume.
        consumed: NonZeroUsize,
    },

    /// Produce one replacement value and consume source units.
    ///
    /// `consumed` must not exceed the hook context's available input count.
    /// Over-consuming is a hook contract violation and panics in the engine.
    Emit {
        /// Value to write to the output buffer.
        value: Value,
        /// Source units to consume.
        consumed: NonZeroUsize,
    },
}

impl<Value> DecodeInvalidAction<Value> {
    /// Validates a policy-reported consumed source-unit count against available
    /// input.
    ///
    /// # Parameters
    ///
    /// - `consumed`: Source units requested by the concrete policy.
    /// - `available`: Source units visible from the current decode cursor.
    ///
    /// # Returns
    ///
    /// Returns the validated non-zero consumed count.
    ///
    /// # Panics
    ///
    /// Panics when `available == 0` or when `consumed > available`.
    #[inline]
    #[must_use]
    pub(super) fn bound_consumed(consumed: NonZeroUsize, available: usize) -> NonZeroUsize {
        assert!(available > 0, "DecodeInvalidAction cannot consume empty input",);
        assert!(
            consumed.get() <= available,
            "DecodeInvalidAction consumed units must not exceed available input",
        );
        consumed
    }
}