qubit_codec/transcode/engine/decode_incomplete_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//! Incomplete-decode actions returned by buffered decoder policy hooks.
9
10use crate::Codec;
11
12/// Incomplete-decode action for a codec-backed decode hook.
13pub type DecodeIncompleteActionOf<C> = DecodeIncompleteAction<<C as Codec>::Value>;
14
15/// Action selected after end-of-input leaves a codec value incomplete.
16///
17/// The decode engine invokes this action only after the caller has established
18/// EOF. A non-rejecting action consumes every source unit still available from
19/// the current decode cursor.
20///
21/// # Type Parameters
22///
23/// - `Value`: Decoded output value type.
24///
25/// # Examples
26///
27/// ```
28/// use qubit_codec::engine::DecodeIncompleteAction;
29///
30/// let action = DecodeIncompleteAction::<u8>::Emit { value: b'?' };
31/// assert!(matches!(action, DecodeIncompleteAction::Emit { value: b'?' }));
32/// ```
33#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
34#[non_exhaustive]
35pub enum DecodeIncompleteAction<Value> {
36 /// Reject the incomplete source tail.
37 ///
38 /// The decode engine reports the codec-domain error when available, or an
39 /// [`crate::TranscodeFailure::IncompleteInput`] framework error otherwise.
40 Reject,
41
42 /// Consume the entire incomplete source tail without output.
43 Skip,
44
45 /// Consume the entire incomplete source tail and emit one replacement.
46 Emit {
47 /// Replacement value to write to the output buffer.
48 value: Value,
49 },
50}