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