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// =============================================================================
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}