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§
Sourcefn read_utf8_payload_into_async<'a>(
&'a mut self,
bytes: &'a mut Vec<u8>,
len: usize,
max_len: usize,
) -> impl Future<Output = Result<()>> + 'awhere
Self: Unpin,
fn read_utf8_payload_into_async<'a>(
&'a mut self,
bytes: &'a mut Vec<u8>,
len: usize,
max_len: usize,
) -> impl Future<Output = Result<()>> + 'awhere
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.
Sourcefn read_utf8_payload_async(
&mut self,
len: usize,
max_len: usize,
) -> impl Future<Output = Result<String>> + '_where
Self: Unpin,
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.
Sourcefn 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_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.
Sourcefn 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_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.
Sourcefn 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_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.
Sourcefn read_utf8_string_uleb_u64_strict_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,
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.
Sourcefn 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_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.
Sourcefn 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_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.
Sourcefn read_string_with_u16_len_le_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,
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.
Sourcefn 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_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.
Sourcefn 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_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.
Sourcefn read_string_with_u32_len_le_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,
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".