Skip to main content

qubit_codec_binary/codec/
leb128_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::convert::Infallible;
10use core::marker::PhantomData;
11use core::num::NonZeroUsize;
12
13use qubit_codec::Codec;
14use qubit_codec::DecodeFailure;
15use qubit_utils::UncheckedSlice;
16use qubit_utils::nonzero;
17
18use crate::Leb128DecodeError;
19use crate::Leb128DecodePolicy;
20
21/// Maps detailed LEB128 decoding failures to the generic codec failure type.
22///
23/// Incomplete input preserves its minimum total byte requirement. Malformed
24/// and non-canonical input retain the original error and its consumed byte
25/// count for progress under the caller's invalid-input policy. This count
26/// does not guarantee recovery at a protocol field boundary.
27///
28/// # Parameters
29///
30/// - `error`: Detailed LEB128 decode failure to preserve in the generic codec
31///   failure.
32#[inline]
33pub(in crate::codec) fn map_leb128_decode_failure(error: Leb128DecodeError) -> DecodeFailure<Leb128DecodeError> {
34    if let Some(required) = error.required() {
35        DecodeFailure::incomplete_with_source(error, required)
36    } else {
37        let consumed = error
38            .consumed()
39            .expect("invalid LEB128 decode errors always report consumed bytes");
40        DecodeFailure::invalid(error, consumed)
41    }
42}
43
44/// Type-level unchecked LEB128 codec.
45///
46/// Encoding is always canonical; `P` only affects decoding. Encoding-only
47/// callers should conventionally use [`crate::NonStrict`] because no decoding
48/// policy is applied on that path.
49///
50/// # Type Parameters
51///
52/// - `T`: Integer value type to decode from LEB128 bytes and encode into
53///   canonical LEB128 bytes.
54/// - `P`: Required type-level decoding policy implementing
55///   [`Leb128DecodePolicy`]. Use [`crate::Strict`] to reject non-canonical
56///   inputs, or [`crate::NonStrict`] to accept non-canonical inputs. This
57///   parameter does not affect canonical encoding.
58///
59/// The decoding policy is intentionally required so wire-format callers make
60/// the canonicality contract explicit.
61/// Non-canonical input accepted by [`crate::NonStrict`] must still fit the
62/// target integer's maximum decode width and terminal payload bits. See that
63/// policy's documentation for the width limits and an example.
64///
65/// ```compile_fail
66/// use qubit_codec_binary::Leb128Codec;
67///
68/// let _ = Leb128Codec::<u64>::default();
69/// ```
70///
71/// # Examples
72///
73/// ```
74/// use qubit_codec_binary::{
75///     Leb128Codec,
76///     NonStrict,
77/// };
78///
79/// let mut output = [0_u8; Leb128Codec::<u64, NonStrict>::MAX_ENCODE_UNITS_PER_VALUE];
80/// let written = unsafe {
81///     Leb128Codec::<u64, NonStrict>::encode(300, &mut output, 0)
82/// };
83/// assert_eq!(2, written);
84///
85/// let (decoded, consumed) = unsafe {
86///     Leb128Codec::<u64, NonStrict>::decode(&output[..written], 0)
87/// }.expect("canonical LEB128 value should decode");
88/// assert_eq!(300, decoded);
89/// assert_eq!(2, consumed.get());
90/// ```
91#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
92pub struct Leb128Codec<T, P> {
93    /// Associates the value and decode-policy types without storing either.
94    marker: PhantomData<fn() -> (T, P)>,
95}
96
97macro_rules! impl_unsigned_leb128_codec {
98    ($ty:ty) => {
99        impl<P> Leb128Codec<$ty, P>
100        where
101            P: Leb128DecodePolicy,
102        {
103            /// Minimum number of bytes that can represent a complete value.
104            pub const MIN_UNITS_PER_VALUE: usize = <Self as Codec>::MIN_UNITS_PER_VALUE;
105
106            /// Maximum number of bytes emitted when encoding this type.
107            pub const MAX_ENCODE_UNITS_PER_VALUE: usize = <Self as Codec>::MAX_ENCODE_UNITS_PER_VALUE;
108
109            /// Maximum number of bytes consumed when decoding this type.
110            pub const MAX_DECODE_UNITS_PER_VALUE: usize = <Self as Codec>::MAX_DECODE_UNITS_PER_VALUE;
111
112            /// Decodes a value from `input` starting at `input_index` without
113            /// bounds checks.
114            ///
115            /// # Parameters
116            ///
117            /// - `input`: Source byte buffer.
118            /// - `input_index`: Start index in `input`.
119            ///
120            /// # Returns
121            ///
122            /// Returns the decoded value and the non-zero number of consumed
123            /// bytes.
124            ///
125            /// # Errors
126            ///
127            /// Returns [`Leb128DecodeError`] if the bytes are incomplete,
128            /// malformed, or strict decoding rejects a non-canonical
129            /// representation.
130            ///
131            /// # Safety
132            ///
133            /// The caller must guarantee that `input_index` is a valid boundary
134            /// and at least [`Self::MIN_UNITS_PER_VALUE`] byte is readable
135            /// from `input_index`.
136            #[inline]
137            pub unsafe fn decode(input: &[u8], input_index: usize) -> Result<($ty, NonZeroUsize), Leb128DecodeError> {
138                debug_assert!(input.len().saturating_sub(input_index) >= Self::MIN_UNITS_PER_VALUE);
139
140                // SAFETY: The caller guarantees enough readable bytes for this
141                // type.
142                let (value, consumed) = unsafe {
143                    read_uleb_unchecked::<P>(input, input_index, <$ty>::BITS, Self::MAX_DECODE_UNITS_PER_VALUE)?
144                };
145                Ok((value as $ty, consumed))
146            }
147
148            /// Encodes `value` into `output` starting at `output_index` without
149            /// bounds checks.
150            ///
151            /// # Parameters
152            ///
153            /// - `value`: Value to encode.
154            /// - `output`: Destination byte buffer.
155            /// - `output_index`: Start index in `output`.
156            ///
157            /// # Returns
158            ///
159            /// Returns the number of written bytes.
160            ///
161            /// # Safety
162            ///
163            /// The caller must guarantee that the canonical unsigned LEB128
164            /// byte width of `value` is writable starting at `output_index`.
165            /// Reserving [`Self::MAX_ENCODE_UNITS_PER_VALUE`] bytes always satisfies
166            /// this requirement; for a known value, the exact
167            /// [`Codec::encode_len`] is sufficient.
168            #[must_use = "the returned byte count determines the encoded payload range"]
169            #[inline]
170            pub unsafe fn encode(value: $ty, output: &mut [u8], output_index: usize) -> usize {
171                // SAFETY: The caller guarantees enough writable bytes for the
172                // canonical representation of this value.
173                unsafe { write_uleb_unchecked(output, output_index, value as u128) }
174            }
175        }
176
177        impl<P> Codec for Leb128Codec<$ty, P>
178        where
179            P: Leb128DecodePolicy,
180        {
181            /// The unsigned integer represented by this codec.
182            type Value = $ty;
183            /// One byte of the LEB128 representation.
184            type Unit = u8;
185            /// Detailed errors for incomplete, malformed, or policy-rejected input.
186            type DecodeError = Leb128DecodeError;
187            /// Encoding is infallible for every value of this integer type.
188            type EncodeError = Infallible;
189
190            /// Minimum bytes readable before decoding can be attempted.
191            const MIN_UNITS_PER_VALUE: usize = 1;
192            /// Maximum bytes emitted by canonical unsigned LEB128 encoding.
193            const MAX_ENCODE_UNITS_PER_VALUE: usize = (<$ty>::BITS as usize).div_ceil(7);
194            /// Maximum bytes consumed by decoding this integer type.
195            const MAX_DECODE_UNITS_PER_VALUE: usize = (<$ty>::BITS as usize).div_ceil(7);
196
197            /// Returns the exact width of the canonical unsigned LEB128 encoding.
198            ///
199            /// # Parameters
200            ///
201            /// - `value`: Integer value whose encoded width is queried.
202            ///
203            /// # Returns
204            ///
205            /// Returns a width of at least one byte and no more than
206            /// [`Self::MAX_ENCODE_UNITS_PER_VALUE`]. The decoding policy does not
207            /// affect this length.
208            #[inline]
209            fn encode_len(&self, value: &$ty) -> usize {
210                uleb_encoded_len(*value as u128)
211            }
212
213            /// Decodes one unsigned LEB128 value and reports its byte consumption.
214            ///
215            /// # Parameters
216            ///
217            /// - `input`: Source bytes.
218            /// - `input_index`: Start index of the encoded value.
219            ///
220            /// # Returns
221            ///
222            /// Returns the decoded value and the non-zero number of bytes consumed.
223            ///
224            /// # Errors
225            ///
226            /// Returns [`DecodeFailure::Incomplete`] with the detailed error
227            /// retained as its source and a minimum total byte requirement when
228            /// a valid prefix needs more input. Returns [`DecodeFailure::Invalid`]
229            /// with the detailed error and consumed-byte count for malformed
230            /// input or, under [`crate::Strict`], a non-canonical representation.
231            /// The required count is a lower bound, not a guarantee that decoding
232            /// will succeed at that length. The consumed count is not a guaranteed
233            /// protocol-field recovery boundary.
234            /// [`crate::NonStrict`] still enforces the target integer's maximum
235            /// decode width and terminal payload-bit limits; the policy only
236            /// changes canonicality checks.
237            ///
238            /// # Safety
239            ///
240            /// `input_index` must be a valid boundary and at least
241            /// [`Self::MIN_UNITS_PER_VALUE`] bytes must be readable there.
242            #[inline]
243            unsafe fn decode(
244                &mut self,
245                input: &[u8],
246                input_index: usize,
247            ) -> Result<($ty, NonZeroUsize), DecodeFailure<Self::DecodeError>> {
248                debug_assert!(input.len().saturating_sub(input_index) >= Self::MIN_UNITS_PER_VALUE);
249
250                // SAFETY: The caller upholds the `Codec::decode`
251                // contract.
252                unsafe { Self::decode(input, input_index) }.map_err(map_leb128_decode_failure)
253            }
254
255            /// Encodes one value using its canonical unsigned LEB128 representation.
256            ///
257            /// # Parameters
258            ///
259            /// - `value`: Integer value to encode.
260            /// - `output`: Destination byte buffer.
261            /// - `output_index`: Start index in `output`.
262            ///
263            /// # Returns
264            ///
265            /// Returns the number of bytes written, equal to
266            /// [`Self::encode_len`] for `value`.
267            ///
268            /// # Errors
269            ///
270            /// This implementation uses [`Infallible`]; encoding an unsigned
271            /// integer value cannot fail.
272            ///
273            /// # Safety
274            ///
275            /// The caller must ensure [`Codec::can_encode_value`] returned
276            /// `true` for `value`. Starting at `output_index`, provide either
277            /// the exact [`Self::encode_len`] capacity for `value` or at least
278            /// [`Self::MAX_ENCODE_UNITS_PER_VALUE`] writable bytes.
279            #[inline]
280            unsafe fn encode(
281                &mut self,
282                value: &$ty,
283                output: &mut [u8],
284                output_index: usize,
285            ) -> Result<usize, Self::EncodeError> {
286                let required = self.encode_len(value);
287                debug_assert!(output.len().saturating_sub(output_index) >= required);
288
289                // SAFETY: The `Codec::encode` contract provides either the
290                // exact canonical width or this type's maximum width.
291                let written = unsafe { Self::encode(*value, output, output_index) };
292                Ok(written)
293            }
294        }
295    };
296}
297
298macro_rules! impl_signed_leb128_codec {
299    ($ty:ty) => {
300        impl<P> Leb128Codec<$ty, P>
301        where
302            P: Leb128DecodePolicy,
303        {
304            /// Minimum number of bytes that can represent a complete value.
305            pub const MIN_UNITS_PER_VALUE: usize = <Self as Codec>::MIN_UNITS_PER_VALUE;
306
307            /// Maximum number of bytes emitted when encoding this type.
308            pub const MAX_ENCODE_UNITS_PER_VALUE: usize = <Self as Codec>::MAX_ENCODE_UNITS_PER_VALUE;
309
310            /// Maximum number of bytes consumed when decoding this type.
311            pub const MAX_DECODE_UNITS_PER_VALUE: usize = <Self as Codec>::MAX_DECODE_UNITS_PER_VALUE;
312
313            /// Decodes a value from `input` starting at `input_index` without bounds
314            /// checks.
315            ///
316            /// # Parameters
317            ///
318            /// - `input`: Source byte buffer.
319            /// - `input_index`: Start index in `input`.
320            ///
321            /// # Returns
322            ///
323            /// Returns the decoded value and the non-zero number of consumed
324            /// bytes.
325            ///
326            /// # Errors
327            ///
328            /// Returns [`Leb128DecodeError`] if the bytes are incomplete,
329            /// malformed, or strict decoding rejects a non-canonical
330            /// representation.
331            ///
332            /// # Safety
333            ///
334            /// The caller must guarantee that `input_index` is a valid boundary
335            /// and at least [`Self::MIN_UNITS_PER_VALUE`] byte is readable
336            /// from `input_index`.
337            #[inline]
338            pub unsafe fn decode(input: &[u8], input_index: usize) -> Result<($ty, NonZeroUsize), Leb128DecodeError> {
339                debug_assert!(input.len().saturating_sub(input_index) >= Self::MIN_UNITS_PER_VALUE);
340
341                // SAFETY: The caller guarantees enough readable bytes for this
342                // type.
343                let (value, consumed) = unsafe {
344                    read_sleb_unchecked::<P>(input, input_index, <$ty>::BITS, Self::MAX_DECODE_UNITS_PER_VALUE)?
345                };
346                Ok((value as $ty, consumed))
347            }
348
349            /// Encodes `value` into `output` starting at `output_index` without bounds
350            /// checks.
351            ///
352            /// # Parameters
353            ///
354            /// - `value`: Value to encode.
355            /// - `output`: Destination byte buffer.
356            /// - `output_index`: Start index in `output`.
357            ///
358            /// # Returns
359            ///
360            /// Returns the number of written bytes.
361            ///
362            /// # Safety
363            ///
364            /// The caller must guarantee that the canonical signed LEB128 byte
365            /// width of `value` is writable starting at `output_index`.
366            /// Reserving [`Self::MAX_ENCODE_UNITS_PER_VALUE`] bytes always satisfies
367            /// this requirement; for a known value, the exact
368            /// [`Codec::encode_len`] is sufficient.
369            #[must_use = "the returned byte count determines the encoded payload range"]
370            #[inline]
371            pub unsafe fn encode(value: $ty, output: &mut [u8], output_index: usize) -> usize {
372                // SAFETY: The caller guarantees enough writable bytes for the
373                // canonical representation of this value.
374                unsafe { write_sleb_unchecked(output, output_index, value as i128) }
375            }
376        }
377
378        impl<P> Codec for Leb128Codec<$ty, P>
379        where
380            P: Leb128DecodePolicy,
381        {
382            /// The signed integer represented by this codec.
383            type Value = $ty;
384            /// One byte of the LEB128 representation.
385            type Unit = u8;
386            /// Detailed errors for incomplete, malformed, or policy-rejected input.
387            type DecodeError = Leb128DecodeError;
388            /// Encoding is infallible for every value of this integer type.
389            type EncodeError = Infallible;
390
391            /// Minimum bytes readable before decoding can be attempted.
392            const MIN_UNITS_PER_VALUE: usize = 1;
393            /// Maximum bytes emitted by canonical signed LEB128 encoding.
394            const MAX_ENCODE_UNITS_PER_VALUE: usize = (<$ty>::BITS as usize).div_ceil(7);
395            /// Maximum bytes consumed by decoding this integer type.
396            const MAX_DECODE_UNITS_PER_VALUE: usize = (<$ty>::BITS as usize).div_ceil(7);
397
398            /// Returns the exact width of the canonical signed LEB128 encoding.
399            ///
400            /// # Parameters
401            ///
402            /// - `value`: Integer value whose encoded width is queried.
403            ///
404            /// # Returns
405            ///
406            /// Returns a width of at least one byte and no more than
407            /// [`Self::MAX_ENCODE_UNITS_PER_VALUE`]. The decoding policy does not
408            /// affect this length.
409            #[inline]
410            fn encode_len(&self, value: &$ty) -> usize {
411                sleb_encoded_len(*value as i128)
412            }
413
414            /// Decodes one signed LEB128 value and reports its byte consumption.
415            ///
416            /// # Parameters
417            ///
418            /// - `input`: Source bytes.
419            /// - `input_index`: Start index of the encoded value.
420            ///
421            /// # Returns
422            ///
423            /// Returns the decoded value and the non-zero number of bytes consumed.
424            ///
425            /// # Errors
426            ///
427            /// Returns [`DecodeFailure::Incomplete`] with the detailed error
428            /// retained as its source and a minimum total byte requirement when
429            /// a valid prefix needs more input. Returns [`DecodeFailure::Invalid`]
430            /// with the detailed error and consumed-byte count for malformed
431            /// input or, under [`crate::Strict`], a non-canonical representation.
432            /// The required count is a lower bound, not a guarantee that decoding
433            /// will succeed at that length. The consumed count is not a guaranteed
434            /// protocol-field recovery boundary.
435            /// [`crate::NonStrict`] still enforces the target integer's maximum
436            /// decode width and terminal payload-bit limits; the policy only
437            /// changes canonicality checks.
438            ///
439            /// # Safety
440            ///
441            /// `input_index` must be a valid boundary and at least
442            /// [`Self::MIN_UNITS_PER_VALUE`] bytes must be readable there.
443            #[inline]
444            unsafe fn decode(
445                &mut self,
446                input: &[u8],
447                input_index: usize,
448            ) -> Result<($ty, NonZeroUsize), DecodeFailure<Self::DecodeError>> {
449                debug_assert!(input.len().saturating_sub(input_index) >= Self::MIN_UNITS_PER_VALUE);
450
451                // SAFETY: The caller upholds the `Codec::decode`
452                // contract.
453                unsafe { Self::decode(input, input_index) }.map_err(map_leb128_decode_failure)
454            }
455
456            /// Encodes one value using its canonical signed LEB128 representation.
457            ///
458            /// # Parameters
459            ///
460            /// - `value`: Integer value to encode.
461            /// - `output`: Destination byte buffer.
462            /// - `output_index`: Start index in `output`.
463            ///
464            /// # Returns
465            ///
466            /// Returns the number of bytes written, equal to
467            /// [`Self::encode_len`] for `value`.
468            ///
469            /// # Errors
470            ///
471            /// This implementation uses [`Infallible`]; encoding a signed
472            /// integer value cannot fail.
473            ///
474            /// # Safety
475            ///
476            /// The caller must ensure [`Codec::can_encode_value`] returned
477            /// `true` for `value`. Starting at `output_index`, provide either
478            /// the exact [`Self::encode_len`] capacity for `value` or at least
479            /// [`Self::MAX_ENCODE_UNITS_PER_VALUE`] writable bytes.
480            #[inline]
481            unsafe fn encode(
482                &mut self,
483                value: &$ty,
484                output: &mut [u8],
485                output_index: usize,
486            ) -> Result<usize, Self::EncodeError> {
487                let required = self.encode_len(value);
488                debug_assert!(output.len().saturating_sub(output_index) >= required);
489
490                // SAFETY: The `Codec::encode` contract provides either the
491                // exact canonical width or this type's maximum width.
492                let written = unsafe { Self::encode(*value, output, output_index) };
493                Ok(written)
494            }
495        }
496    };
497}
498
499impl_unsigned_leb128_codec!(u8);
500impl_unsigned_leb128_codec!(u16);
501impl_unsigned_leb128_codec!(u32);
502impl_unsigned_leb128_codec!(u64);
503impl_unsigned_leb128_codec!(u128);
504impl_unsigned_leb128_codec!(usize);
505
506impl_signed_leb128_codec!(i8);
507impl_signed_leb128_codec!(i16);
508impl_signed_leb128_codec!(i32);
509impl_signed_leb128_codec!(i64);
510impl_signed_leb128_codec!(i128);
511impl_signed_leb128_codec!(isize);
512
513/// Decodes an unsigned LEB128 value without bounds checks.
514///
515/// # Type Parameters
516///
517/// - `P`: Type-level decoding policy used to decide whether non-canonical
518///   encodings are accepted.
519///
520/// # Parameters
521///
522/// - `input`: Source byte buffer.
523/// - `index`: Start index in `input`.
524/// - `bits`: Bit width of the target integer type.
525/// - `max_bytes`: Maximum number of bytes allowed for that target width.
526///
527/// # Returns
528///
529/// Returns the decoded value and the non-zero number of consumed bytes.
530///
531/// # Errors
532///
533/// Returns [`Leb128DecodeError`] when the byte sequence is incomplete,
534/// malformed, or when `P` rejects a non-canonical encoding.
535///
536/// # Safety
537///
538/// The caller must guarantee that at least one byte is readable from `index`.
539#[inline]
540unsafe fn read_uleb_unchecked<P>(
541    input: &[u8],
542    index: usize,
543    bits: u32,
544    max_bytes: usize,
545) -> Result<(u128, NonZeroUsize), Leb128DecodeError>
546where
547    P: Leb128DecodePolicy,
548{
549    debug_assert!(input.len().saturating_sub(index) >= 1);
550
551    let available = input.len().saturating_sub(index).min(max_bytes);
552    // SAFETY: The caller guarantees that the currently available bytes are
553    // readable from `index`.
554    match unsafe { read_uleb_prefix_unchecked::<P>(input, index, bits, max_bytes, available) } {
555        Ok(Some((value, consumed))) => {
556            debug_assert!(consumed > 0);
557            // SAFETY: Prefix readers only return `Some` after consuming at
558            // least one terminating byte.
559            let consumed = nonzero(consumed);
560            Ok((value, consumed))
561        }
562        Ok(None) => {
563            debug_assert!(available < usize::MAX, "available byte count overflowed");
564            // SAFETY: Adding one to the available byte count produces a
565            // non-zero retry lower bound.
566            let required = nonzero(available + 1);
567            Err(Leb128DecodeError::incomplete(index, required, available))
568        }
569        Err(error) => Err(error),
570    }
571}
572
573/// Tries to decode an unsigned LEB128 value from currently available bytes.
574///
575/// # Type Parameters
576///
577/// - `P`: Type-level decoding policy used to decide whether non-canonical
578///   encodings are accepted.
579///
580/// # Parameters
581///
582/// - `input`: Source byte buffer.
583/// - `index`: Start index in `input`.
584/// - `bits`: Bit width of the target integer type.
585/// - `max_bytes`: Maximum number of bytes allowed for that target width.
586/// - `available`: Number of bytes currently readable from `index`.
587///
588/// # Returns
589///
590/// Returns `Ok(Some((value, consumed)))` when a complete value is decoded,
591/// `Ok(None)` when more bytes are needed, or `Err(error)` when the payload is
592/// invalid. Invalid errors carry the consumable byte count.
593///
594/// # Safety
595///
596/// The caller must guarantee that `input.as_ptr().add(index)` is valid to read
597/// `available` bytes and that `available <= max_bytes`.
598#[inline]
599unsafe fn read_uleb_prefix_unchecked<P>(
600    input: &[u8],
601    index: usize,
602    bits: u32,
603    max_bytes: usize,
604    available: usize,
605) -> Result<Option<(u128, usize)>, Leb128DecodeError>
606where
607    P: Leb128DecodePolicy,
608{
609    debug_assert!(available <= max_bytes, "available bytes exceed LEB128 maximum width");
610    let mut value = 0u128;
611    let mut shift = 0u32;
612    for offset in 0..available {
613        // SAFETY: The caller guarantees enough readable bytes for this loop.
614        let byte = unsafe { UncheckedSlice::read(input, index + offset) };
615        let payload = u128::from(byte & 0x7F);
616        value |= payload << shift;
617        if byte & 0x80 == 0 {
618            if offset == max_bytes - 1 && !unsigned_final_payload_fits(byte, bits, offset) {
619                return Err(malformed_decode_error(index, index + offset, offset + 1));
620            }
621            let consumed = offset + 1;
622            if P::STRICT && !is_canonical_uleb_terminal(offset, byte) {
623                return Err(noncanonical_decode_error(index, consumed));
624            }
625            return Ok(Some((value, consumed)));
626        }
627        shift += 7;
628    }
629    if available < max_bytes {
630        return Ok(None);
631    }
632    Err(malformed_decode_error(index, index + max_bytes - 1, max_bytes))
633}
634
635/// Decodes a signed LEB128 value without bounds checks.
636///
637/// # Type Parameters
638///
639/// - `P`: Type-level decoding policy used to decide whether non-canonical
640///   encodings are accepted.
641///
642/// # Parameters
643///
644/// - `input`: Source byte buffer.
645/// - `index`: Start index in `input`.
646/// - `bits`: Bit width of the target integer type.
647/// - `max_bytes`: Maximum number of bytes allowed for that target width.
648///
649/// # Returns
650///
651/// Returns the decoded value and the non-zero number of consumed bytes.
652///
653/// # Errors
654///
655/// Returns [`Leb128DecodeError`] when the byte sequence is incomplete,
656/// malformed, or when `P` rejects a non-canonical encoding.
657///
658/// # Safety
659///
660/// The caller must guarantee that at least one byte is readable from `index`.
661#[inline]
662unsafe fn read_sleb_unchecked<P>(
663    input: &[u8],
664    index: usize,
665    bits: u32,
666    max_bytes: usize,
667) -> Result<(i128, NonZeroUsize), Leb128DecodeError>
668where
669    P: Leb128DecodePolicy,
670{
671    debug_assert!(input.len().saturating_sub(index) >= 1);
672
673    let available = input.len().saturating_sub(index).min(max_bytes);
674    // SAFETY: The caller guarantees that the currently available bytes are
675    // readable from `index`.
676    match unsafe { read_sleb_prefix_unchecked::<P>(input, index, bits, max_bytes, available) } {
677        Ok(Some((value, consumed))) => {
678            debug_assert!(consumed > 0);
679            // SAFETY: Prefix readers only return `Some` after consuming at
680            // least one terminating byte.
681            let consumed = nonzero(consumed);
682            Ok((value, consumed))
683        }
684        Ok(None) => {
685            debug_assert!(available < usize::MAX, "available byte count overflowed");
686            // SAFETY: Adding one to the available byte count produces a
687            // non-zero retry lower bound.
688            let required = nonzero(available + 1);
689            Err(Leb128DecodeError::incomplete(index, required, available))
690        }
691        Err(error) => Err(error),
692    }
693}
694
695/// Tries to decode a signed LEB128 value from currently available bytes.
696///
697/// # Type Parameters
698///
699/// - `P`: Type-level decoding policy used to decide whether non-canonical
700///   encodings are accepted.
701///
702/// # Parameters
703///
704/// - `input`: Source byte buffer.
705/// - `index`: Start index in `input`.
706/// - `bits`: Bit width of the target integer type.
707/// - `max_bytes`: Maximum number of bytes allowed for that target width.
708/// - `available`: Number of bytes currently readable from `index`.
709///
710/// # Returns
711///
712/// Returns `Ok(Some((value, consumed)))` when a complete value is decoded,
713/// `Ok(None)` when more bytes are needed, or `Err(error)` when the payload is
714/// invalid. Invalid errors carry the consumable byte count.
715///
716/// # Safety
717///
718/// The caller must guarantee that `input.as_ptr().add(index)` is valid to read
719/// `available` bytes and that `available <= max_bytes`.
720#[inline]
721unsafe fn read_sleb_prefix_unchecked<P>(
722    input: &[u8],
723    index: usize,
724    bits: u32,
725    max_bytes: usize,
726    available: usize,
727) -> Result<Option<(i128, usize)>, Leb128DecodeError>
728where
729    P: Leb128DecodePolicy,
730{
731    debug_assert!(available <= max_bytes, "available bytes exceed LEB128 maximum width");
732    let mut value = 0i128;
733    let mut shift = 0u32;
734    let mut previous_byte = 0u8;
735    for offset in 0..available {
736        // SAFETY: The caller guarantees enough readable bytes for this loop.
737        let byte = unsafe { UncheckedSlice::read(input, index + offset) };
738        let payload = i128::from(byte & 0x7F);
739        value |= payload << shift;
740        if byte & 0x80 == 0 {
741            if offset == max_bytes - 1 && !signed_final_payload_fits(byte, bits, offset) {
742                return Err(malformed_decode_error(index, index + offset, offset + 1));
743            }
744            if byte & 0x40 != 0 && shift + 7 < i128::BITS {
745                value |= (!0i128) << (shift + 7);
746            }
747            let consumed = offset + 1;
748            if P::STRICT && !is_canonical_sleb_terminal(offset, previous_byte, byte) {
749                return Err(noncanonical_decode_error(index, consumed));
750            }
751            return Ok(Some((value, consumed)));
752        }
753        previous_byte = byte;
754        shift += 7;
755    }
756    if available < max_bytes {
757        return Ok(None);
758    }
759    Err(malformed_decode_error(index, index + max_bytes - 1, max_bytes))
760}
761
762/// Builds a malformed LEB128 error on the cold error path.
763///
764/// # Parameters
765///
766/// - `start_index`: Absolute byte index where the malformed payload starts.
767/// - `error_index`: Absolute byte index associated with the malformed payload.
768/// - `consumed`: Number of bytes that should be consumed before reporting the
769///   error.
770///
771/// # Returns
772///
773/// Returns the error carrying the byte count to consume.
774#[cold]
775fn malformed_decode_error(start_index: usize, error_index: usize, consumed: usize) -> Leb128DecodeError {
776    debug_assert!(consumed > 0, "malformed LEB128 errors must consume bytes");
777    // SAFETY: All malformed call sites pass either `offset + 1` or `max_bytes`,
778    // both of which are non-zero for supported LEB128 codecs.
779    let consumed = nonzero(consumed);
780    Leb128DecodeError::malformed(start_index, error_index, consumed)
781}
782
783/// Builds a non-canonical LEB128 error on the cold error path.
784///
785/// # Parameters
786///
787/// - `index`: Absolute byte index at which the non-canonical payload starts.
788/// - `consumed`: Number of bytes that should be consumed before reporting the
789///   error.
790///
791/// # Returns
792///
793/// Returns the error carrying the byte count to consume.
794#[cold]
795fn noncanonical_decode_error(index: usize, consumed: usize) -> Leb128DecodeError {
796    debug_assert!(consumed > 0, "non-canonical LEB128 errors must consume bytes");
797    // SAFETY: Non-canonical errors are detected only after reading at least one
798    // terminating byte.
799    let consumed = nonzero(consumed);
800    Leb128DecodeError::noncanonical(index, consumed)
801}
802
803/// Checks whether the final unsigned LEB128 payload byte fits the target width.
804///
805/// # Parameters
806///
807/// - `byte`: Final LEB128 byte to validate.
808/// - `bits`: Bit width of the target unsigned integer type.
809/// - `offset`: Zero-based byte offset of `byte` within the encoded value.
810///
811/// # Returns
812///
813/// Returns `true` if the unused payload bits are all zero.
814#[must_use]
815#[inline]
816fn unsigned_final_payload_fits(byte: u8, bits: u32, offset: usize) -> bool {
817    let used_bits = bits - offset as u32 * 7;
818    byte >> used_bits == 0
819}
820
821/// Checks whether the final signed LEB128 payload byte fits the target width.
822///
823/// # Parameters
824///
825/// - `byte`: Final LEB128 byte to validate.
826/// - `bits`: Bit width of the target signed integer type.
827/// - `offset`: Zero-based byte offset of `byte` within the encoded value.
828///
829/// # Returns
830///
831/// Returns `true` if the unused payload bits are a valid sign extension.
832#[must_use]
833#[inline]
834fn signed_final_payload_fits(byte: u8, bits: u32, offset: usize) -> bool {
835    let used_bits = bits - offset as u32 * 7;
836    let payload = byte & 0x7F;
837    let used_mask = ((1u16 << used_bits) - 1) as u8;
838    let unused_mask = 0x7F & !used_mask;
839    let sign_bit = 1u8 << (used_bits - 1);
840    if payload & sign_bit == 0 {
841        payload & unused_mask == 0
842    } else {
843        payload & unused_mask == unused_mask
844    }
845}
846
847/// Checks whether an unsigned LEB128 terminal byte is canonical.
848///
849/// # Parameters
850///
851/// - `offset`: Zero-based byte offset of the terminal byte.
852/// - `byte`: Terminal byte without a continuation flag.
853///
854/// # Returns
855///
856/// Returns `true` when the terminal byte is necessary to encode the value.
857#[must_use]
858#[inline]
859fn is_canonical_uleb_terminal(offset: usize, byte: u8) -> bool {
860    offset == 0 || byte & 0x7F != 0
861}
862
863/// Checks whether a signed LEB128 terminal byte is canonical.
864///
865/// # Parameters
866///
867/// - `offset`: Zero-based byte offset of the terminal byte.
868/// - `previous_byte`: The preceding continuation byte when `offset` is
869///   non-zero.
870/// - `byte`: Terminal byte without a continuation flag.
871///
872/// # Returns
873///
874/// Returns `true` when the terminal byte is necessary to preserve the signed
875/// value represented by the preceding byte.
876#[must_use]
877#[inline]
878fn is_canonical_sleb_terminal(offset: usize, previous_byte: u8, byte: u8) -> bool {
879    if offset == 0 {
880        return true;
881    }
882    let payload = byte & 0x7F;
883    !((payload == 0 && previous_byte & 0x40 == 0) || (payload == 0x7F && previous_byte & 0x40 != 0))
884}
885
886/// Encodes an unsigned integer as canonical LEB128 without bounds checks.
887///
888/// # Parameters
889///
890/// - `output`: Destination byte buffer.
891/// - `index`: Start index in `output`.
892/// - `value`: Unsigned value to encode.
893///
894/// # Returns
895///
896/// Returns the number of written bytes.
897///
898/// # Safety
899///
900/// The caller must guarantee that `output.as_mut_ptr().add(index)` is valid to
901/// write the full canonical LEB128 representation of `value`.
902unsafe fn write_uleb_unchecked(output: &mut [u8], index: usize, mut value: u128) -> usize {
903    let mut offset = 0;
904    loop {
905        let mut byte = (value & 0x7F) as u8;
906        value >>= 7;
907        if value != 0 {
908            byte |= 0x80;
909        }
910        // SAFETY: The caller guarantees enough writable bytes for the encoded
911        // value.
912        unsafe {
913            UncheckedSlice::write(output, index + offset, byte);
914        }
915        offset += 1;
916        if value == 0 {
917            return offset;
918        }
919    }
920}
921
922/// Computes the canonical unsigned LEB128 byte width for `value`.
923///
924/// # Parameters
925///
926/// - `value`: Unsigned integer value whose canonical encoded width is measured.
927#[must_use]
928#[inline]
929pub(in crate::codec) fn uleb_encoded_len(mut value: u128) -> usize {
930    let mut len = 0;
931    loop {
932        value >>= 7;
933        len += 1;
934        if value == 0 {
935            return len;
936        }
937    }
938}
939
940/// Encodes a signed integer as canonical LEB128 without bounds checks.
941///
942/// # Parameters
943///
944/// - `output`: Destination byte buffer.
945/// - `index`: Start index in `output`.
946/// - `value`: Signed value to encode.
947///
948/// # Returns
949///
950/// Returns the number of written bytes.
951///
952/// # Safety
953///
954/// The caller must guarantee that `output.as_mut_ptr().add(index)` is valid to
955/// write the full canonical LEB128 representation of `value`.
956unsafe fn write_sleb_unchecked(output: &mut [u8], index: usize, mut value: i128) -> usize {
957    let mut offset = 0;
958    loop {
959        let mut byte = (value & 0x7F) as u8;
960        let sign_bit_set = byte & 0x40 != 0;
961        value >>= 7;
962        let done = (value == 0 && !sign_bit_set) || (value == -1 && sign_bit_set);
963        if !done {
964            byte |= 0x80;
965        }
966        // SAFETY: The caller guarantees enough writable bytes for the encoded
967        // value.
968        unsafe {
969            UncheckedSlice::write(output, index + offset, byte);
970        }
971        offset += 1;
972        if done {
973            return offset;
974        }
975    }
976}
977
978/// Computes the canonical signed LEB128 byte width for `value`.
979///
980/// # Parameters
981///
982/// - `value`: Signed integer value whose canonical encoded width is measured.
983#[must_use]
984#[inline]
985fn sleb_encoded_len(mut value: i128) -> usize {
986    let mut len = 0;
987    loop {
988        let byte = (value & 0x7F) as u8;
989        let sign_bit_set = byte & 0x40 != 0;
990        value >>= 7;
991        let done = (value == 0 && !sign_bit_set) || (value == -1 && sign_bit_set);
992        len += 1;
993        if done {
994            return len;
995        }
996    }
997}