qubit_io_binary/ext/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// =============================================================================
8use std::io::Result;
9
10use crate::util::{
11 checked_u64_len,
12 write_all,
13 write_utf8_payload as write_utf8_payload_impl,
14 write_utf8_string_with_u16_len,
15 write_utf8_string_with_u32_len,
16};
17use crate::{
18 BinaryWriteExt,
19 Leb128WriteExt,
20};
21use qubit_codec::ByteOrder;
22use qubit_io::Output;
23
24/// Extension methods for writing length-prefixed UTF-8 strings.
25pub trait StringWriteExt: Output<Item = u8> {
26 /// Writes a UTF-8 payload without a length prefix.
27 ///
28 /// # Parameters
29 ///
30 /// - `value`: String slice to write.
31 ///
32 /// # Returns
33 ///
34 /// Returns after the payload has been written.
35 ///
36 /// # Errors
37 ///
38 /// Returns an I/O error from the underlying writer.
39 fn write_utf8_payload(&mut self, value: &str) -> Result<()>;
40
41 /// Writes a UTF-8 string with an unsigned LEB128 byte-length prefix.
42 ///
43 /// The length prefix is encoded as `usize`, so this format is target-width
44 /// dependent. Prefer `u16` or `u32` length-prefix methods for persistent
45 /// files and cross-platform protocols.
46 ///
47 /// # Parameters
48 ///
49 /// - `value`: String slice to write.
50 ///
51 /// # Returns
52 ///
53 /// Returns after the prefix and payload have been written.
54 ///
55 /// # Errors
56 ///
57 /// Returns an I/O error from the underlying writer.
58 fn write_utf8_string_uleb_usize(&mut self, value: &str) -> Result<()>;
59
60 /// Writes a UTF-8 string with an unsigned LEB128 `u64` byte-length prefix.
61 ///
62 /// Prefer this method over [`Self::write_utf8_string_uleb_usize`] for
63 /// persistent files and cross-platform protocols because the length
64 /// field is independent of the current Rust target's pointer width.
65 ///
66 /// # Parameters
67 ///
68 /// - `value`: String slice to write.
69 ///
70 /// # Returns
71 ///
72 /// Returns after the prefix and payload have been written.
73 ///
74 /// # Errors
75 ///
76 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
77 /// cannot be represented as `u64`, or an I/O error from the underlying
78 /// writer.
79 fn write_utf8_string_uleb_u64(&mut self, value: &str) -> Result<()>;
80
81 /// Writes a UTF-8 string with a runtime-order `u16` byte-length prefix.
82 ///
83 /// # Parameters
84 ///
85 /// - `value`: String slice to write.
86 /// - `byte_order`: Byte order used by the length prefix.
87 ///
88 /// # Returns
89 ///
90 /// Returns after the prefix and payload have been written.
91 ///
92 /// # Errors
93 ///
94 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
95 /// does not fit into `u16`, or an I/O error from the underlying writer.
96 fn write_string_with_u16_len(
97 &mut self,
98 value: &str,
99 byte_order: ByteOrder,
100 ) -> Result<()>;
101
102 /// Writes a UTF-8 string with a big-endian `u16` byte-length prefix.
103 ///
104 /// # Parameters
105 ///
106 /// - `value`: String slice to write.
107 ///
108 /// # Returns
109 ///
110 /// Returns after the prefix and payload have been written.
111 ///
112 /// # Errors
113 ///
114 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
115 /// does not fit into `u16`, or an I/O error from the underlying writer.
116 fn write_string_with_u16_len_be(&mut self, value: &str) -> Result<()>;
117
118 /// Writes a UTF-8 string with a little-endian `u16` byte-length prefix.
119 ///
120 /// # Parameters
121 ///
122 /// - `value`: String slice to write.
123 ///
124 /// # Returns
125 ///
126 /// Returns after the prefix and payload have been written.
127 ///
128 /// # Errors
129 ///
130 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
131 /// does not fit into `u16`, or an I/O error from the underlying writer.
132 fn write_string_with_u16_len_le(&mut self, value: &str) -> Result<()>;
133
134 /// Writes a UTF-8 string with a runtime-order `u32` byte-length prefix.
135 ///
136 /// # Parameters
137 ///
138 /// - `value`: String slice to write.
139 /// - `byte_order`: Byte order used by the length prefix.
140 ///
141 /// # Returns
142 ///
143 /// Returns after the prefix and payload have been written.
144 ///
145 /// # Errors
146 ///
147 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
148 /// does not fit into `u32`, or an I/O error from the underlying writer.
149 fn write_string_with_u32_len(
150 &mut self,
151 value: &str,
152 byte_order: ByteOrder,
153 ) -> Result<()>;
154
155 /// Writes a UTF-8 string with a big-endian `u32` byte-length prefix.
156 ///
157 /// # Parameters
158 ///
159 /// - `value`: String slice to write.
160 ///
161 /// # Returns
162 ///
163 /// Returns after the prefix and payload have been written.
164 ///
165 /// # Errors
166 ///
167 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
168 /// does not fit into `u32`, or an I/O error from the underlying writer.
169 fn write_string_with_u32_len_be(&mut self, value: &str) -> Result<()>;
170
171 /// Writes a UTF-8 string with a little-endian `u32` byte-length prefix.
172 ///
173 /// # Parameters
174 ///
175 /// - `value`: String slice to write.
176 ///
177 /// # Returns
178 ///
179 /// Returns after the prefix and payload have been written.
180 ///
181 /// # Errors
182 ///
183 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
184 /// does not fit into `u32`, or an I/O error from the underlying writer.
185 fn write_string_with_u32_len_le(&mut self, value: &str) -> Result<()>;
186}
187
188impl<T> StringWriteExt for T
189where
190 T: Output<Item = u8> + ?Sized,
191{
192 #[inline]
193 fn write_utf8_payload(&mut self, value: &str) -> Result<()> {
194 write_utf8_payload_impl(self, value)
195 }
196
197 #[inline]
198 fn write_utf8_string_uleb_usize(&mut self, value: &str) -> Result<()> {
199 let bytes = value.as_bytes();
200 self.write_uleb_usize(bytes.len())?;
201 write_all(self, bytes)
202 }
203
204 #[inline]
205 fn write_utf8_string_uleb_u64(&mut self, value: &str) -> Result<()> {
206 let bytes = value.as_bytes();
207 self.write_uleb_u64(checked_u64_len(bytes.len())?)?;
208 write_all(self, bytes)
209 }
210
211 #[inline]
212 fn write_string_with_u16_len(
213 &mut self,
214 value: &str,
215 byte_order: ByteOrder,
216 ) -> Result<()> {
217 write_utf8_string_with_u16_len(self, value, |writer, len| {
218 writer.write_u16(len, byte_order)
219 })
220 }
221
222 #[inline]
223 fn write_string_with_u16_len_be(&mut self, value: &str) -> Result<()> {
224 write_utf8_string_with_u16_len(self, value, |writer, len| {
225 writer.write_u16_be(len)
226 })
227 }
228
229 #[inline]
230 fn write_string_with_u16_len_le(&mut self, value: &str) -> Result<()> {
231 write_utf8_string_with_u16_len(self, value, |writer, len| {
232 writer.write_u16_le(len)
233 })
234 }
235
236 #[inline]
237 fn write_string_with_u32_len(
238 &mut self,
239 value: &str,
240 byte_order: ByteOrder,
241 ) -> Result<()> {
242 write_utf8_string_with_u32_len(self, value, |writer, len| {
243 writer.write_u32(len, byte_order)
244 })
245 }
246
247 #[inline]
248 fn write_string_with_u32_len_be(&mut self, value: &str) -> Result<()> {
249 write_utf8_string_with_u32_len(self, value, |writer, len| {
250 writer.write_u32_be(len)
251 })
252 }
253
254 #[inline]
255 fn write_string_with_u32_len_le(&mut self, value: &str) -> Result<()> {
256 write_utf8_string_with_u32_len(self, value, |writer, len| {
257 writer.write_u32_le(len)
258 })
259 }
260}