Skip to main content

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}