qubit-io-binary 0.7.1

Synchronous and asynchronous binary stream I/O adapters for Rust
Documentation
// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Extension methods for decoding LEB128 values from byte streams.

use std::io::Result;

use qubit_codec_binary::Leb128Codec;
use qubit_codec_binary::NonStrict;
use qubit_codec_binary::Strict;
use qubit_io::Input;

use crate::util::read_leb128_payload;

macro_rules! read_leb128_value {
    ($reader:expr, $ty:ty, $policy:ty) => {
        read_leb128_payload::<
            { Leb128Codec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
            Leb128Codec<$ty, $policy>,
            _,
        >($reader)
    };
}

/// Extension methods for reading LEB128 integers from byte streams.
///
/// # Target-width integers
///
/// `usize` and `isize` methods use the current Rust target's pointer width.
/// Prefer fixed-width integer methods such as
/// [`Self::read_uleb_u64_non_strict`] or [`Self::read_sleb_i64_non_strict`] for
/// persistent files and cross-platform protocols. Non-strict methods use the
/// `_non_strict` suffix; canonical-only methods use the corresponding `_strict`
/// suffix.
pub trait Leb128ReadExt: Input<Item = u8> {
    /// Reads a non-strict unsigned LEB128 `u8`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u8_non_strict(&mut self) -> Result<u8> {
        read_leb128_value!(self, u8, NonStrict)
    }

    /// Reads a strict unsigned LEB128 `u8`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u8_strict(&mut self) -> Result<u8> {
        read_leb128_value!(self, u8, Strict)
    }

    /// Reads a non-strict unsigned LEB128 `u16`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u16_non_strict(&mut self) -> Result<u16> {
        read_leb128_value!(self, u16, NonStrict)
    }

    /// Reads a strict unsigned LEB128 `u16`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u16_strict(&mut self) -> Result<u16> {
        read_leb128_value!(self, u16, Strict)
    }

    /// Reads a non-strict unsigned LEB128 `u32`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u32_non_strict(&mut self) -> Result<u32> {
        read_leb128_value!(self, u32, NonStrict)
    }

    /// Reads a strict unsigned LEB128 `u32`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u32_strict(&mut self) -> Result<u32> {
        read_leb128_value!(self, u32, Strict)
    }

    /// Reads a non-strict unsigned LEB128 `u64`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u64_non_strict(&mut self) -> Result<u64> {
        read_leb128_value!(self, u64, NonStrict)
    }

    /// Reads a strict unsigned LEB128 `u64`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u64_strict(&mut self) -> Result<u64> {
        read_leb128_value!(self, u64, Strict)
    }

    /// Reads a non-strict unsigned LEB128 `u128`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u128_non_strict(&mut self) -> Result<u128> {
        read_leb128_value!(self, u128, NonStrict)
    }

    /// Reads a strict unsigned LEB128 `u128`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_u128_strict(&mut self) -> Result<u128> {
        read_leb128_value!(self, u128, Strict)
    }

    /// Reads a non-strict unsigned LEB128 `usize`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_usize_non_strict(&mut self) -> Result<usize> {
        read_leb128_value!(self, usize, NonStrict)
    }

    /// Reads a strict unsigned LEB128 `usize`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_uleb_usize_strict(&mut self) -> Result<usize> {
        read_leb128_value!(self, usize, Strict)
    }

    /// Reads a non-strict signed LEB128 `i8`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i8_non_strict(&mut self) -> Result<i8> {
        read_leb128_value!(self, i8, NonStrict)
    }

    /// Reads a strict signed LEB128 `i8`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i8_strict(&mut self) -> Result<i8> {
        read_leb128_value!(self, i8, Strict)
    }

    /// Reads a non-strict signed LEB128 `i16`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i16_non_strict(&mut self) -> Result<i16> {
        read_leb128_value!(self, i16, NonStrict)
    }

    /// Reads a strict signed LEB128 `i16`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i16_strict(&mut self) -> Result<i16> {
        read_leb128_value!(self, i16, Strict)
    }

    /// Reads a non-strict signed LEB128 `i32`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i32_non_strict(&mut self) -> Result<i32> {
        read_leb128_value!(self, i32, NonStrict)
    }

    /// Reads a strict signed LEB128 `i32`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i32_strict(&mut self) -> Result<i32> {
        read_leb128_value!(self, i32, Strict)
    }

    /// Reads a non-strict signed LEB128 `i64`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i64_non_strict(&mut self) -> Result<i64> {
        read_leb128_value!(self, i64, NonStrict)
    }

    /// Reads a strict signed LEB128 `i64`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i64_strict(&mut self) -> Result<i64> {
        read_leb128_value!(self, i64, Strict)
    }

    /// Reads a non-strict signed LEB128 `i128`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i128_non_strict(&mut self) -> Result<i128> {
        read_leb128_value!(self, i128, NonStrict)
    }

    /// Reads a strict signed LEB128 `i128`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_i128_strict(&mut self) -> Result<i128> {
        read_leb128_value!(self, i128, Strict)
    }

    /// Reads a non-strict signed LEB128 `isize`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_isize_non_strict(&mut self) -> Result<isize> {
        read_leb128_value!(self, isize, NonStrict)
    }

    /// Reads a strict signed LEB128 `isize`.
    ///
    /// # Returns
    ///
    /// Returns the decoded integer.
    ///
    /// # Errors
    ///
    /// Returns an input error or an invalid-data error when the payload is
    /// malformed or violates the selected canonicality policy.
    #[inline(always)]
    fn read_sleb_isize_strict(&mut self) -> Result<isize> {
        read_leb128_value!(self, isize, Strict)
    }
}

impl<R> Leb128ReadExt for R where R: Input<Item = u8> + ?Sized {}