Skip to main content

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 {}