qubit_codec/codec/codec_decode_error_signal.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//! Domain-neutral codec decode error signals.
9
10use core::num::NonZeroUsize;
11
12/// Optional stream-recovery signals exposed by codec decode errors.
13///
14/// Concrete codec errors remain responsible for describing their own domain
15/// failure. This trait only standardizes the small amount of control-flow
16/// information that streaming adapters need when deciding whether to read more
17/// input or consume invalid units before reporting an error.
18pub trait CodecDecodeErrorSignal {
19 /// Returns the total input units required from the current value start.
20 ///
21 /// # Returns
22 ///
23 /// Returns `Some(required)` for incomplete input prefixes, or `None` when
24 /// the error does not request more input.
25 #[must_use]
26 #[inline(always)]
27 fn required_total(&self) -> Option<usize> {
28 None
29 }
30
31 /// Returns invalid input units that may be consumed to make progress.
32 ///
33 /// # Returns
34 ///
35 /// Returns `Some(consumed)` for malformed or non-canonical input that a
36 /// streaming adapter may discard before surfacing the error, or `None`
37 /// when no consumption hint is available.
38 #[must_use]
39 #[inline(always)]
40 fn consumed_units(&self) -> Option<NonZeroUsize> {
41 None
42 }
43}
44
45impl CodecDecodeErrorSignal for core::convert::Infallible {}