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