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