qubit_io_binary/ext/async_string_read_ext.rs
1// =============================================================================
2// Copyright (c) 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Asynchronous length-prefixed UTF-8 reads.
9
10use core::future::Future;
11use std::io::Result;
12
13use qubit_codec::ByteOrder;
14use qubit_io::AsyncInput;
15
16use crate::AsyncBinaryReadExt;
17use crate::AsyncLeb128ReadExt;
18use crate::util::read_utf8_payload_async;
19use crate::util::read_utf8_payload_into_async;
20#[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
21use crate::util::usize_from_u32_len;
22#[cfg(not(target_pointer_width = "64"))]
23use crate::util::usize_from_u64_len;
24
25/// Future-based length-prefixed UTF-8 reads.
26///
27/// # Cancellation safety
28///
29/// These reads are not cancellation safe. Dropping a pending future leaves
30/// bytes already consumed from the prefix or payload consumed.
31pub trait AsyncStringReadExt: AsyncInput<Item = u8> {
32 /// Asynchronously reads and validates a UTF-8 payload into reusable byte
33 /// storage.
34 ///
35 /// # Parameters
36 ///
37 /// - `bytes`: Reusable destination buffer. It is cleared before a permitted
38 /// read and contains the received bytes when the read succeeds or when
39 /// UTF-8 validation fails.
40 /// - `len`: Encoded payload length in bytes.
41 /// - `max_len`: Maximum accepted payload length in bytes.
42 ///
43 /// # Returns
44 ///
45 /// Returns a future that completes after `bytes` contains one valid UTF-8
46 /// payload.
47 ///
48 /// # Errors
49 ///
50 /// Returns an input or allocation error, or an invalid-data error when
51 /// `len` exceeds `max_len` or the payload is not valid UTF-8.
52 ///
53 /// # Cancellation safety
54 ///
55 /// This operation is not cancellation safe; dropping the future retains
56 /// bytes already consumed from the input and modifications already made
57 /// to `bytes`.
58 #[inline]
59 fn read_utf8_payload_into_async<'a>(
60 &'a mut self,
61 bytes: &'a mut Vec<u8>,
62 len: usize,
63 max_len: usize,
64 ) -> impl Future<Output = Result<()>> + 'a
65 where
66 Self: Unpin,
67 {
68 async move { read_utf8_payload_into_async(self, bytes, len, max_len).await }
69 }
70
71 /// Asynchronously reads an already length-delimited UTF-8 payload.
72 ///
73 /// # Parameters
74 ///
75 /// - `len`: Encoded payload length in bytes.
76 /// - `max_len`: Maximum accepted payload length in bytes.
77 ///
78 /// # Returns
79 ///
80 /// Returns the decoded string.
81 ///
82 /// # Errors
83 ///
84 /// Returns an input or allocation error, or an invalid-data error when
85 /// `len` exceeds `max_len` or the payload is not valid UTF-8.
86 ///
87 /// # Cancellation safety
88 ///
89 /// This operation is not cancellation safe; dropping the future retains
90 /// any bytes already consumed from the input.
91 #[inline]
92 fn read_utf8_payload_async(&mut self, len: usize, max_len: usize) -> impl Future<Output = Result<String>> + '_
93 where
94 Self: Unpin,
95 {
96 async move { read_utf8_payload_async(self, len, max_len).await }
97 }
98
99 /// Asynchronously reads a target-width LEB128-length UTF-8 string.
100 ///
101 /// # Parameters
102 ///
103 /// - `max_len`: Maximum accepted payload length in bytes.
104 ///
105 /// # Returns
106 ///
107 /// Returns the decoded string.
108 ///
109 /// # Errors
110 ///
111 /// Returns an input or allocation error, or an invalid-data error for a
112 /// malformed length, an excessive length, or invalid UTF-8.
113 ///
114 /// # Cancellation safety
115 ///
116 /// This operation is not cancellation safe; dropping the future retains
117 /// any prefix or payload bytes already consumed.
118 #[inline]
119 fn read_utf8_string_uleb_usize_async(&mut self, max_len: usize) -> impl Future<Output = Result<String>> + '_
120 where
121 Self: Unpin,
122 {
123 async move {
124 let len = self.read_uleb_usize_non_strict_async().await?;
125 read_utf8_payload_async(self, len, max_len).await
126 }
127 }
128
129 /// Asynchronously reads a canonical target-width LEB128-length string.
130 ///
131 /// # Parameters
132 ///
133 /// - `max_len`: Maximum accepted payload length in bytes.
134 ///
135 /// # Returns
136 ///
137 /// Returns the decoded string.
138 ///
139 /// # Errors
140 ///
141 /// Returns an input or allocation error, or an invalid-data error for a
142 /// non-canonical length, an excessive length, or invalid UTF-8.
143 ///
144 /// # Cancellation safety
145 ///
146 /// This operation is not cancellation safe; dropping the future retains
147 /// any prefix or payload bytes already consumed.
148 #[inline]
149 fn read_utf8_string_uleb_usize_strict_async(&mut self, max_len: usize) -> impl Future<Output = Result<String>> + '_
150 where
151 Self: Unpin,
152 {
153 async move {
154 let len = self.read_uleb_usize_strict_async().await?;
155 read_utf8_payload_async(self, len, max_len).await
156 }
157 }
158
159 /// Asynchronously reads a `u64` LEB128-length UTF-8 string.
160 ///
161 /// # Parameters
162 ///
163 /// - `max_len`: Maximum accepted payload length in bytes.
164 ///
165 /// # Returns
166 ///
167 /// Returns the decoded string.
168 ///
169 /// # Errors
170 ///
171 /// Returns an input, conversion, or allocation error, or an invalid-data
172 /// error for a malformed or excessive length or invalid UTF-8.
173 ///
174 /// # Cancellation safety
175 ///
176 /// This operation is not cancellation safe; dropping the future retains
177 /// any prefix or payload bytes already consumed.
178 #[inline]
179 fn read_utf8_string_uleb_u64_async(&mut self, max_len: usize) -> impl Future<Output = Result<String>> + '_
180 where
181 Self: Unpin,
182 {
183 async move {
184 let len = self.read_uleb_u64_non_strict_async().await?;
185 #[cfg(target_pointer_width = "64")]
186 let len = len as usize;
187 #[cfg(not(target_pointer_width = "64"))]
188 let len = usize_from_u64_len(len)?;
189 read_utf8_payload_async(self, len, max_len).await
190 }
191 }
192
193 /// Asynchronously reads a canonical `u64` LEB128-length UTF-8 string.
194 ///
195 /// # Parameters
196 ///
197 /// - `max_len`: Maximum accepted payload length in bytes.
198 ///
199 /// # Returns
200 ///
201 /// Returns the decoded string.
202 ///
203 /// # Errors
204 ///
205 /// Returns an input, conversion, or allocation error, or an invalid-data
206 /// error for a non-canonical or excessive length or invalid UTF-8.
207 ///
208 /// # Cancellation safety
209 ///
210 /// This operation is not cancellation safe; dropping the future retains
211 /// any prefix or payload bytes already consumed.
212 #[inline]
213 fn read_utf8_string_uleb_u64_strict_async(&mut self, max_len: usize) -> impl Future<Output = Result<String>> + '_
214 where
215 Self: Unpin,
216 {
217 async move {
218 let len = self.read_uleb_u64_strict_async().await?;
219 #[cfg(target_pointer_width = "64")]
220 let len = len as usize;
221 #[cfg(not(target_pointer_width = "64"))]
222 let len = usize_from_u64_len(len)?;
223 read_utf8_payload_async(self, len, max_len).await
224 }
225 }
226
227 /// Asynchronously reads a runtime-order `u16`-length UTF-8 string.
228 ///
229 /// # Parameters
230 ///
231 /// - `byte_order`: Byte order used to decode the length.
232 /// - `max_len`: Maximum accepted payload length in bytes.
233 ///
234 /// # Returns
235 ///
236 /// Returns the decoded string.
237 ///
238 /// # Errors
239 ///
240 /// Returns an input or allocation error, or an invalid-data error for an
241 /// excessive length or invalid UTF-8.
242 ///
243 /// # Cancellation safety
244 ///
245 /// This operation is not cancellation safe; dropping the future retains
246 /// any prefix or payload bytes already consumed.
247 #[inline]
248 fn read_string_with_u16_len_async(
249 &mut self,
250 byte_order: ByteOrder,
251 max_len: usize,
252 ) -> impl Future<Output = Result<String>> + '_
253 where
254 Self: Unpin,
255 {
256 async move {
257 let len = usize::from(self.read_u16_async(byte_order).await?);
258 read_utf8_payload_async(self, len, max_len).await
259 }
260 }
261
262 /// Asynchronously reads a big-endian `u16`-length UTF-8 string.
263 ///
264 /// # Parameters
265 ///
266 /// - `max_len`: Maximum accepted payload length in bytes.
267 ///
268 /// # Returns
269 ///
270 /// Returns the decoded string.
271 ///
272 /// # Errors
273 ///
274 /// Returns an input or allocation error, or an invalid-data error for an
275 /// excessive length or invalid UTF-8.
276 ///
277 /// # Cancellation safety
278 ///
279 /// This operation is not cancellation safe; dropping the future retains
280 /// any prefix or payload bytes already consumed.
281 #[inline]
282 fn read_string_with_u16_len_be_async(&mut self, max_len: usize) -> impl Future<Output = Result<String>> + '_
283 where
284 Self: Unpin,
285 {
286 async move {
287 let len = usize::from(self.read_u16_be_async().await?);
288 read_utf8_payload_async(self, len, max_len).await
289 }
290 }
291
292 /// Asynchronously reads a little-endian `u16`-length UTF-8 string.
293 ///
294 /// # Parameters
295 ///
296 /// - `max_len`: Maximum accepted payload length in bytes.
297 ///
298 /// # Returns
299 ///
300 /// Returns the decoded string.
301 ///
302 /// # Errors
303 ///
304 /// Returns an input or allocation error, or an invalid-data error for an
305 /// excessive length or invalid UTF-8.
306 ///
307 /// # Cancellation safety
308 ///
309 /// This operation is not cancellation safe; dropping the future retains
310 /// any prefix or payload bytes already consumed.
311 #[inline]
312 fn read_string_with_u16_len_le_async(&mut self, max_len: usize) -> impl Future<Output = Result<String>> + '_
313 where
314 Self: Unpin,
315 {
316 async move {
317 let len = usize::from(self.read_u16_le_async().await?);
318 read_utf8_payload_async(self, len, max_len).await
319 }
320 }
321
322 /// Asynchronously reads a runtime-order `u32`-length UTF-8 string.
323 ///
324 /// # Parameters
325 ///
326 /// - `byte_order`: Byte order used to decode the length.
327 /// - `max_len`: Maximum accepted payload length in bytes.
328 ///
329 /// # Returns
330 ///
331 /// Returns the decoded string.
332 ///
333 /// # Errors
334 ///
335 /// Returns an input, conversion, or allocation error, or an invalid-data
336 /// error for an excessive length or invalid UTF-8.
337 ///
338 /// # Cancellation safety
339 ///
340 /// This operation is not cancellation safe; dropping the future retains
341 /// any prefix or payload bytes already consumed.
342 #[inline]
343 fn read_string_with_u32_len_async(
344 &mut self,
345 byte_order: ByteOrder,
346 max_len: usize,
347 ) -> impl Future<Output = Result<String>> + '_
348 where
349 Self: Unpin,
350 {
351 async move {
352 let len = self.read_u32_async(byte_order).await?;
353 #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
354 let len = len as usize;
355 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
356 let len = usize_from_u32_len(len)?;
357 read_utf8_payload_async(self, len, max_len).await
358 }
359 }
360
361 /// Asynchronously reads a big-endian `u32`-length UTF-8 string.
362 ///
363 /// # Parameters
364 ///
365 /// - `max_len`: Maximum accepted payload length in bytes.
366 ///
367 /// # Returns
368 ///
369 /// Returns the decoded string.
370 ///
371 /// # Errors
372 ///
373 /// Returns an input, conversion, or allocation error, or an invalid-data
374 /// error for an excessive length or invalid UTF-8.
375 ///
376 /// # Cancellation safety
377 ///
378 /// This operation is not cancellation safe; dropping the future retains
379 /// any prefix or payload bytes already consumed.
380 #[inline]
381 fn read_string_with_u32_len_be_async(&mut self, max_len: usize) -> impl Future<Output = Result<String>> + '_
382 where
383 Self: Unpin,
384 {
385 async move {
386 let len = self.read_u32_be_async().await?;
387 #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
388 let len = len as usize;
389 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
390 let len = usize_from_u32_len(len)?;
391 read_utf8_payload_async(self, len, max_len).await
392 }
393 }
394
395 /// Asynchronously reads a little-endian `u32`-length UTF-8 string.
396 ///
397 /// # Parameters
398 ///
399 /// - `max_len`: Maximum accepted payload length in bytes.
400 ///
401 /// # Returns
402 ///
403 /// Returns the decoded string.
404 ///
405 /// # Errors
406 ///
407 /// Returns an input, conversion, or allocation error, or an invalid-data
408 /// error for an excessive length or invalid UTF-8.
409 ///
410 /// # Cancellation safety
411 ///
412 /// This operation is not cancellation safe; dropping the future retains
413 /// any prefix or payload bytes already consumed.
414 #[inline]
415 fn read_string_with_u32_len_le_async(&mut self, max_len: usize) -> impl Future<Output = Result<String>> + '_
416 where
417 Self: Unpin,
418 {
419 async move {
420 let len = self.read_u32_le_async().await?;
421 #[cfg(any(target_pointer_width = "32", target_pointer_width = "64"))]
422 let len = len as usize;
423 #[cfg(not(any(target_pointer_width = "32", target_pointer_width = "64")))]
424 let len = usize_from_u32_len(len)?;
425 read_utf8_payload_async(self, len, max_len).await
426 }
427 }
428}
429
430impl<R> AsyncStringReadExt for R where R: AsyncInput<Item = u8> + ?Sized {}