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}