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