pub trait StringReadExt: ByteInput {
// Required methods
fn read_utf8_payload_into(
&mut self,
bytes: &mut Vec<u8>,
len: usize,
max_len: usize,
) -> Result<()>;
fn read_utf8_payload(
&mut self,
len: usize,
max_len: usize,
) -> Result<String>;
fn read_utf8_string_uleb_usize(&mut self, max_len: usize) -> Result<String>;
fn read_utf8_string_uleb_usize_strict(
&mut self,
max_len: usize,
) -> Result<String>;
fn read_utf8_string_uleb_u64(&mut self, max_len: usize) -> Result<String>;
fn read_utf8_string_uleb_u64_strict(
&mut self,
max_len: usize,
) -> Result<String>;
fn read_string_with_u16_len(
&mut self,
byte_order: ByteOrder,
max_len: usize,
) -> Result<String>;
fn read_string_with_u16_len_be(&mut self, max_len: usize) -> Result<String>;
fn read_string_with_u16_len_le(&mut self, max_len: usize) -> Result<String>;
fn read_string_with_u32_len(
&mut self,
byte_order: ByteOrder,
max_len: usize,
) -> Result<String>;
fn read_string_with_u32_len_be(&mut self, max_len: usize) -> Result<String>;
fn read_string_with_u32_len_le(&mut self, max_len: usize) -> Result<String>;
}Expand description
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);Required Methods§
Sourcefn read_utf8_payload_into(
&mut self,
bytes: &mut Vec<u8>,
len: usize,
max_len: usize,
) -> Result<()>
fn read_utf8_payload_into( &mut self, bytes: &mut Vec<u8>, len: usize, max_len: usize, ) -> Result<()>
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.
Sourcefn read_utf8_payload(&mut self, len: usize, max_len: usize) -> Result<String>
fn read_utf8_payload(&mut self, len: usize, max_len: usize) -> Result<String>
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.
Sourcefn read_utf8_string_uleb_usize(&mut self, max_len: usize) -> Result<String>
fn read_utf8_string_uleb_usize(&mut self, 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.
Sourcefn read_utf8_string_uleb_usize_strict(
&mut self,
max_len: usize,
) -> Result<String>
fn read_utf8_string_uleb_usize_strict( &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.
Sourcefn read_utf8_string_uleb_u64(&mut self, max_len: usize) -> Result<String>
fn read_utf8_string_uleb_u64(&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.
Sourcefn read_utf8_string_uleb_u64_strict(&mut self, max_len: usize) -> Result<String>
fn read_utf8_string_uleb_u64_strict(&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.
Sourcefn read_string_with_u16_len(
&mut self,
byte_order: ByteOrder,
max_len: usize,
) -> Result<String>
fn read_string_with_u16_len( &mut self, byte_order: ByteOrder, 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.
Sourcefn read_string_with_u16_len_be(&mut self, max_len: usize) -> Result<String>
fn read_string_with_u16_len_be(&mut self, 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.
Sourcefn read_string_with_u16_len_le(&mut self, max_len: usize) -> Result<String>
fn read_string_with_u16_len_le(&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.
Sourcefn read_string_with_u32_len(
&mut self,
byte_order: ByteOrder,
max_len: usize,
) -> Result<String>
fn read_string_with_u32_len( &mut self, byte_order: ByteOrder, 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.
Sourcefn read_string_with_u32_len_be(&mut self, max_len: usize) -> Result<String>
fn read_string_with_u32_len_be(&mut self, 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.
Sourcefn read_string_with_u32_len_le(&mut self, max_len: usize) -> Result<String>
fn read_string_with_u32_len_le(&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.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".