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            type Value = $ty;
182            type Unit = u8;
183            type DecodeError = Leb128DecodeError;
184            type EncodeError = Infallible;
185
186            const MIN_UNITS_PER_VALUE: usize = 1;
187            const MAX_ENCODE_UNITS_PER_VALUE: usize = (<$ty>::BITS as usize).div_ceil(7);
188            const MAX_DECODE_UNITS_PER_VALUE: usize = (<$ty>::BITS as usize).div_ceil(7);
189
190            #[inline]
191            fn encode_len(&self, value: &$ty) -> usize {
192                uleb_encoded_len(*value as u128)
193            }
194
195            #[inline]
196            unsafe fn decode(
197                &mut self,
198                input: &[u8],
199                input_index: usize,
200            ) -> Result<($ty, NonZeroUsize), DecodeFailure<Self::DecodeError>> {
201                debug_assert!(input.len().saturating_sub(input_index) >= Self::MIN_UNITS_PER_VALUE);
202
203                // SAFETY: The caller upholds the `Codec::decode`
204                // contract.
205                unsafe { Self::decode(input, input_index) }.map_err(map_leb128_decode_failure)
206            }
207
208            #[inline]
209            unsafe fn encode(
210                &mut self,
211                value: &$ty,
212                output: &mut [u8],
213                output_index: usize,
214            ) -> Result<usize, Self::EncodeError> {
215                let required = self.encode_len(value);
216                debug_assert!(output.len().saturating_sub(output_index) >= required);
217
218                // SAFETY: The `Codec::encode` contract provides either the
219                // exact canonical width or this type's maximum width.
220                let written = unsafe { Self::encode(*value, output, output_index) };
221                Ok(written)
222            }
223        }
224    };
225}
226
227macro_rules! impl_signed_leb128_codec {
228    ($ty:ty) => {
229        impl<P> Leb128Codec<$ty, P>
230        where
231            P: Leb128DecodePolicy,
232        {
233            /// Minimum number of bytes that can represent a complete value.
234            pub const MIN_UNITS_PER_VALUE: usize = <Self as Codec>::MIN_UNITS_PER_VALUE;
235
236            /// Maximum number of bytes emitted when encoding this type.
237            pub const MAX_ENCODE_UNITS_PER_VALUE: usize = <Self as Codec>::MAX_ENCODE_UNITS_PER_VALUE;
238
239            /// Maximum number of bytes consumed when decoding this type.
240            pub const MAX_DECODE_UNITS_PER_VALUE: usize = <Self as Codec>::MAX_DECODE_UNITS_PER_VALUE;
241
242            /// Decodes a value from `input` starting at `input_index` without bounds
243            /// checks.
244            ///
245            /// # Parameters
246            ///
247            /// - `input`: Source byte buffer.
248            /// - `input_index`: Start index in `input`.
249            ///
250            /// # Returns
251            ///
252            /// Returns the decoded value and the non-zero number of consumed
253            /// bytes.
254            ///
255            /// # Errors
256            ///
257            /// Returns [`Leb128DecodeError`] if the bytes are incomplete,
258            /// malformed, or strict decoding rejects a non-canonical
259            /// representation.
260            ///
261            /// # Safety
262            ///
263            /// The caller must guarantee that `input_index` is a valid boundary
264            /// and at least [`Self::MIN_UNITS_PER_VALUE`] byte is readable
265            /// from `input_index`.
266            #[inline]
267            pub unsafe fn decode(input: &[u8], input_index: usize) -> Result<($ty, NonZeroUsize), Leb128DecodeError> {
268                debug_assert!(input.len().saturating_sub(input_index) >= Self::MIN_UNITS_PER_VALUE);
269
270                // SAFETY: The caller guarantees enough readable bytes for this
271                // type.
272                let (value, consumed) = unsafe {
273                    read_sleb_unchecked::<P>(input, input_index, <$ty>::BITS, Self::MAX_DECODE_UNITS_PER_VALUE)?
274                };
275                Ok((value as $ty, consumed))
276            }
277
278            /// Encodes `value` into `output` starting at `output_index` without bounds
279            /// checks.
280            ///
281            /// # Parameters
282            ///
283            /// - `value`: Value to encode.
284            /// - `output`: Destination byte buffer.
285            /// - `output_index`: Start index in `output`.
286            ///
287            /// # Returns
288            ///
289            /// Returns the number of written bytes.
290            ///
291            /// # Safety
292            ///
293            /// The caller must guarantee that the canonical signed LEB128 byte
294            /// width of `value` is writable starting at `output_index`.
295            /// Reserving [`Self::MAX_ENCODE_UNITS_PER_VALUE`] bytes always satisfies
296            /// this requirement; for a known value, the exact
297            /// [`Codec::encode_len`] is sufficient.
298            #[must_use = "the returned byte count determines the encoded payload range"]
299            #[inline]
300            pub unsafe fn encode(value: $ty, output: &mut [u8], output_index: usize) -> usize {
301                // SAFETY: The caller guarantees enough writable bytes for the
302                // canonical representation of this value.
303                unsafe { write_sleb_unchecked(output, output_index, value as i128) }
304            }
305        }
306
307        impl<P> Codec for Leb128Codec<$ty, P>
308        where
309            P: Leb128DecodePolicy,
310        {
311            type Value = $ty;
312            type Unit = u8;
313            type DecodeError = Leb128DecodeError;
314            type EncodeError = Infallible;
315
316            const MIN_UNITS_PER_VALUE: usize = 1;
317            const MAX_ENCODE_UNITS_PER_VALUE: usize = (<$ty>::BITS as usize).div_ceil(7);
318            const MAX_DECODE_UNITS_PER_VALUE: usize = (<$ty>::BITS as usize).div_ceil(7);
319
320            #[inline]
321            fn encode_len(&self, value: &$ty) -> usize {
322                sleb_encoded_len(*value as i128)
323            }
324
325            #[inline]
326            unsafe fn decode(
327                &mut self,
328                input: &[u8],
329                input_index: usize,
330            ) -> Result<($ty, NonZeroUsize), DecodeFailure<Self::DecodeError>> {
331                debug_assert!(input.len().saturating_sub(input_index) >= Self::MIN_UNITS_PER_VALUE);
332
333                // SAFETY: The caller upholds the `Codec::decode`
334                // contract.
335                unsafe { Self::decode(input, input_index) }.map_err(map_leb128_decode_failure)
336            }
337
338            #[inline]
339            unsafe fn encode(
340                &mut self,
341                value: &$ty,
342                output: &mut [u8],
343                output_index: usize,
344            ) -> Result<usize, Self::EncodeError> {
345                let required = self.encode_len(value);
346                debug_assert!(output.len().saturating_sub(output_index) >= required);
347
348                // SAFETY: The `Codec::encode` contract provides either the
349                // exact canonical width or this type's maximum width.
350                let written = unsafe { Self::encode(*value, output, output_index) };
351                Ok(written)
352            }
353        }
354    };
355}
356
357impl_unsigned_leb128_codec!(u8);
358impl_unsigned_leb128_codec!(u16);
359impl_unsigned_leb128_codec!(u32);
360impl_unsigned_leb128_codec!(u64);
361impl_unsigned_leb128_codec!(u128);
362impl_unsigned_leb128_codec!(usize);
363
364impl_signed_leb128_codec!(i8);
365impl_signed_leb128_codec!(i16);
366impl_signed_leb128_codec!(i32);
367impl_signed_leb128_codec!(i64);
368impl_signed_leb128_codec!(i128);
369impl_signed_leb128_codec!(isize);
370
371/// Decodes an unsigned LEB128 value without bounds checks.
372///
373/// # Type Parameters
374///
375/// - `P`: Type-level decoding policy used to decide whether non-canonical
376///   encodings are accepted.
377///
378/// # Parameters
379///
380/// - `input`: Source byte buffer.
381/// - `index`: Start index in `input`.
382/// - `bits`: Bit width of the target integer type.
383/// - `max_bytes`: Maximum number of bytes allowed for that target width.
384///
385/// # Returns
386///
387/// Returns the decoded value and the non-zero number of consumed bytes.
388///
389/// # Errors
390///
391/// Returns [`Leb128DecodeError`] when the byte sequence is incomplete,
392/// malformed, or when `P` rejects a non-canonical encoding.
393///
394/// # Safety
395///
396/// The caller must guarantee that at least one byte is readable from `index`.
397#[inline]
398unsafe fn read_uleb_unchecked<P>(
399    input: &[u8],
400    index: usize,
401    bits: u32,
402    max_bytes: usize,
403) -> Result<(u128, NonZeroUsize), Leb128DecodeError>
404where
405    P: Leb128DecodePolicy,
406{
407    debug_assert!(input.len().saturating_sub(index) >= 1);
408
409    let available = input.len().saturating_sub(index).min(max_bytes);
410    // SAFETY: The caller guarantees that the currently available bytes are
411    // readable from `index`.
412    match unsafe { read_uleb_prefix_unchecked::<P>(input, index, bits, max_bytes, available) } {
413        Ok(Some((value, consumed))) => {
414            debug_assert!(consumed > 0);
415            // SAFETY: Prefix readers only return `Some` after consuming at
416            // least one terminating byte.
417            let consumed = nonzero(consumed);
418            Ok((value, consumed))
419        }
420        Ok(None) => {
421            debug_assert!(available < usize::MAX, "available byte count overflowed");
422            // SAFETY: Adding one to the available byte count produces a
423            // non-zero retry lower bound.
424            let required = nonzero(available + 1);
425            Err(Leb128DecodeError::incomplete(index, required, available))
426        }
427        Err(error) => Err(error),
428    }
429}
430
431/// Tries to decode an unsigned LEB128 value from currently available bytes.
432///
433/// # Type Parameters
434///
435/// - `P`: Type-level decoding policy used to decide whether non-canonical
436///   encodings are accepted.
437///
438/// # Parameters
439///
440/// - `input`: Source byte buffer.
441/// - `index`: Start index in `input`.
442/// - `bits`: Bit width of the target integer type.
443/// - `max_bytes`: Maximum number of bytes allowed for that target width.
444/// - `available`: Number of bytes currently readable from `index`.
445///
446/// # Returns
447///
448/// Returns `Ok(Some((value, consumed)))` when a complete value is decoded,
449/// `Ok(None)` when more bytes are needed, or `Err(error)` when the payload is
450/// invalid. Invalid errors carry the consumable byte count.
451///
452/// # Safety
453///
454/// The caller must guarantee that `input.as_ptr().add(index)` is valid to read
455/// `available` bytes and that `available <= max_bytes`.
456#[inline]
457unsafe fn read_uleb_prefix_unchecked<P>(
458    input: &[u8],
459    index: usize,
460    bits: u32,
461    max_bytes: usize,
462    available: usize,
463) -> Result<Option<(u128, usize)>, Leb128DecodeError>
464where
465    P: Leb128DecodePolicy,
466{
467    debug_assert!(available <= max_bytes, "available bytes exceed LEB128 maximum width");
468    let mut value = 0u128;
469    let mut shift = 0u32;
470    for offset in 0..available {
471        // SAFETY: The caller guarantees enough readable bytes for this loop.
472        let byte = unsafe { UncheckedSlice::read(input, index + offset) };
473        let payload = u128::from(byte & 0x7F);
474        value |= payload << shift;
475        if byte & 0x80 == 0 {
476            if offset == max_bytes - 1 && !unsigned_final_payload_fits(byte, bits, offset) {
477                return Err(malformed_decode_error(index, index + offset, offset + 1));
478            }
479            let consumed = offset + 1;
480            if P::STRICT && !is_canonical_uleb_terminal(offset, byte) {
481                return Err(noncanonical_decode_error(index, consumed));
482            }
483            return Ok(Some((value, consumed)));
484        }
485        shift += 7;
486    }
487    if available < max_bytes {
488        return Ok(None);
489    }
490    Err(malformed_decode_error(index, index + max_bytes - 1, max_bytes))
491}
492
493/// Decodes a signed LEB128 value without bounds checks.
494///
495/// # Type Parameters
496///
497/// - `P`: Type-level decoding policy used to decide whether non-canonical
498///   encodings are accepted.
499///
500/// # Parameters
501///
502/// - `input`: Source byte buffer.
503/// - `index`: Start index in `input`.
504/// - `bits`: Bit width of the target integer type.
505/// - `max_bytes`: Maximum number of bytes allowed for that target width.
506///
507/// # Returns
508///
509/// Returns the decoded value and the non-zero number of consumed bytes.
510///
511/// # Errors
512///
513/// Returns [`Leb128DecodeError`] when the byte sequence is incomplete,
514/// malformed, or when `P` rejects a non-canonical encoding.
515///
516/// # Safety
517///
518/// The caller must guarantee that at least one byte is readable from `index`.
519#[inline]
520unsafe fn read_sleb_unchecked<P>(
521    input: &[u8],
522    index: usize,
523    bits: u32,
524    max_bytes: usize,
525) -> Result<(i128, NonZeroUsize), Leb128DecodeError>
526where
527    P: Leb128DecodePolicy,
528{
529    debug_assert!(input.len().saturating_sub(index) >= 1);
530
531    let available = input.len().saturating_sub(index).min(max_bytes);
532    // SAFETY: The caller guarantees that the currently available bytes are
533    // readable from `index`.
534    match unsafe { read_sleb_prefix_unchecked::<P>(input, index, bits, max_bytes, available) } {
535        Ok(Some((value, consumed))) => {
536            debug_assert!(consumed > 0);
537            // SAFETY: Prefix readers only return `Some` after consuming at
538            // least one terminating byte.
539            let consumed = nonzero(consumed);
540            Ok((value, consumed))
541        }
542        Ok(None) => {
543            debug_assert!(available < usize::MAX, "available byte count overflowed");
544            // SAFETY: Adding one to the available byte count produces a
545            // non-zero retry lower bound.
546            let required = nonzero(available + 1);
547            Err(Leb128DecodeError::incomplete(index, required, available))
548        }
549        Err(error) => Err(error),
550    }
551}
552
553/// Tries to decode a signed LEB128 value from currently available bytes.
554///
555/// # Type Parameters
556///
557/// - `P`: Type-level decoding policy used to decide whether non-canonical
558///   encodings are accepted.
559///
560/// # Parameters
561///
562/// - `input`: Source byte buffer.
563/// - `index`: Start index in `input`.
564/// - `bits`: Bit width of the target integer type.
565/// - `max_bytes`: Maximum number of bytes allowed for that target width.
566/// - `available`: Number of bytes currently readable from `index`.
567///
568/// # Returns
569///
570/// Returns `Ok(Some((value, consumed)))` when a complete value is decoded,
571/// `Ok(None)` when more bytes are needed, or `Err(error)` when the payload is
572/// invalid. Invalid errors carry the consumable byte count.
573///
574/// # Safety
575///
576/// The caller must guarantee that `input.as_ptr().add(index)` is valid to read
577/// `available` bytes and that `available <= max_bytes`.
578#[inline]
579unsafe fn read_sleb_prefix_unchecked<P>(
580    input: &[u8],
581    index: usize,
582    bits: u32,
583    max_bytes: usize,
584    available: usize,
585) -> Result<Option<(i128, usize)>, Leb128DecodeError>
586where
587    P: Leb128DecodePolicy,
588{
589    debug_assert!(available <= max_bytes, "available bytes exceed LEB128 maximum width");
590    let mut value = 0i128;
591    let mut shift = 0u32;
592    let mut previous_byte = 0u8;
593    for offset in 0..available {
594        // SAFETY: The caller guarantees enough readable bytes for this loop.
595        let byte = unsafe { UncheckedSlice::read(input, index + offset) };
596        let payload = i128::from(byte & 0x7F);
597        value |= payload << shift;
598        if byte & 0x80 == 0 {
599            if offset == max_bytes - 1 && !signed_final_payload_fits(byte, bits, offset) {
600                return Err(malformed_decode_error(index, index + offset, offset + 1));
601            }
602            if byte & 0x40 != 0 && shift + 7 < i128::BITS {
603                value |= (!0i128) << (shift + 7);
604            }
605            let consumed = offset + 1;
606            if P::STRICT && !is_canonical_sleb_terminal(offset, previous_byte, byte) {
607                return Err(noncanonical_decode_error(index, consumed));
608            }
609            return Ok(Some((value, consumed)));
610        }
611        previous_byte = byte;
612        shift += 7;
613    }
614    if available < max_bytes {
615        return Ok(None);
616    }
617    Err(malformed_decode_error(index, index + max_bytes - 1, max_bytes))
618}
619
620/// Builds a malformed LEB128 error on the cold error path.
621///
622/// # Parameters
623///
624/// - `start_index`: Absolute byte index where the malformed payload starts.
625/// - `error_index`: Absolute byte index associated with the malformed payload.
626/// - `consumed`: Number of bytes that should be consumed before reporting the
627///   error.
628///
629/// # Returns
630///
631/// Returns the error carrying the byte count to consume.
632#[cold]
633fn malformed_decode_error(start_index: usize, error_index: usize, consumed: usize) -> Leb128DecodeError {
634    debug_assert!(consumed > 0, "malformed LEB128 errors must consume bytes");
635    // SAFETY: All malformed call sites pass either `offset + 1` or `max_bytes`,
636    // both of which are non-zero for supported LEB128 codecs.
637    let consumed = nonzero(consumed);
638    Leb128DecodeError::malformed(start_index, error_index, consumed)
639}
640
641/// Builds a non-canonical LEB128 error on the cold error path.
642///
643/// # Parameters
644///
645/// - `index`: Absolute byte index at which the non-canonical payload starts.
646/// - `consumed`: Number of bytes that should be consumed before reporting the
647///   error.
648///
649/// # Returns
650///
651/// Returns the error carrying the byte count to consume.
652#[cold]
653fn noncanonical_decode_error(index: usize, consumed: usize) -> Leb128DecodeError {
654    debug_assert!(consumed > 0, "non-canonical LEB128 errors must consume bytes");
655    // SAFETY: Non-canonical errors are detected only after reading at least one
656    // terminating byte.
657    let consumed = nonzero(consumed);
658    Leb128DecodeError::noncanonical(index, consumed)
659}
660
661/// Checks whether the final unsigned LEB128 payload byte fits the target width.
662///
663/// # Parameters
664///
665/// - `byte`: Final LEB128 byte to validate.
666/// - `bits`: Bit width of the target unsigned integer type.
667/// - `offset`: Zero-based byte offset of `byte` within the encoded value.
668///
669/// # Returns
670///
671/// Returns `true` if the unused payload bits are all zero.
672#[must_use]
673#[inline]
674fn unsigned_final_payload_fits(byte: u8, bits: u32, offset: usize) -> bool {
675    let used_bits = bits - offset as u32 * 7;
676    byte >> used_bits == 0
677}
678
679/// Checks whether the final signed LEB128 payload byte fits the target width.
680///
681/// # Parameters
682///
683/// - `byte`: Final LEB128 byte to validate.
684/// - `bits`: Bit width of the target signed integer type.
685/// - `offset`: Zero-based byte offset of `byte` within the encoded value.
686///
687/// # Returns
688///
689/// Returns `true` if the unused payload bits are a valid sign extension.
690#[must_use]
691#[inline]
692fn signed_final_payload_fits(byte: u8, bits: u32, offset: usize) -> bool {
693    let used_bits = bits - offset as u32 * 7;
694    let payload = byte & 0x7F;
695    let used_mask = ((1u16 << used_bits) - 1) as u8;
696    let unused_mask = 0x7F & !used_mask;
697    let sign_bit = 1u8 << (used_bits - 1);
698    if payload & sign_bit == 0 {
699        payload & unused_mask == 0
700    } else {
701        payload & unused_mask == unused_mask
702    }
703}
704
705/// Checks whether an unsigned LEB128 terminal byte is canonical.
706///
707/// # Parameters
708///
709/// - `offset`: Zero-based byte offset of the terminal byte.
710/// - `byte`: Terminal byte without a continuation flag.
711///
712/// # Returns
713///
714/// Returns `true` when the terminal byte is necessary to encode the value.
715#[must_use]
716#[inline]
717fn is_canonical_uleb_terminal(offset: usize, byte: u8) -> bool {
718    offset == 0 || byte & 0x7F != 0
719}
720
721/// Checks whether a signed LEB128 terminal byte is canonical.
722///
723/// # Parameters
724///
725/// - `offset`: Zero-based byte offset of the terminal byte.
726/// - `previous_byte`: The preceding continuation byte when `offset` is
727///   non-zero.
728/// - `byte`: Terminal byte without a continuation flag.
729///
730/// # Returns
731///
732/// Returns `true` when the terminal byte is necessary to preserve the signed
733/// value represented by the preceding byte.
734#[must_use]
735#[inline]
736fn is_canonical_sleb_terminal(offset: usize, previous_byte: u8, byte: u8) -> bool {
737    if offset == 0 {
738        return true;
739    }
740    let payload = byte & 0x7F;
741    !((payload == 0 && previous_byte & 0x40 == 0) || (payload == 0x7F && previous_byte & 0x40 != 0))
742}
743
744/// Encodes an unsigned integer as canonical LEB128 without bounds checks.
745///
746/// # Parameters
747///
748/// - `output`: Destination byte buffer.
749/// - `index`: Start index in `output`.
750/// - `value`: Unsigned value to encode.
751///
752/// # Returns
753///
754/// Returns the number of written bytes.
755///
756/// # Safety
757///
758/// The caller must guarantee that `output.as_mut_ptr().add(index)` is valid to
759/// write the full canonical LEB128 representation of `value`.
760unsafe fn write_uleb_unchecked(output: &mut [u8], index: usize, mut value: u128) -> usize {
761    let mut offset = 0;
762    loop {
763        let mut byte = (value & 0x7F) as u8;
764        value >>= 7;
765        if value != 0 {
766            byte |= 0x80;
767        }
768        // SAFETY: The caller guarantees enough writable bytes for the encoded
769        // value.
770        unsafe {
771            UncheckedSlice::write(output, index + offset, byte);
772        }
773        offset += 1;
774        if value == 0 {
775            return offset;
776        }
777    }
778}
779
780/// Computes the canonical unsigned LEB128 byte width for `value`.
781///
782/// # Parameters
783///
784/// - `value`: Unsigned integer value whose canonical encoded width is measured.
785#[must_use]
786#[inline]
787pub(in crate::codec) fn uleb_encoded_len(mut value: u128) -> usize {
788    let mut len = 0;
789    loop {
790        value >>= 7;
791        len += 1;
792        if value == 0 {
793            return len;
794        }
795    }
796}
797
798/// Encodes a signed integer as canonical LEB128 without bounds checks.
799///
800/// # Parameters
801///
802/// - `output`: Destination byte buffer.
803/// - `index`: Start index in `output`.
804/// - `value`: Signed value to encode.
805///
806/// # Returns
807///
808/// Returns the number of written bytes.
809///
810/// # Safety
811///
812/// The caller must guarantee that `output.as_mut_ptr().add(index)` is valid to
813/// write the full canonical LEB128 representation of `value`.
814unsafe fn write_sleb_unchecked(output: &mut [u8], index: usize, mut value: i128) -> usize {
815    let mut offset = 0;
816    loop {
817        let mut byte = (value & 0x7F) as u8;
818        let sign_bit_set = byte & 0x40 != 0;
819        value >>= 7;
820        let done = (value == 0 && !sign_bit_set) || (value == -1 && sign_bit_set);
821        if !done {
822            byte |= 0x80;
823        }
824        // SAFETY: The caller guarantees enough writable bytes for the encoded
825        // value.
826        unsafe {
827            UncheckedSlice::write(output, index + offset, byte);
828        }
829        offset += 1;
830        if done {
831            return offset;
832        }
833    }
834}
835
836/// Computes the canonical signed LEB128 byte width for `value`.
837///
838/// # Parameters
839///
840/// - `value`: Signed integer value whose canonical encoded width is measured.
841#[must_use]
842#[inline]
843fn sleb_encoded_len(mut value: i128) -> usize {
844    let mut len = 0;
845    loop {
846        let byte = (value & 0x7F) as u8;
847        let sign_bit_set = byte & 0x40 != 0;
848        value >>= 7;
849        let done = (value == 0 && !sign_bit_set) || (value == -1 && sign_bit_set);
850        len += 1;
851        if done {
852            return len;
853        }
854    }
855}