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