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