qubit-io-binary 0.8.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 reading length-prefixed UTF-8 strings.

use std::io::Result;

use qubit_codec::ByteOrder;
use qubit_io::ByteInput;

use crate::BinaryReadExt;
use crate::Leb128ReadExt;
use crate::util::read_utf8_payload as read_utf8_payload_impl;
use crate::util::read_utf8_payload_into as read_utf8_payload_into_impl;
#[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
use crate::util::usize_from_u32_len;
#[cfg(not(target_pointer_width = "64"))]
use crate::util::usize_from_u64_len;

/// Extension methods for reading length-prefixed UTF-8 strings.
///
/// String-producing methods may return allocation failures as I/O errors in
/// addition to input and validation errors described below.
///
/// A length-prefixed read is not transactional. If the decoded length exceeds
/// max_len, the prefix is consumed but the payload is left unread. If UTF-8
/// validation fails, both the prefix and the complete payload are consumed.
/// Do not continue parsing the same record from the current position.
///
/// # Examples
///
/// Read a length-prefixed string and observe that an oversized length consumes
/// its prefix while leaving the payload unread:
///
/// ```
/// use std::io::Cursor;
/// use std::io::ErrorKind;
/// use qubit_io_binary::StringReadExt;
///
/// let mut input = Cursor::new([3, b'a', b'b', b'c']);
/// assert_eq!(input.read_utf8_string_uleb_u64_strict(3)?, "abc");
/// let mut oversized = Cursor::new([3, b'a', b'b', b'c']);
/// assert_eq!(oversized.read_utf8_string_uleb_u64_strict(2).unwrap_err().kind(), ErrorKind::InvalidData);
/// assert_eq!(oversized.position(), 1);
/// # Ok::<(), std::io::Error>(())
/// ```
pub trait StringReadExt: ByteInput {
    /// Reads and validates a UTF-8 payload into reusable byte storage.
    ///
    /// # Parameters
    ///
    /// - `bytes`: Reusable destination buffer. It is cleared before a permitted
    ///   read and contains the received bytes when the read succeeds or when
    ///   UTF-8 validation fails.
    /// - `len`: UTF-8 payload length in bytes.
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// If `len` exceeds `max_len`, `bytes` is left unchanged. Once the length
    /// is accepted, its previous contents may be cleared even if allocation or
    /// reading fails. After an I/O error, `bytes` is not a complete payload:
    /// its length does not report how many bytes were received, and it may
    /// contain zero-filled bytes that were never read. Invalid UTF-8 is
    /// reported only after the complete payload has been received, so all
    /// payload bytes remain available in `bytes` for diagnostics.
    ///
    /// # Returns
    ///
    /// Returns after `bytes` contains one valid UTF-8 payload.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for payload reads or allocation failures, or
    /// [`std::io::ErrorKind::InvalidData`] when `len` exceeds `max_len` or
    /// the payload is not valid UTF-8.
    fn read_utf8_payload_into(&mut self, bytes: &mut Vec<u8>, len: usize, max_len: usize) -> Result<()>;

