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