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(&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}