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