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