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