qubit_io_binary/stream/buffered_leb128_reader.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
9//! Buffered reader for LEB128-encoded values.
10
11use core::marker::PhantomData;
12use std::collections::TryReserveError;
13use std::io::Result;
14use std::io::SeekFrom;
15
16use qubit_codec::TranscodeDecodeInput;
17use qubit_codec_binary::Leb128Codec;
18use qubit_codec_binary::Leb128DecodePolicy;
19use qubit_codec_binary::NonStrict;
20use qubit_codec_binary::Strict;
21use qubit_io::Buffer;
22use qubit_io::Input;
23use qubit_io::Seekable;
24
25use super::internal::TranscodeDecodeInputExt;
26use crate::util::MIN_CODEC_BUFFER_CAPACITY;
27use crate::util::read_utf8_payload;
28#[cfg(not(target_pointer_width = "64"))]
29use crate::util::usize_from_u64_len;
30
31/// Buffered reader for LEB128 integers.
32///
33/// Values are decoded directly from the internal input buffer while the codec
34/// scans for the LEB128 terminating byte.
35///
36/// # Buffered state
37///
38/// This reader may prefetch bytes from the wrapped reader. As a result,
39/// [`Self::inner`] can observe an underlying stream position ahead of the
40/// logical position exposed by this wrapper.
41///
42/// # Target-width integers
43///
44/// `usize` and `isize` methods use the current Rust target's pointer width.
45/// Prefer fixed-width integer methods such as `read_u64` or `read_i64` for
46/// persistent files and cross-platform protocols.
47///
48/// # Type Parameters
49///
50/// - `R`: Underlying byte input.
51/// - `P`: LEB128 canonicality policy.
52pub struct BufferedLeb128Reader<R, P>
53where
54 R: Input<Item = u8>,
55{
56 /// Buffered codec input and wrapped reader.
57 input: TranscodeDecodeInput<R>,
58 /// Associates the selected decoding policy without storing a value.
59 marker: PhantomData<fn() -> P>,
60}
61
62impl<R, P> BufferedLeb128Reader<R, P>
63where
64 R: Input<Item = u8>,
65 P: Leb128DecodePolicy,
66{
67 /// Creates a buffered LEB128 reader with the default buffer capacity.
68 ///
69 /// # Parameters
70 ///
71 /// - `inner`: Underlying byte input.
72 ///
73 /// # Returns
74 ///
75 /// Returns a buffered reader using policy `P`.
76 #[must_use]
77 #[inline]
78 pub fn new(inner: R) -> Self {
79 Self {
80 input: TranscodeDecodeInput::new(inner),
81 marker: PhantomData,
82 }
83 }
84
85 /// Creates a buffered LEB128 reader with at least `capacity` bytes.
86 ///
87 /// # Parameters
88 ///
89 /// - `inner`: Underlying byte input.
90 /// - `capacity`: Requested internal buffer capacity in bytes.
91 ///
92 /// # Returns
93 ///
94 /// Returns a buffered reader whose capacity also satisfies the largest
95 /// supported codec payload.
96 #[must_use]
97 #[inline]
98 pub fn with_capacity(inner: R, capacity: usize) -> Self {
99 Self {
100 input: TranscodeDecodeInput::with_capacity(inner, capacity.max(MIN_CODEC_BUFFER_CAPACITY)),
101 marker: PhantomData,
102 }
103 }
104
105 /// Tries to create a buffered LEB128 reader with at least `capacity` bytes.
106 ///
107 /// # Errors
108 ///
109 /// Returns an allocation error when the requested buffer cannot be
110 /// allocated.
111 #[inline]
112 pub fn try_with_capacity(inner: R, capacity: usize) -> std::result::Result<Self, TryReserveError> {
113 Ok(Self {
114 input: TranscodeDecodeInput::try_with_capacity(inner, capacity.max(MIN_CODEC_BUFFER_CAPACITY))?,
115 marker: PhantomData,
116 })
117 }
118
119 /// Returns whether this reader rejects non-canonical encodings.
120 ///
121 /// # Returns
122 ///
123 /// Returns `true` when policy `P` requires canonical encodings.
124 #[must_use]
125 #[inline(always)]
126 pub const fn is_strict(&self) -> bool {
127 P::STRICT
128 }
129
130 /// Returns a shared reference to the underlying reader.
131 ///
132 /// The underlying reader may already be positioned past unread bytes held
133 /// in this wrapper's internal buffer.
134 ///
135 /// # Returns
136 ///
137 /// Returns the wrapped reader.
138 #[must_use]
139 #[inline(always)]
140 pub const fn inner(&self) -> &R {
141 self.input.inner()
142 }
143
144 /// Consumes this wrapper and preserves its unread buffered bytes.
145 ///
146 /// # Returns
147 ///
148 /// Returns the wrapped reader and the buffer whose [`Buffer::readable`]
149 /// slice contains every prefetched byte not yet consumed logically. To
150 /// continue the same logical stream, consume that slice before reading
151 /// from the returned reader.
152 #[inline(always)]
153 #[must_use = "the returned inner reader and unread buffer must be handled"]
154 pub fn into_parts(self) -> (R, Buffer<u8>) {
155 self.input.into_parts()
156 }
157}
158
159macro_rules! impl_read_value {
160 ($policy:ty, $method:ident, $ty:ty, $doc:literal) => {
161 #[doc = $doc]
162 #[doc = ""]
163 #[doc = "# Returns"]
164 #[doc = ""]
165 #[doc = concat!("Returns the decoded `", stringify!($ty), "`.")]
166 #[doc = ""]
167 #[doc = "# Errors"]
168 #[doc = ""]
169 #[doc = "Returns an input error or an invalid-data error when the \
170 payload is malformed or violates the selected policy."]
171 #[inline(always)]
172 pub fn $method(&mut self) -> Result<$ty> {
173 type Codec = Leb128Codec<$ty, $policy>;
174
175 self.input.read_decoded::<Codec>()
176 }
177 };
178}
179
180macro_rules! impl_for_policy {
181 (
182 $policy:ty,
183 $read_usize:ident,
184 $read_u64:ident,
185 $read_utf8_string_usize:ident,
186 $read_utf8_string_u64:ident,
187 {
188 $(($method:ident, $ty:ty, $doc:literal)),* $(,)?
189 }
190 $(,)?
191 ) => {
192 impl<R> BufferedLeb128Reader<R, $policy>
193 where
194 R: Input<Item = u8>,
195 {
196 $(
197 impl_read_value!($policy, $method, $ty, $doc);
198 )*
199
200 /// Reads a UTF-8 string prefixed by an unsigned LEB128 byte length.
201 ///
202 /// The length prefix is decoded as usize, so this format is
203 /// target-width dependent. Prefer a fixed-width length prefix for
204 /// persistent files and cross-platform protocols.
205 ///
206 /// # Parameters
207 ///
208 /// - max_len: Maximum accepted UTF-8 payload length in bytes.
209 ///
210 /// # Returns
211 ///
212 /// Returns the decoded UTF-8 string.
213 ///
214 /// # Errors
215 ///
216 /// Returns an input or allocation error, or an invalid-data error
217 /// for a malformed or excessive length or invalid UTF-8.
218 #[inline]
219 pub fn $read_utf8_string_usize(
220 &mut self,
221 max_len: usize,
222 ) -> Result<String> {
223 let len = self.$read_usize()?;
224 read_utf8_payload(&mut self.input, len, max_len)
225 }
226
227 /// Reads a UTF-8 string prefixed by an unsigned LEB128 u64 byte
228 /// length.
229 ///
230 /// Prefer this method over the usize variant for persistent files
231 /// and cross-platform protocols because the length field is
232 /// independent of the current Rust target's pointer width.
233 ///
234 /// # Parameters
235 ///
236 /// - max_len: Maximum accepted UTF-8 payload length in bytes.
237 ///
238 /// # Returns
239 ///
240 /// Returns the decoded UTF-8 string.
241 ///
242 /// # Errors
243 ///
244 /// Returns an input, conversion, or allocation error, or an
245 /// invalid-data error for a malformed or excessive length or
246 /// invalid UTF-8.
247 #[inline]
248 pub fn $read_utf8_string_u64(
249 &mut self,
250 max_len: usize,
251 ) -> Result<String> {
252 let len = self.$read_u64()?;
253 #[cfg(target_pointer_width = "64")]
254 let len = len as usize;
255 #[cfg(not(target_pointer_width = "64"))]
256 let len = usize_from_u64_len(len)?;
257 read_utf8_payload(&mut self.input, len, max_len)
258 }
259 }
260 };
261}
262
263impl_for_policy!(
264 NonStrict,
265 read_usize_non_strict,
266 read_u64_non_strict,
267 read_utf8_string_usize_non_strict,
268 read_utf8_string_u64_non_strict,
269 {
270 (read_u8_non_strict, u8, "Reads an unsigned LEB128 u8."),
271 (read_u16_non_strict, u16, "Reads an unsigned LEB128 u16."),
272 (read_u32_non_strict, u32, "Reads an unsigned LEB128 u32."),
273 (read_u64_non_strict, u64, "Reads an unsigned LEB128 u64."),
274 (read_u128_non_strict, u128, "Reads an unsigned LEB128 u128."),
275 (read_usize_non_strict, usize, "Reads an unsigned LEB128 usize."),
276 (read_i8_non_strict, i8, "Reads a signed LEB128 i8."),
277 (read_i16_non_strict, i16, "Reads a signed LEB128 i16."),
278 (read_i32_non_strict, i32, "Reads a signed LEB128 i32."),
279 (read_i64_non_strict, i64, "Reads a signed LEB128 i64."),
280 (read_i128_non_strict, i128, "Reads a signed LEB128 i128."),
281 (read_isize_non_strict, isize, "Reads a signed LEB128 isize."),
282 },
283);
284impl_for_policy!(
285 Strict,
286 read_usize,
287 read_u64,
288 read_utf8_string_usize,
289 read_utf8_string_u64,
290 {
291 (read_u8, u8, "Reads an unsigned LEB128 u8."),
292 (read_u16, u16, "Reads an unsigned LEB128 u16."),
293 (read_u32, u32, "Reads an unsigned LEB128 u32."),
294 (read_u64, u64, "Reads an unsigned LEB128 u64."),
295 (read_u128, u128, "Reads an unsigned LEB128 u128."),
296 (read_usize, usize, "Reads an unsigned LEB128 usize."),
297 (read_i8, i8, "Reads a signed LEB128 i8."),
298 (read_i16, i16, "Reads a signed LEB128 i16."),
299 (read_i32, i32, "Reads a signed LEB128 i32."),
300 (read_i64, i64, "Reads a signed LEB128 i64."),
301 (read_i128, i128, "Reads a signed LEB128 i128."),
302 (read_isize, isize, "Reads a signed LEB128 isize."),
303 },
304);
305impl<R, P> Input for BufferedLeb128Reader<R, P>
306where
307 R: Input<Item = u8>,
308{
309 type Item = u8;
310
311 /// Reports that this adapter buffers input.
312 ///
313 /// # Returns
314 ///
315 /// Always returns `true`.
316 #[inline(always)]
317 fn is_buffered(&self) -> bool {
318 true
319 }
320
321 /// Reads up to `count` bytes into an indexed output range.
322 ///
323 /// # Parameters
324 ///
325 /// - `output`: Destination slice.
326 /// - `index`: First destination index.
327 /// - `count`: Maximum number of bytes to read.
328 ///
329 /// # Returns
330 ///
331 /// Returns the number of bytes read.
332 ///
333 /// # Errors
334 ///
335 /// Returns an error reported while reading the buffered input.
336 ///
337 /// # Safety
338 ///
339 /// `index..index + count` must be a valid range within `output`.
340 #[inline(always)]
341 unsafe fn read_unchecked(&mut self, output: &mut [u8], index: usize, count: usize) -> Result<usize> {
342 // SAFETY: The caller upholds the indexed destination range contract.
343 unsafe { self.input.read_unchecked(output, index, count) }
344 }
345}
346
347impl<R, P> Seekable for BufferedLeb128Reader<R, P>
348where
349 R: Input<Item = u8> + Seekable<Unit = u8>,
350{
351 type Unit = u8;
352
353 /// Seeks the wrapped reader and discards buffered bytes after success.
354 ///
355 /// # Parameters
356 ///
357 /// - `position`: Target seek position.
358 ///
359 /// # Returns
360 ///
361 /// Returns the new physical stream position.
362 ///
363 /// # Errors
364 ///
365 /// Returns the seek error reported by the wrapped reader and preserves
366 /// buffered bytes when seeking fails.
367 #[inline(always)]
368 fn seek_to(&mut self, position: SeekFrom) -> Result<u64> {
369 self.input.seek(position)
370 }
371}