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