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