Skip to main content

qubit_io_binary/ext/
async_string_write_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 writes.
9
10use core::future::Future;
11use std::io::Result;
12
13use qubit_codec::ByteOrder;
14use qubit_io::AsyncOutput;
15
16use crate::AsyncBinaryWriteExt;
17use crate::AsyncLeb128WriteExt;
18use crate::util::checked_u16_len;
19use crate::util::checked_u32_len;
20use crate::util::checked_u64_len;
21use crate::util::write_all_async;
22
23/// Future-based length-prefixed UTF-8 writes.
24///
25/// # Cancellation safety
26///
27/// These writes are not cancellation safe. Dropping a pending future leaves
28/// any already-written prefix or payload bytes in the output.
29pub trait AsyncStringWriteExt: AsyncOutput<Item = u8> {
30    /// Asynchronously writes a UTF-8 payload without a length prefix.
31    ///
32    /// # Parameters
33    ///
34    /// - `value`: String payload to write.
35    ///
36    /// # Returns
37    ///
38    /// Returns a future that completes after the payload has been written.
39    ///
40    /// # Errors
41    ///
42    /// Returns an output error, including a write-zero error when the output
43    /// stops making progress.
44    ///
45    /// # Cancellation safety
46    ///
47    /// This operation is not cancellation safe; dropping the future leaves
48    /// any already-written payload prefix in the output.
49    #[inline]
50    fn write_utf8_payload_async<'a>(&'a mut self, value: &'a str) -> impl Future<Output = Result<()>> + 'a
51    where
52        Self: Unpin,
53    {
54        async move { write_all_async(self, value.as_bytes()).await }
55    }
56
57    /// Asynchronously writes a target-width LEB128-length UTF-8 string.
58    ///
59    /// # Parameters
60    ///
61    /// - `value`: String to length-prefix and write.
62    ///
63    /// # Returns
64    ///
65    /// Returns a future that completes after the prefix and payload are
66    /// written.
67    ///
68    /// # Errors
69    ///
70    /// Returns an output error, including a write-zero error when the output
71    /// stops making progress.
72    ///
73    /// # Cancellation safety
74    ///
75    /// This operation is not cancellation safe; dropping the future leaves
76    /// any already-written prefix or payload bytes in the output.
77    #[inline]
78    fn write_utf8_string_uleb_usize_async<'a>(&'a mut self, value: &'a str) -> impl Future<Output = Result<()>> + 'a
79    where
80        Self: Unpin,
81    {
82        async move {
83            self.write_uleb_usize_async(value.len()).await?;
84            write_all_async(self, value.as_bytes()).await
85        }
86    }
87
88    /// Asynchronously writes a `u64` LEB128-length UTF-8 string.
89    ///
90    /// # Parameters
91    ///
92    /// - `value`: String to length-prefix and write.
93    ///
94    /// # Returns
95    ///
96    /// Returns a future that completes after the prefix and payload are
97    /// written.
98    ///
99    /// # Errors
100    ///
101    /// Returns an invalid-input error when the length cannot fit in `u64`, or
102    /// an output error while writing.
103    ///
104    /// # Cancellation safety
105    ///
106    /// This operation is not cancellation safe; dropping the future leaves
107    /// any already-written prefix or payload bytes in the output.
108    #[inline]
109    fn write_utf8_string_uleb_u64_async<'a>(&'a mut self, value: &'a str) -> impl Future<Output = Result<()>> + 'a
110    where
111        Self: Unpin,
112    {
113        async move {
114            let len = checked_u64_len(value.len())?;
115            self.write_uleb_u64_async(len).await?;
116            write_all_async(self, value.as_bytes()).await
117        }
118    }
119
120    /// Asynchronously writes a runtime-order `u16`-length UTF-8 string.
121    ///
122    /// # Parameters
123    ///
124    /// - `value`: String to length-prefix and write.
125    /// - `byte_order`: Byte order used to encode the length.
126    ///
127    /// # Returns
128    ///
129    /// Returns a future that completes after the prefix and payload are
130    /// written.
131    ///
132    /// # Errors
133    ///
134    /// Returns an invalid-input error when the length exceeds `u16::MAX`, or
135    /// an output error while writing.
136    ///
137    /// # Cancellation safety
138    ///
139    /// This operation is not cancellation safe; dropping the future leaves
140    /// any already-written prefix or payload bytes in the output.
141    #[inline]
142    fn write_string_with_u16_len_async<'a>(
143        &'a mut self,
144        value: &'a str,
145        byte_order: ByteOrder,
146    ) -> impl Future<Output = Result<()>> + 'a
147    where
148        Self: Unpin,
149    {
150        async move {
151            let len = checked_u16_len(value.len())?;
152            self.write_u16_async(len, byte_order).await?;
153            write_all_async(self, value.as_bytes()).await
154        }
155    }
156
157    /// Asynchronously writes a big-endian `u16`-length UTF-8 string.
158    ///
159    /// # Parameters
160    ///
161    /// - `value`: String to length-prefix and write.
162    ///
163    /// # Returns
164    ///
165    /// Returns a future that completes after the prefix and payload are
166    /// written.
167    ///
168    /// # Errors
169    ///
170    /// Returns an invalid-input error when the length exceeds `u16::MAX`, or
171    /// an output error while writing.
172    ///
173    /// # Cancellation safety
174    ///
175    /// This operation is not cancellation safe; dropping the future leaves
176    /// any already-written prefix or payload bytes in the output.
177    #[inline]
178    fn write_string_with_u16_len_be_async<'a>(&'a mut self, value: &'a str) -> impl Future<Output = Result<()>> + 'a
179    where
180        Self: Unpin,
181    {
182        async move {
183            let len = checked_u16_len(value.len())?;
184            self.write_u16_be_async(len).await?;
185            write_all_async(self, value.as_bytes()).await
186        }
187    }
188
189    /// Asynchronously writes a little-endian `u16`-length UTF-8 string.
190    ///
191    /// # Parameters
192    ///
193    /// - `value`: String to length-prefix and write.
194    ///
195    /// # Returns
196    ///
197    /// Returns a future that completes after the prefix and payload are
198    /// written.
199    ///
200    /// # Errors
201    ///
202    /// Returns an invalid-input error when the length exceeds `u16::MAX`, or
203    /// an output error while writing.
204    ///
205    /// # Cancellation safety
206    ///
207    /// This operation is not cancellation safe; dropping the future leaves
208    /// any already-written prefix or payload bytes in the output.
209    #[inline]
210    fn write_string_with_u16_len_le_async<'a>(&'a mut self, value: &'a str) -> impl Future<Output = Result<()>> + 'a
211    where
212        Self: Unpin,
213    {
214        async move {
215            let len = checked_u16_len(value.len())?;
216            self.write_u16_le_async(len).await?;
217            write_all_async(self, value.as_bytes()).await
218        }
219    }
220
221    /// Asynchronously writes a runtime-order `u32`-length UTF-8 string.
222    ///
223    /// # Parameters
224    ///
225    /// - `value`: String to length-prefix and write.
226    /// - `byte_order`: Byte order used to encode the length.
227    ///
228    /// # Returns
229    ///
230    /// Returns a future that completes after the prefix and payload are
231    /// written.
232    ///
233    /// # Errors
234    ///
235    /// Returns an invalid-input error when the length exceeds `u32::MAX`, or
236    /// an output error while writing.
237    ///
238    /// # Cancellation safety
239    ///
240    /// This operation is not cancellation safe; dropping the future leaves
241    /// any already-written prefix or payload bytes in the output.
242    #[inline]
243    fn write_string_with_u32_len_async<'a>(
244        &'a mut self,
245        value: &'a str,
246        byte_order: ByteOrder,
247    ) -> impl Future<Output = Result<()>> + 'a
248    where
249        Self: Unpin,
250    {
251        async move {
252            let len = checked_u32_len(value.len())?;
253            self.write_u32_async(len, byte_order).await?;
254            write_all_async(self, value.as_bytes()).await
255        }
256    }
257
258    /// Asynchronously writes a big-endian `u32`-length UTF-8 string.
259    ///
260    /// # Parameters
261    ///
262    /// - `value`: String to length-prefix and write.
263    ///
264    /// # Returns
265    ///
266    /// Returns a future that completes after the prefix and payload are
267    /// written.
268    ///
269    /// # Errors
270    ///
271    /// Returns an invalid-input error when the length exceeds `u32::MAX`, or
272    /// an output error while writing.
273    ///
274    /// # Cancellation safety
275    ///
276    /// This operation is not cancellation safe; dropping the future leaves
277    /// any already-written prefix or payload bytes in the output.
278    #[inline]
279    fn write_string_with_u32_len_be_async<'a>(&'a mut self, value: &'a str) -> impl Future<Output = Result<()>> + 'a
280    where
281        Self: Unpin,
282    {
283        async move {
284            let len = checked_u32_len(value.len())?;
285            self.write_u32_be_async(len).await?;
286            write_all_async(self, value.as_bytes()).await
287        }
288    }
289
290    /// Asynchronously writes a little-endian `u32`-length UTF-8 string.
291    ///
292    /// # Parameters
293    ///
294    /// - `value`: String to length-prefix and write.
295    ///
296    /// # Returns
297    ///
298    /// Returns a future that completes after the prefix and payload are
299    /// written.
300    ///
301    /// # Errors
302    ///
303    /// Returns an invalid-input error when the length exceeds `u32::MAX`, or
304    /// an output error while writing.
305    ///
306    /// # Cancellation safety
307    ///
308    /// This operation is not cancellation safe; dropping the future leaves
309    /// any already-written prefix or payload bytes in the output.
310    #[inline]
311    fn write_string_with_u32_len_le_async<'a>(&'a mut self, value: &'a str) -> impl Future<Output = Result<()>> + 'a
312    where
313        Self: Unpin,
314    {
315        async move {
316            let len = checked_u32_len(value.len())?;
317            self.write_u32_le_async(len).await?;
318            write_all_async(self, value.as_bytes()).await
319        }
320    }
321}
322
323impl<W> AsyncStringWriteExt for W where W: AsyncOutput<Item = u8> + ?Sized {}