qubit-io-binary 0.8.6

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 ZigZag-encoded integers from streams.

use std::io::Result;

use qubit_codec_binary::NonStrict;
use qubit_codec_binary::Strict;
use qubit_codec_binary::ZigZagCodec;
use qubit_io::ByteInput;

use crate::util::read_leb128_payload;

/// Decodes one ZigZag value using the selected integer type and canonicality
/// policy.
macro_rules! read_zig_zag_value {
    ($reader:expr, $ty:ty, $policy:ty) => {
        read_leb128_payload::<
            { ZigZagCodec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
            ZigZagCodec<$ty, $policy>,
            _,
        >($reader)
    };
}

/// Extension methods for reading ZigZag + unsigned LEB128 integers.
///
/// # Target-width integers
///
/// `isize` methods use the current Rust target's pointer width. Prefer
/// fixed-width integer methods such as [`Self::read_zig_zag_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.
/// A failed synchronous read may have consumed part of the current value.
/// Do not blindly retry the same operation; resume only from a framing
/// boundary or a trusted seek checkpoint.
///
/// # Examples
///
/// Decode a strict ZigZag value from a byte slice:
///
/// ```
/// use std::io::Cursor;
/// use qubit_io_binary::ZigZagReadExt;
///
/// let mut input = Cursor::new([0x53]);
/// assert_eq!(input.read_zig_zag_i64_strict()?, -42);
/// # Ok::<(), std::io::Error>(())
/// ```
pub trait ZigZagReadExt: ByteInput {
    /// Reads a non-strict ZigZag `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_zig_zag_i8_non_strict(&mut self) -> Result<i8> {
        read_zig_zag_value!(self, i8, NonStrict)
    }

    /// Reads a strict ZigZag `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_zig_zag_i8_strict(&mut self) -> Result<i8> {
        read_zig_zag_value!(self, i8, Strict)
    }

    /// Reads a non-strict ZigZag `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_zig_zag_i16_non_strict(&mut self) -> Result<i16> {
        read_zig_zag_value!(self, i16, NonStrict)
    }

    /// Reads a strict ZigZag `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_zig_zag_i16_strict(&mut self) -> Result<i16> {
        read_zig_zag_value!(self, i16, Strict)
    }

    /// Reads a non-strict ZigZag `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_zig_zag_i32_non_strict(&mut self) -> Result<i32> {
        read_zig_zag_value!(self, i32, NonStrict)
    }

    /// Reads a strict ZigZag `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_zig_zag_i32_strict(&mut self) -> Result<i32> {
        read_zig_zag_value!(self, i32, Strict)
    }

    /// Reads a non-strict ZigZag `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_zig_zag_i64_non_strict(&mut self) -> Result<i64> {
        read_zig_zag_value!(self, i64, NonStrict)
    }

    /// Reads a strict ZigZag `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_zig_zag_i64_strict(&mut self) -> Result<i64> {
        read_zig_zag_value!(self, i64, Strict)
    }

    /// Reads a non-strict ZigZag `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_zig_zag_i128_non_strict(&mut self) -> Result<i128> {
        read_zig_zag_value!(self, i128, NonStrict)
    }

    /// Reads a strict ZigZag `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_zig_zag_i128_strict(&mut self) -> Result<i128> {
        read_zig_zag_value!(self, i128, Strict)
    }

    /// Reads a non-strict ZigZag `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_zig_zag_isize_non_strict(&mut self) -> Result<isize> {
        read_zig_zag_value!(self, isize, NonStrict)
    }

    /// Reads a strict ZigZag `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_zig_zag_isize_strict(&mut self) -> Result<isize> {
        read_zig_zag_value!(self, isize, Strict)
    }
}

impl<R> ZigZagReadExt for R where R: ByteInput + ?Sized {}