Skip to main content

AsyncStringReadExt

Trait AsyncStringReadExt 

Source
pub trait AsyncStringReadExt: AsyncInput<Item = u8> {
    // Provided methods
    fn read_utf8_payload_into_async<'a>(
        &'a mut self,
        bytes: &'a mut Vec<u8>,
        len: usize,
        max_len: usize,
    ) -> impl Future<Output = Result<()>> + 'a
       where Self: Unpin { ... }
    fn read_utf8_payload_async(
        &mut self,
        len: usize,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_utf8_string_uleb_usize_async(
        &mut self,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_utf8_string_uleb_usize_strict_async(
        &mut self,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_utf8_string_uleb_u64_async(
        &mut self,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_utf8_string_uleb_u64_strict_async(
        &mut self,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_string_with_u16_len_async(
        &mut self,
        byte_order: ByteOrder,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_string_with_u16_len_be_async(
        &mut self,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_string_with_u16_len_le_async(
        &mut self,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_string_with_u32_len_async(
        &mut self,
        byte_order: ByteOrder,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_string_with_u32_len_be_async(
        &mut self,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
    fn read_string_with_u32_len_le_async(
        &mut self,
        max_len: usize,
    ) -> impl Future<Output = Result<String>> + '_
       where Self: Unpin { ... }
}
Expand description

Future-based length-prefixed UTF-8 reads.

§Cancellation safety

These reads are not cancellation safe. Dropping a pending future leaves bytes already consumed from the prefix or payload consumed.

A length above max_len consumes its prefix but leaves the payload unread; invalid UTF-8 is reported after the complete payload has been consumed. Neither failure rolls back the input.

§Examples

Define a generic async helper that reads a bounded, length-prefixed label:

use qubit_io::AsyncInput;
use qubit_io_binary::AsyncStringReadExt;

async fn read_label<I>(input: &mut I) -> std::io::Result<String>
where
    I: AsyncInput<Item = u8> + Unpin,
{
    input.read_utf8_string_uleb_u64_strict_async(64).await
}

Provided Methods§

Source

fn read_utf8_payload_into_async<'a>( &'a mut self, bytes: &'a mut Vec<u8>, len: usize, max_len: usize, ) -> impl Future<Output = Result<()>> + 'a
where Self: Unpin,

Asynchronously 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: Encoded payload length in bytes.
  • max_len: Maximum accepted 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 or after a polled future is cancelled, 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 a future that completes after bytes contains one valid UTF-8 payload.

§Errors

Returns an input or allocation error, or an invalid-data error when len exceeds max_len or the payload is not valid UTF-8.

§Cancellation safety

This operation is not cancellation safe. Dropping a future before it is polled performs no read. Dropping it after polling does not roll back bytes consumed from the input or modifications made to bytes.

Source

fn read_utf8_payload_async( &mut self, len: usize, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads an already length-delimited UTF-8 payload.

§Parameters
  • len: Encoded payload length in bytes.
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input or allocation error, or an invalid-data error when len exceeds max_len or the payload is not valid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any bytes already consumed from the input.

Source

fn read_utf8_string_uleb_usize_async( &mut self, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a target-width LEB128-length UTF-8 string.

§Parameters
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input or allocation error, or an invalid-data error for a malformed length, an excessive length, or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Source

fn read_utf8_string_uleb_usize_strict_async( &mut self, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a canonical target-width LEB128-length string.

§Parameters
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input or allocation error, or an invalid-data error for a non-canonical length, an excessive length, or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Source

fn read_utf8_string_uleb_u64_async( &mut self, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a u64 LEB128-length UTF-8 string.

§Parameters
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input, conversion, or allocation error, or an invalid-data error for a malformed or excessive length or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Source

fn read_utf8_string_uleb_u64_strict_async( &mut self, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a canonical u64 LEB128-length UTF-8 string.

§Parameters
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input, conversion, or allocation error, or an invalid-data error for a non-canonical or excessive length or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Source

fn read_string_with_u16_len_async( &mut self, byte_order: ByteOrder, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a runtime-order u16-length UTF-8 string.

§Parameters
  • byte_order: Byte order used to decode the length.
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input or allocation error, or an invalid-data error for an excessive length or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Source

fn read_string_with_u16_len_be_async( &mut self, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a big-endian u16-length UTF-8 string.

§Parameters
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input or allocation error, or an invalid-data error for an excessive length or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Source

fn read_string_with_u16_len_le_async( &mut self, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a little-endian u16-length UTF-8 string.

§Parameters
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input or allocation error, or an invalid-data error for an excessive length or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Source

fn read_string_with_u32_len_async( &mut self, byte_order: ByteOrder, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a runtime-order u32-length UTF-8 string.

§Parameters
  • byte_order: Byte order used to decode the length.
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input, conversion, or allocation error, or an invalid-data error for an excessive length or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Source

fn read_string_with_u32_len_be_async( &mut self, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a big-endian u32-length UTF-8 string.

§Parameters
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input, conversion, or allocation error, or an invalid-data error for an excessive length or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Source

fn read_string_with_u32_len_le_async( &mut self, max_len: usize, ) -> impl Future<Output = Result<String>> + '_
where Self: Unpin,

Asynchronously reads a little-endian u32-length UTF-8 string.

§Parameters
  • max_len: Maximum accepted payload length in bytes.
§Returns

Returns the decoded string.

§Errors

Returns an input, conversion, or allocation error, or an invalid-data error for an excessive length or invalid UTF-8.

§Cancellation safety

This operation is not cancellation safe; dropping the future retains any prefix or payload bytes already consumed.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§

Source§

impl<R> AsyncStringReadExt for R
where R: AsyncInput<Item = u8> + ?Sized,