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