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