    /// Reads a UTF-8 payload with an already decoded byte length.
    ///
    /// # Parameters
    ///
    /// - `len`: UTF-8 payload length in bytes.
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when `len` exceeds `max_len`, or
    /// [`std::io::ErrorKind::InvalidData`] when the payload is not valid
    /// UTF-8.
    fn read_utf8_payload(&mut self, len: usize, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with an unsigned LEB128 byte-length prefix.
    ///
    /// The length prefix is decoded as `usize`, so this format is target-width
    /// dependent. Prefer `u16` or `u32` length-prefix methods for persistent
    /// files and cross-platform protocols.
    ///
    /// # Parameters
    ///
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
    /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
    /// is not valid UTF-8.
    fn read_utf8_string_uleb_usize(&mut self, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with a canonical unsigned LEB128 byte-length
    /// prefix.
    ///
    /// The length prefix is decoded as `usize`, so this format is target-width
    /// dependent. Prefer `u16` or `u32` length-prefix methods for persistent
    /// files and cross-platform protocols.
    ///
    /// # Parameters
    ///
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the length prefix is
    /// malformed or non-canonical, [`std::io::ErrorKind::InvalidData`] when
    /// the encoded length exceeds `max_len`, or
    /// [`std::io::ErrorKind::InvalidData`] when the payload is not valid
    /// UTF-8.
    fn read_utf8_string_uleb_usize_strict(&mut self, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with an unsigned LEB128 `u64` byte-length prefix.
    ///
    /// Prefer this method over [`Self::read_utf8_string_uleb_usize`] for
    /// persistent files and cross-platform protocols because the length
    /// field is independent of the current Rust target's pointer width.
    ///
    /// # Parameters
    ///
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the encoded `u64` length
    /// does not fit the local `usize`, when the encoded length exceeds
    /// `max_len`, or when the payload is not valid UTF-8.
    fn read_utf8_string_uleb_u64(&mut self, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with a canonical unsigned LEB128 `u64` byte-length
    /// prefix.
    ///
    /// Prefer this method over [`Self::read_utf8_string_uleb_usize_strict`] for
    /// persistent files and cross-platform protocols because the length field
    /// is independent of the current Rust target's pointer width.
    ///
    /// # Parameters
    ///
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the length prefix is
    /// malformed or non-canonical, when the encoded `u64` length does not
    /// fit the local `usize`, when the encoded length exceeds `max_len`, or
    /// when the payload is not valid UTF-8.
    fn read_utf8_string_uleb_u64_strict(&mut self, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with a runtime-order `u16` byte-length prefix.
    ///
    /// # Parameters
    ///
    /// - `byte_order`: Byte order used by the length prefix.
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
    /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
    /// is not valid UTF-8.
    fn read_string_with_u16_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with a big-endian `u16` byte-length prefix.
    ///
    /// # Parameters
    ///
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
    /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
    /// is not valid UTF-8.
    fn read_string_with_u16_len_be(&mut self, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with a little-endian `u16` byte-length prefix.
    ///
    /// # Parameters
    ///
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
    /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
    /// is not valid UTF-8.
    fn read_string_with_u16_len_le(&mut self, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with a runtime-order `u32` byte-length prefix.
    ///
    /// # Parameters
    ///
    /// - `byte_order`: Byte order used by the length prefix.
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
    /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
    /// is not valid UTF-8.
    fn read_string_with_u32_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with a big-endian `u32` byte-length prefix.
    ///
    /// # Parameters
    ///
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
    /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
    /// is not valid UTF-8.
    fn read_string_with_u32_len_be(&mut self, max_len: usize) -> Result<String>;

    /// Reads a UTF-8 string with a little-endian `u32` byte-length prefix.
    ///
    /// # Parameters
    ///
    /// - `max_len`: Maximum accepted UTF-8 payload length in bytes.
    ///
    /// # Returns
    ///
    /// The decoded string.
    ///
    /// # Errors
    ///
    /// Returns an I/O error for length or payload reads,
    /// [`std::io::ErrorKind::InvalidData`] when the encoded length exceeds
    /// `max_len`, or [`std::io::ErrorKind::InvalidData`] when the payload
    /// is not valid UTF-8.
    fn read_string_with_u32_len_le(&mut self, max_len: usize) -> Result<String>;
}

impl<T> StringReadExt for T
where
    T: ByteInput + ?Sized,
{
    #[inline]
    fn read_utf8_payload_into(&mut self, bytes: &mut Vec<u8>, len: usize, max_len: usize) -> Result<()> {
        read_utf8_payload_into_impl(self, bytes, len, max_len)
    }

    #[inline]
    fn read_utf8_payload(&mut self, len: usize, max_len: usize) -> Result<String> {
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_utf8_string_uleb_usize(&mut self, max_len: usize) -> Result<String> {
        let len = self.read_uleb_usize_non_strict()?;
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_utf8_string_uleb_usize_strict(&mut self, max_len: usize) -> Result<String> {
        let len = self.read_uleb_usize_strict()?;
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_utf8_string_uleb_u64(&mut self, max_len: usize) -> Result<String> {
        let len = self.read_uleb_u64_non_strict()?;
        #[cfg(target_pointer_width = "64")]
        let len = len as usize;
        #[cfg(not(target_pointer_width = "64"))]
        let len = usize_from_u64_len(len)?;
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_utf8_string_uleb_u64_strict(&mut self, max_len: usize) -> Result<String> {
        let len = self.read_uleb_u64_strict()?;
        #[cfg(target_pointer_width = "64")]
        let len = len as usize;
        #[cfg(not(target_pointer_width = "64"))]
        let len = usize_from_u64_len(len)?;
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_string_with_u16_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String> {
        let len = usize::from(self.read_u16(byte_order)?);
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_string_with_u16_len_be(&mut self, max_len: usize) -> Result<String> {
        let len = self.read_u16_be()? as usize;
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_string_with_u16_len_le(&mut self, max_len: usize) -> Result<String> {
        let len = self.read_u16_le()? as usize;
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_string_with_u32_len(&mut self, byte_order: ByteOrder, max_len: usize) -> Result<String> {
        let len = self.read_u32(byte_order)?;
        #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
        let len = len as usize;
        #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
        let len = usize_from_u32_len(len)?;
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_string_with_u32_len_be(&mut self, max_len: usize) -> Result<String> {
        let len = self.read_u32_be()?;
        #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
        let len = len as usize;
        #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
        let len = usize_from_u32_len(len)?;
        read_utf8_payload_impl(self, len, max_len)
    }

    #[inline]
    fn read_string_with_u32_len_le(&mut self, max_len: usize) -> Result<String> {
        let len = self.read_u32_le()?;
        #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
        let len = len as usize;
        #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
        let len = usize_from_u32_len(len)?;
        read_utf8_payload_impl(self, len, max_len)
    }
}