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 {}