Skip to main content

qubit_codec/codec/codec/
codec.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
9use core::num::NonZeroUsize;
10
11use super::super::decode_failure::DecodeFailure;
12
13/// Encodes and decodes one value or codec quantum against a unit buffer.
14///
15/// `Codec` is the lowest-level abstraction in the codec stack. It is intended
16/// for hot paths that have already validated buffer capacity and want to avoid
17/// constructing subslices for every value. Higher-level transcoders and
18/// convenience APIs are responsible for checked buffer management and owned
19/// output allocation.
20///
21/// `MIN_UNITS_PER_VALUE` and `MAX_DECODE_UNITS_PER_VALUE` describe the readable
22/// representation-width bounds for one decoded value. If fewer than the
23/// minimum units are available, no complete value can exist, so a streaming
24/// caller can request more input or report an incomplete EOF tail. The minimum
25/// is also the smallest safety precondition checked callers must satisfy before
26/// entering [`decode`](Self::decode). The decode maximum bounds successful
27/// consumption and incomplete-input requirements for one value.
28///
29/// `MAX_ENCODE_UNITS_PER_VALUE` is the independent value-agnostic upper bound
30/// for main-phase encode output. Reserving that many units makes encoding safe
31/// for every encodable value. Once a value and encode state are known, callers
32/// may instead reserve the exact [`encode_len`](Self::encode_len), which must
33/// not exceed the encode maximum. Complete-lifecycle adapters that still need
34/// to run [`encode_reset`](Self::encode_reset) must reserve the maximum first
35/// because reset may change the exact width.
36///
37/// A codec may keep decode-side and encode-side stream state. That state is an
38/// implementation detail owned by the codec. Callers do not snapshot or restore
39/// it; implementations must keep their own state internally consistent across
40/// every public operation. A failed decode attempt must not advance decode
41/// state, so callers can retry the same input after refilling their buffer or
42/// applying an invalid-input policy.
43///
44/// Decode operations see only the currently supplied input slice and codec
45/// state. [`decode`](Self::decode) treats that slice as an open stream segment;
46/// [`decode_eof`](Self::decode_eof) receives the same preconditions after the
47/// caller has established that no more units will arrive. Returning
48/// [`DecodeFailure::Incomplete`] from `decode` requests more input for the
49/// current value; it is not itself an EOF error. Codecs that need EOF-aware
50/// maximal-munch parsing or reinterpretation of a trailing prefix can override
51/// `decode_eof` without changing their streaming behavior.
52/// An incomplete failure may also retain codec-specific context through
53/// [`DecodeFailure::incomplete_with_source`]; stream drivers may ignore that
54/// context while retrying and use it for detailed EOF diagnostics.
55///
56/// # Associated Types
57///
58/// - `Value`: Logical value decoded from or encoded into the buffer. This may
59///   be a scalar such as `u8`, `u16`, `u64`, a `char`, a fixed quantum such as
60///   `[u8; 3]`, or an owned value such as `String`/`Vec<u8>`. Adapters that
61///   need scratch initialization add their own bounds at the use site.
62/// - `Unit`: Buffer unit used by the encoded representation. Implementations
63///   are typically scalar storage units such as `u8`, `u16`, or `char`.
64///   Adapters that allocate owned output add their own initialization bounds at
65///   the use site.
66///
67/// Implementors must uphold the safety contract documented by
68/// [`decode`](Self::decode), [`encode`](Self::encode),
69/// [`encode_reset`](Self::encode_reset), and
70/// [`decode_finish`](Self::decode_finish). Unchecked implementations must not
71/// read or write outside the caller-provided ranges. Implementations should use
72/// `debug_assert!` to state the expected buffer bounds at the unchecked entry
73/// point.
74///
75/// Implementations must also guarantee that
76/// [`MIN_UNITS_PER_VALUE`](Self::MIN_UNITS_PER_VALUE) is non-zero and no larger
77/// than [`MAX_DECODE_UNITS_PER_VALUE`](Self::MAX_DECODE_UNITS_PER_VALUE), which
78/// must also be non-zero. `MAX_ENCODE_UNITS_PER_VALUE` may be zero for a codec
79/// that always buffers each accepted value instead of immediately emitting
80/// units. Checked adapters enforce the decode-bound invariants with
81/// compile-time assertions before using codec-provided bounds.
82///
83/// # Why the low-level methods are unchecked
84///
85/// The `unsafe` entry points are intentional: checked adapters validate the
86/// index and capacity preconditions once, then call [`encode`](Self::encode)
87/// and [`decode`](Self::decode) without rebuilding subslices or repeating
88/// bounds checks for every value. The `safe_vs_unchecked` benchmark in
89/// `benches/transcode.rs` compares the same 64 KiB copy loop in release mode.
90/// Its result is workload- and toolchain-specific, so callers should use
91/// checked adapters unless they can establish the documented preconditions at
92/// a trusted boundary. Measure representative codec workloads before choosing
93/// an unchecked entry point. Codec implementations should keep the unchecked
94/// methods small and use `debug_assert!` for those assumptions.
95///
96/// # Examples
97///
98/// A minimal identity codec exposes its bounds and decodes one byte:
99///
100/// ```
101/// use core::convert::Infallible;
102/// use core::num::NonZeroUsize;
103///
104/// use qubit_codec::Codec;
105/// use qubit_codec::DecodeFailure;
106///
107/// struct Identity;
108/// impl Identity {
109///     fn new() -> Self { Self }
110/// }
111/// impl Codec for Identity {
112///     type Value = u8;
113///     type Unit = u8;
114///     type DecodeError = Infallible;
115///     type EncodeError = Infallible;
116///     const MIN_UNITS_PER_VALUE: usize = 1;
117///     const MAX_DECODE_UNITS_PER_VALUE: usize = 1;
118///     const MAX_ENCODE_UNITS_PER_VALUE: usize = 1;
119///
120///     unsafe fn decode(&mut self, input: &[u8], index: usize)
121///         -> Result<(u8, NonZeroUsize), DecodeFailure<Infallible>> {
122///         Ok((input[index], NonZeroUsize::MIN))
123///     }
124///
125///     unsafe fn encode(&mut self, value: &u8, output: &mut [u8], index: usize)
126///         -> Result<usize, Infallible> {
127///         output[index] = *value;
128///         Ok(1)
129///     }
130/// }
131///
132/// let mut codec = Identity::new();
133/// assert_eq!(codec.encode_len(&42), 1);
134/// // SAFETY: the input contains the one readable unit required by Identity.
135/// let (value, consumed) = unsafe { codec.decode(&[42], 0) }.unwrap();
136/// assert_eq!((value, consumed.get()), (42, 1));
137/// ```
138pub trait Codec {
139    /// The type of logical values decoded from or encoded into the buffer.
140    type Value;
141
142    /// The type of buffer units used by the encoded representation.
143    type Unit;
144
145    /// The type of errors reported when decoding malformed units.
146    type DecodeError;
147
148    /// The type of errors reported when encoding an unsupported value.
149    type EncodeError;
150
151    /// The minimum possible non-zero readable unit count for one decoded value.
152    ///
153    /// This is the minimum readable width of any valid encoded value. Checked
154    /// callers use it for planning and fast impossibility checks. If a
155    /// streaming decoder has fewer than this many readable units, no complete
156    /// value can be present at the current position. Unsafe
157    /// [`decode`](Self::decode) callers must provide at least this many
158    /// readable units at `index`.
159    ///
160    /// Default decode hooks use the input unit count as their output bound:
161    /// an invalid-input policy may consume fewer units than a valid value and
162    /// still emit one replacement value.
163    const MIN_UNITS_PER_VALUE: usize;
164
165    /// The maximum unit count emitted when encoding one value.
166    ///
167    /// This is a value-independent upper bound for the main encode phase. When
168    /// no concrete value is available, reserving this many writable units is
169    /// sufficient for any encodable value, without first calling
170    /// [`encode_len`](Self::encode_len). For a known value, callers may reserve
171    /// only the exact length returned by `encode_len` instead. This bound does
172    /// not include output produced by encode reset or finish phases.
173    ///
174    /// This is also the multiplier used by default encode hooks when estimating
175    /// the maximum number of output units needed for an input value count.
176    ///
177    /// The bound may be zero for a codec that buffers every accepted value and
178    /// emits retained output only during a later lifecycle phase.
179    const MAX_ENCODE_UNITS_PER_VALUE: usize;
180
181    /// The maximum non-zero unit count consumed to decode one value.
182    ///
183    /// This is a value-independent upper bound for one complete encoded value
184    /// or codec quantum on the decode side. Successful decode consumption and
185    /// the `required_total` carried by [`DecodeFailure::Incomplete`] must not
186    /// exceed this bound.
187    const MAX_DECODE_UNITS_PER_VALUE: usize;
188
189    /// The maximum unit count emitted when resetting encode state.
190    ///
191    /// This bound covers only output written by
192    /// [`encode_reset`](Self::encode_reset). It does not include hook-owned
193    /// reset output or any ordinary encoded input values. It must cover every
194    /// reachable pre-reset encode state. Stateless codecs should use the
195    /// default `0`.
196    const MAX_ENCODE_RESET_UNITS: usize = 0;
197
198    /// The maximum unit count emitted when finishing encode state at EOF.
199    ///
200    /// This bound covers only output written by
201    /// [`encode_finish`](Self::encode_finish). It does not include hook-owned
202    /// finish output and must cover every reachable encode state, even when the
203    /// current stream has no pending finish output. Stateless codecs should use
204    /// the default `0`. Codecs that emit a stream trailer (padding, checksum,
205    /// or end-of-stream marker) should override this with the exact maximum
206    /// unit count.
207    const MAX_ENCODE_FINISH_UNITS: usize = 0;
208
209    /// The maximum value count emitted when resetting decode state.
210    ///
211    /// This bound covers only values written by
212    /// [`decode_reset`](Self::decode_reset). It does not include hook-owned
213    /// reset output or values decoded from source units. It must cover every
214    /// reachable pre-reset decode state. Stateless codecs should use the
215    /// default `0`. Codecs that emit a stream-start sentinel or BOM on reset
216    /// should override this.
217    const MAX_DECODE_RESET_VALUES: usize = 0;
218
219    /// The maximum value count emitted when finishing decode state.
220    ///
221    /// This bound covers only values written by
222    /// [`decode_finish`](Self::decode_finish). It does not include hook-owned
223    /// finish output and must cover every reachable decode state, even when the
224    /// current stream has no pending finish output. Stateless codecs should use
225    /// the default `0`.
226    const MAX_DECODE_FINISH_VALUES: usize = 0;
227
228    /// Returns whether `value` is in this codec's encodable value domain.
229    ///
230    /// The default implementation returns `true`, which is correct for codecs
231    /// whose [`Value`](Self::Value) type contains only values they can encode.
232    /// Codecs whose logical value type is broader than their representation
233    /// domain, such as an ASCII codec with `Value = char`, must override this
234    /// method.
235    ///
236    /// Checked encoder adapters call this method in the same codec state used
237    /// to query [`encode_len`](Self::encode_len) and enter the unsafe
238    /// [`encode`](Self::encode) method. Complete-lifecycle adapters do so after
239    /// [`encode_reset`](Self::encode_reset). Direct unsafe callers must uphold
240    /// the same ordering.
241    ///
242    /// # Parameters
243    ///
244    /// - `value`: Value whose encodability is queried.
245    ///
246    /// # Returns
247    ///
248    /// Returns `true` when `value` may be passed to
249    /// [`encode_len`](Self::encode_len) and [`encode`](Self::encode).
250    #[inline]
251    #[must_use]
252    fn can_encode_value(&self, _value: &Self::Value) -> bool {
253        true
254    }
255
256    /// Returns the exact unit count this codec will write when encoding
257    /// `value`.
258    ///
259    /// The default implementation returns
260    /// [`MAX_ENCODE_UNITS_PER_VALUE`](Self::MAX_ENCODE_UNITS_PER_VALUE). This
261    /// default is correct only when every successful main encode writes exactly
262    /// that many units in the relevant codec state, as fixed-width codecs
263    /// normally do.
264    ///
265    /// Variable-width, buffering, or otherwise state-dependent codecs must
266    /// override this method to report the true encoded length for encodable
267    /// `value`s. The return value is never an estimate or an "unknown" marker:
268    /// it must equal the unit count [`encode`](Self::encode) subsequently
269    /// writes for the same `value` under the same codec state. It must also
270    /// never exceed
271    /// [`MAX_ENCODE_UNITS_PER_VALUE`](Self::MAX_ENCODE_UNITS_PER_VALUE).
272    /// Callers that do not yet have a concrete value should use
273    /// `MAX_ENCODE_UNITS_PER_VALUE` directly instead of calling this method.
274    ///
275    /// Default codec-backed encoders use this exact value for per-value output
276    /// capacity. The contract requires callers to use this method only when
277    /// [`can_encode_value`](Self::can_encode_value) returned `true` for the
278    /// same `value`.
279    ///
280    /// # Parameters
281    ///
282    /// - `value`: Value whose encoded length is queried.
283    ///
284    /// # Returns
285    ///
286    /// Returns the unit count [`encode`](Self::encode) will write for an
287    /// encodable `value`.
288    ///
289    /// A return value of `0` is valid for stateful encoders that accept a
290    /// value into internal state without immediately emitting units. Examples
291    /// include codecs that aggregate values into fixed-size quanta, shift-state
292    /// encodings, or framing layers that defer output until enough values have
293    /// been seen or EOF is finalized. Stateless and directly value-to-unit
294    /// codecs should continue returning a positive length.
295    #[inline]
296    #[must_use]
297    fn encode_len(&self, _value: &Self::Value) -> usize {
298        Self::MAX_ENCODE_UNITS_PER_VALUE
299    }
300
301    /// Emits stream-start output and resets encode-side state.
302    ///
303    /// # Parameters
304    ///
305    /// - `output`: Destination unit buffer.
306    /// - `output_index`: Start index in `output`.
307    ///
308    /// # Returns
309    ///
310    /// Returns the number of reset units written.
311    ///
312    /// # Errors
313    ///
314    /// Returns `Self::EncodeError` when reset output cannot be emitted.
315    /// Implementations must leave encode state unchanged when returning an
316    /// error.
317    ///
318    /// # Safety
319    ///
320    /// The caller must guarantee that the implementation can write up to
321    /// [`MAX_ENCODE_RESET_UNITS`](Self::MAX_ENCODE_RESET_UNITS) units starting
322    /// at `output_index`.
323    #[inline]
324    unsafe fn encode_reset(
325        &mut self,
326        _output: &mut [Self::Unit],
327        _output_index: usize,
328    ) -> Result<usize, Self::EncodeError> {
329        Ok(0)
330    }
331
332    /// Encodes one borrowed value into `output` starting at `output_index`.
333    ///
334    /// # Parameters
335    ///
336    /// - `value`: Value to encode.
337    /// - `output`: Destination unit buffer.
338    /// - `output_index`: Start index in `output`.
339    ///
340    /// # Returns
341    ///
342    /// Returns the number of written units.
343    ///
344    /// A successful encode may return `0` when the codec accepted `value` into
345    /// internal encode-side state but intentionally deferred output. This is
346    /// the normal shape for accumulative encoders such as base64-byte
347    /// aggregators, shift-state encodings, or frame builders. In that case
348    /// [`encode_len`](Self::encode_len) for the same `value` and state must
349    /// also return `0`, and the retained output must be emitted by a later
350    /// successful [`encode`](Self::encode),
351    /// [`encode_finish`](Self::encode_finish), or codec-specific facade.
352    ///
353    /// # Errors
354    ///
355    /// Returns `Self::EncodeError` for encode-side state or representation
356    /// failures other than a value being outside the codec's encodable domain.
357    /// Checked callers reject values for which
358    /// [`can_encode_value`](Self::can_encode_value) returns `false` before
359    /// entering this unsafe method. Implementations must leave their internal
360    /// state consistent when returning an error.
361    ///
362    /// # Safety
363    ///
364    /// The caller must guarantee that
365    /// [`can_encode_value`](Self::can_encode_value) returned `true` for
366    /// `value`. Starting at `output_index`, the caller must also provide either
367    /// at least
368    /// [`MAX_ENCODE_UNITS_PER_VALUE`](Self::MAX_ENCODE_UNITS_PER_VALUE)
369    /// writable
370    /// units, which is sufficient for every encodable value, or at least the
371    /// exact [`encode_len`](Self::encode_len) for the same `value` and codec
372    /// state. On success, implementations must return that exact written unit
373    /// count, including `0` for deliberate buffering, and the count must be no
374    /// larger than `MAX_ENCODE_UNITS_PER_VALUE`. Implementations must not write
375    /// beyond the exact `encode_len` capacity on either the success or error
376    /// path.
377    unsafe fn encode(
378        &mut self,
379        value: &Self::Value,
380        output: &mut [Self::Unit],
381        output_index: usize,
382    ) -> Result<usize, Self::EncodeError>;
383
384    /// Emits EOF trailer output and finishes encode-side state.
385    ///
386    /// This is the encode-side counterpart of
387    /// [`decode_finish`](Self::decode_finish). Codecs that append stream
388    /// trailers (padding, checksums, end-of-stream markers) emit them here.
389    /// Stateless codecs use the default no-op.
390    ///
391    /// # Parameters
392    ///
393    /// - `output`: Destination unit buffer.
394    /// - `output_index`: Start index in `output`.
395    ///
396    /// # Returns
397    ///
398    /// Returns the number of finish units written.
399    ///
400    /// # Errors
401    ///
402    /// Returns `Self::EncodeError` when finish output cannot be emitted.
403    /// Implementations must leave their internal state consistent when
404    /// returning an error.
405    ///
406    /// # Safety
407    ///
408    /// The caller must guarantee that the implementation can write up to
409    /// [`MAX_ENCODE_FINISH_UNITS`](Self::MAX_ENCODE_FINISH_UNITS) units
410    /// starting at `output_index`.
411    #[inline]
412    unsafe fn encode_finish(
413        &mut self,
414        _output: &mut [Self::Unit],
415        _output_index: usize,
416    ) -> Result<usize, Self::EncodeError> {
417        Ok(0)
418    }
419
420    /// Emits stream-start values and resets decode-side state.
421    ///
422    /// This is the decode-side counterpart of
423    /// [`encode_reset`](Self::encode_reset). Codecs that emit a
424    /// stream-start marker or BOM before decoding a new stream emit them
425    /// here. Stateless codecs use the default no-op.
426    ///
427    /// # Parameters
428    ///
429    /// - `output`: Destination value buffer.
430    /// - `output_index`: Start index in `output`.
431    ///
432    /// # Returns
433    ///
434    /// Returns the number of reset values written.
435    ///
436    /// # Errors
437    ///
438    /// Returns `Self::DecodeError` when reset output cannot be emitted.
439    /// Implementations must leave their internal state consistent when
440    /// returning an error.
441    ///
442    /// # Safety
443    ///
444    /// The caller must guarantee that the implementation can write up to
445    /// [`MAX_DECODE_RESET_VALUES`](Self::MAX_DECODE_RESET_VALUES) values
446    /// starting at `output_index`.
447    #[inline]
448    unsafe fn decode_reset(
449        &mut self,
450        _output: &mut [Self::Value],
451        _output_index: usize,
452    ) -> Result<usize, Self::DecodeError> {
453        Ok(0)
454    }
455
456    /// Decodes one value from `input` starting at `input_index`.
457    ///
458    /// # Parameters
459    ///
460    /// - `input`: Source unit buffer.
461    /// - `input_index`: Start index in `input`.
462    ///
463    /// # Returns
464    ///
465    /// Returns the decoded value and the non-zero number of consumed units.
466    ///
467    /// # Errors
468    ///
469    /// Returns [`DecodeFailure::Incomplete`] when the visible input is a
470    /// valid prefix but more units are needed to decide or complete a value.
471    /// This reports a streaming boundary, not a final EOF condition; the
472    /// caller or higher-level adapter decides what an incomplete tail means
473    /// when the upstream source is closed. Codec-specific context may be
474    /// retained in the failure's optional `source` field.
475    /// Returns [`DecodeFailure::Invalid`] when the units are malformed,
476    /// non-canonical, unmappable, or otherwise invalid for this codec and the
477    /// span is known or unknown. Unknown span is represented as
478    /// [`DecodeFailure::Invalid`] with an unknown consumed-unit hint.
479    /// Implementations must leave their internal state consistent when
480    /// returning an error.
481    ///
482    /// # Safety
483    ///
484    /// The caller must guarantee that `input_index` is a valid boundary in
485    /// `input` and that at least
486    /// [`MIN_UNITS_PER_VALUE`](Self::MIN_UNITS_PER_VALUE)
487    /// units are readable from `input_index`. Implementations must not read
488    /// beyond the currently available units under that precondition. They
489    /// may return [`DecodeFailure::Incomplete`] when those units are a
490    /// valid but incomplete prefix.
491    ///
492    /// On success, implementations must return a consumed unit count no larger
493    /// than either the available input or
494    /// [`MAX_DECODE_UNITS_PER_VALUE`](Self::MAX_DECODE_UNITS_PER_VALUE). An
495    /// incomplete result's `required_total` must also not exceed that maximum.
496    /// When returning [`DecodeFailure::Incomplete`], implementations must
497    /// satisfy `input.len() - input_index < required_total.get()` and
498    /// `required_total.get() <= Self::MAX_DECODE_UNITS_PER_VALUE`. The bound
499    /// is the minimum total number of units from the value start, not the
500    /// number of additional units to append. With two units available and at
501    /// least one more needed, report three, not one or two.
502    /// The return type guarantees that successful decoding always consumes at
503    /// least one unit. Implementations should use `debug_assert!` to state
504    /// these unchecked entry-point assumptions.
505    unsafe fn decode(
506        &mut self,
507        input: &[Self::Unit],
508        input_index: usize,
509    ) -> Result<(Self::Value, NonZeroUsize), DecodeFailure<Self::DecodeError>>;
510
511    /// Decodes one value after the caller has established end of input.
512    ///
513    /// This method has the same safety and state guarantees as
514    /// [`decode`](Self::decode), but may resolve an otherwise incomplete
515    /// trailing prefix using EOF-aware format rules. The default preserves the
516    /// open-stream behavior by delegating to [`decode`](Self::decode).
517    ///
518    /// # Parameters
519    ///
520    /// - `input`: Final source unit buffer; no more units will arrive.
521    /// - `input_index`: Start index of the value in `input`.
522    ///
523    /// # Returns
524    ///
525    /// Returns the decoded value and the non-zero number of consumed units.
526    ///
527    /// # Errors
528    ///
529    /// Returns [`DecodeFailure::Incomplete`] for an unresolved final prefix,
530    /// or [`DecodeFailure::Invalid`] for malformed input, as in
531    /// [`decode`](Self::decode). An override may resolve a prefix at EOF.
532    /// When returning [`DecodeFailure::Incomplete`], implementations must
533    /// satisfy `input.len() - input_index < required_total.get()` and
534    /// `required_total.get() <= Self::MAX_DECODE_UNITS_PER_VALUE`, as for
535    /// [`decode`](Self::decode). `required_total` is the minimum total number
536    /// of units from the value start, not the number of additional units to
537    /// append: with two units available and at least one more needed, report
538    /// three, not one or two. This condition also applies at EOF.
539    ///
540    /// # Safety
541    ///
542    /// The caller must satisfy the same input-index and minimum-readable-unit
543    /// preconditions as [`decode`](Self::decode). Implementations must not
544    /// read beyond the currently available units.
545    #[inline]
546    unsafe fn decode_eof(
547        &mut self,
548        input: &[Self::Unit],
549        input_index: usize,
550    ) -> Result<(Self::Value, NonZeroUsize), DecodeFailure<Self::DecodeError>> {
551        // SAFETY: `decode_eof` has the same preconditions as `decode`.
552        unsafe { self.decode(input, input_index) }
553    }
554
555    /// Finishes decode-side EOF state into `output`.
556    ///
557    /// `decode_finish` receives no source input. Callers must have already
558    /// handled any tail reported by [`DecodeFailure::Incomplete`] before
559    /// finishing decode state. Implementations may emit retained values or
560    /// validate internal EOF state, but they must not depend on re-reading the
561    /// incomplete source tail.
562    ///
563    /// # Parameters
564    ///
565    /// - `output`: Destination value buffer.
566    /// - `output_index`: Start index in `output`.
567    ///
568    /// # Returns
569    ///
570    /// Returns the number of finished values written.
571    ///
572    /// # Errors
573    ///
574    /// Returns `Self::DecodeError` when retained decode state is invalid at
575    /// EOF. Implementations must leave their internal state consistent when
576    /// returning an error.
577    ///
578    /// # Safety
579    ///
580    /// The caller must guarantee that the implementation can write up to
581    /// [`MAX_DECODE_FINISH_VALUES`](Self::MAX_DECODE_FINISH_VALUES) values
582    /// starting at `output_index`.
583    #[inline]
584    unsafe fn decode_finish(
585        &mut self,
586        _output: &mut [Self::Value],
587        _output_index: usize,
588    ) -> Result<usize, Self::DecodeError> {
589        Ok(0)
590    }
591}