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(&mut self, value: &str, byte_order: ByteOrder) -> Result<()>;
96
97 /// Writes a UTF-8 string with a big-endian `u16` byte-length prefix.
98 ///
99 /// # Parameters
100 ///
101 /// - `value`: String slice to write.
102 ///
103 /// # Returns
104 ///
105 /// Returns after the prefix and payload have been written.
106 ///
107 /// # Errors
108 ///
109 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
110 /// does not fit into `u16`, or an I/O error from the underlying writer.
111 fn write_string_with_u16_len_be(&mut self, value: &str) -> Result<()>;
112
113 /// Writes a UTF-8 string with a little-endian `u16` byte-length prefix.
114 ///
115 /// # Parameters
116 ///
117 /// - `value`: String slice to write.
118 ///
119 /// # Returns
120 ///
121 /// Returns after the prefix and payload have been written.
122 ///
123 /// # Errors
124 ///
125 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
126 /// does not fit into `u16`, or an I/O error from the underlying writer.
127 fn write_string_with_u16_len_le(&mut self, value: &str) -> Result<()>;
128
129 /// Writes a UTF-8 string with a runtime-order `u32` byte-length prefix.
130 ///
131 /// # Parameters
132 ///
133 /// - `value`: String slice to write.
134 /// - `byte_order`: Byte order used by the length prefix.
135 ///
136 /// # Returns
137 ///
138 /// Returns after the prefix and payload have been written.
139 ///
140 /// # Errors
141 ///
142 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
143 /// does not fit into `u32`, or an I/O error from the underlying writer.
144 fn write_string_with_u32_len(&mut self, value: &str, byte_order: ByteOrder) -> Result<()>;
145
146 /// Writes a UTF-8 string with a big-endian `u32` byte-length prefix.
147 ///
148 /// # Parameters
149 ///
150 /// - `value`: String slice to write.
151 ///
152 /// # Returns
153 ///
154 /// Returns after the prefix and payload have been written.
155 ///
156 /// # Errors
157 ///
158 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
159 /// does not fit into `u32`, or an I/O error from the underlying writer.
160 fn write_string_with_u32_len_be(&mut self, value: &str) -> Result<()>;
161
162 /// Writes a UTF-8 string with a little-endian `u32` byte-length prefix.
163 ///
164 /// # Parameters
165 ///
166 /// - `value`: String slice to write.
167 ///
168 /// # Returns
169 ///
170 /// Returns after the prefix and payload have been written.
171 ///
172 /// # Errors
173 ///
174 /// Returns [`std::io::ErrorKind::InvalidInput`] when the UTF-8 byte length
175 /// does not fit into `u32`, or an I/O error from the underlying writer.
176 fn write_string_with_u32_len_le(&mut self, value: &str) -> Result<()>;
177}
178
179impl<T> StringWriteExt for T
180where
181 T: Output<Item = u8> + ?Sized,
182{
183 #[inline]
184 fn write_utf8_payload(&mut self, value: &str) -> Result<()> {
185 write_utf8_payload_impl(self, value)
186 }
187
188 #[inline]
189 fn write_utf8_string_uleb_usize(&mut self, value: &str) -> Result<()> {
190 let bytes = value.as_bytes();
191 self.write_uleb_usize(bytes.len())?;
192 write_all(self, bytes)
193 }
194
195 #[inline]
196 fn write_utf8_string_uleb_u64(&mut self, value: &str) -> Result<()> {
197 let bytes = value.as_bytes();
198 self.write_uleb_u64(checked_u64_len(bytes.len())?)?;
199 write_all(self, bytes)
200 }
201
202 #[inline]
203 fn write_string_with_u16_len(&mut self, value: &str, byte_order: ByteOrder) -> Result<()> {
204 write_utf8_string_with_u16_len(self, value, |writer, len| writer.write_u16(len, byte_order))
205 }
206
207 #[inline]
208 fn write_string_with_u16_len_be(&mut self, value: &str) -> Result<()> {
209 write_utf8_string_with_u16_len(self, value, |writer, len| writer.write_u16_be(len))
210 }
211
212 #[inline]
213 fn write_string_with_u16_len_le(&mut self, value: &str) -> Result<()> {
214 write_utf8_string_with_u16_len(self, value, |writer, len| writer.write_u16_le(len))
215 }
216
217 #[inline]
218 fn write_string_with_u32_len(&mut self, value: &str, byte_order: ByteOrder) -> Result<()> {
219 write_utf8_string_with_u32_len(self, value, |writer, len| writer.write_u32(len, byte_order))
220 }
221
222 #[inline]
223 fn write_string_with_u32_len_be(&mut self, value: &str) -> Result<()> {
224 write_utf8_string_with_u32_len(self, value, |writer, len| writer.write_u32_be(len))
225 }
226
227 #[inline]
228 fn write_string_with_u32_len_le(&mut self, value: &str) -> Result<()> {
229 write_utf8_string_with_u32_len(self, value, |writer, len| writer.write_u32_le(len))
230 }
231}