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