qubit_io_binary/ext/leb128_read_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
9//! Extension methods for decoding LEB128 values from byte streams.
10
11use std::io::Result;
12
13use qubit_codec_binary::Leb128Codec;
14use qubit_codec_binary::NonStrict;
15use qubit_codec_binary::Strict;
16use qubit_io::ByteInput;
17
18use crate::util::read_leb128_payload;
19
20macro_rules! read_leb128_value {
21 ($reader:expr, $ty:ty, $policy:ty) => {
22 read_leb128_payload::<
23 { Leb128Codec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
24 Leb128Codec<$ty, $policy>,
25 _,
26 >($reader)
27 };
28}
29
30/// Extension methods for reading LEB128 integers from byte streams.
31///
32/// # Target-width integers
33///
34/// `usize` and `isize` methods use the current Rust target's pointer width.
35/// Prefer fixed-width integer methods such as
36/// [`Self::read_uleb_u64_non_strict`] or [`Self::read_sleb_i64_non_strict`] for
37/// persistent files and cross-platform protocols. Non-strict methods use the
38/// `_non_strict` suffix; canonical-only methods use the corresponding `_strict`
39/// suffix.
40/// A failed synchronous read may have consumed part of the current value.
41/// Do not blindly retry the same operation; resume only from a framing
42/// boundary or a trusted seek checkpoint.
43///
44/// # Examples
45///
46/// A non-strict read accepts an overlong encoding that the strict method
47/// rejects:
48///
49/// ```
50/// use std::io::Cursor;
51/// use std::io::ErrorKind;
52/// use qubit_io_binary::Leb128ReadExt;
53///
54/// let mut permissive = Cursor::new([0x80, 0x00]);
55/// assert_eq!(permissive.read_uleb_u64_non_strict()?, 0);
56/// let mut strict = Cursor::new([0x80, 0x00]);
57/// assert_eq!(strict.read_uleb_u64_strict().unwrap_err().kind(), ErrorKind::InvalidData);
58/// # Ok::<(), std::io::Error>(())
59/// ```
60pub trait Leb128ReadExt: ByteInput {
61 /// Reads a non-strict unsigned LEB128 `u8`.
62 ///
63 /// # Returns
64 ///
65 /// Returns the decoded integer.
66 ///
67 /// # Errors
68 ///
69 /// Returns an input error or an invalid-data error when the payload is
70 /// malformed or violates the selected canonicality policy.
71 #[inline(always)]
72 fn read_uleb_u8_non_strict(&mut self) -> Result<u8> {
73 read_leb128_value!(self, u8, NonStrict)
74 }
75
76 /// Reads a strict unsigned LEB128 `u8`.
77 ///
78 /// # Returns
79 ///
80 /// Returns the decoded integer.
81 ///
82 /// # Errors
83 ///
84 /// Returns an input error or an invalid-data error when the payload is
85 /// malformed or violates the selected canonicality policy.
86 #[inline(always)]
87 fn read_uleb_u8_strict(&mut self) -> Result<u8> {
88 read_leb128_value!(self, u8, Strict)
89 }
90
91 /// Reads a non-strict unsigned LEB128 `u16`.
92 ///
93 /// # Returns
94 ///
95 /// Returns the decoded integer.
96 ///
97 /// # Errors
98 ///
99 /// Returns an input error or an invalid-data error when the payload is
100 /// malformed or violates the selected canonicality policy.
101 #[inline(always)]
102 fn read_uleb_u16_non_strict(&mut self) -> Result<u16> {
103 read_leb128_value!(self, u16, NonStrict)
104 }
105
106 /// Reads a strict unsigned LEB128 `u16`.
107 ///
108 /// # Returns
109 ///
110 /// Returns the decoded integer.
111 ///
112 /// # Errors
113 ///
114 /// Returns an input error or an invalid-data error when the payload is
115 /// malformed or violates the selected canonicality policy.
116 #[inline(always)]
117 fn read_uleb_u16_strict(&mut self) -> Result<u16> {
118 read_leb128_value!(self, u16, Strict)
119 }
120
121 /// Reads a non-strict unsigned LEB128 `u32`.
122 ///
123 /// # Returns
124 ///
125 /// Returns the decoded integer.
126 ///
127 /// # Errors
128 ///
129 /// Returns an input error or an invalid-data error when the payload is
130 /// malformed or violates the selected canonicality policy.
131 #[inline(always)]
132 fn read_uleb_u32_non_strict(&mut self) -> Result<u32> {
133 read_leb128_value!(self, u32, NonStrict)
134 }
135
136 /// Reads a strict unsigned LEB128 `u32`.
137 ///
138 /// # Returns
139 ///
140 /// Returns the decoded integer.
141 ///
142 /// # Errors
143 ///
144 /// Returns an input error or an invalid-data error when the payload is
145 /// malformed or violates the selected canonicality policy.
146 #[inline(always)]
147 fn read_uleb_u32_strict(&mut self) -> Result<u32> {
148 read_leb128_value!(self, u32, Strict)
149 }
150
151 /// Reads a non-strict unsigned LEB128 `u64`.
152 ///
153 /// # Returns
154 ///
155 /// Returns the decoded integer.
156 ///
157 /// # Errors
158 ///
159 /// Returns an input error or an invalid-data error when the payload is
160 /// malformed or violates the selected canonicality policy.
161 #[inline(always)]
162 fn read_uleb_u64_non_strict(&mut self) -> Result<u64> {
163 read_leb128_value!(self, u64, NonStrict)
164 }
165
166 /// Reads a strict unsigned LEB128 `u64`.
167 ///
168 /// # Returns
169 ///
170 /// Returns the decoded integer.
171 ///
172 /// # Errors
173 ///
174 /// Returns an input error or an invalid-data error when the payload is
175 /// malformed or violates the selected canonicality policy.
176 #[inline(always)]
177 fn read_uleb_u64_strict(&mut self) -> Result<u64> {
178 read_leb128_value!(self, u64, Strict)
179 }
180
181 /// Reads a non-strict unsigned LEB128 `u128`.
182 ///
183 /// # Returns
184 ///
185 /// Returns the decoded integer.
186 ///
187 /// # Errors
188 ///
189 /// Returns an input error or an invalid-data error when the payload is
190 /// malformed or violates the selected canonicality policy.
191 #[inline(always)]
192 fn read_uleb_u128_non_strict(&mut self) -> Result<u128> {
193 read_leb128_value!(self, u128, NonStrict)
194 }
195
196 /// Reads a strict unsigned LEB128 `u128`.
197 ///
198 /// # Returns
199 ///
200 /// Returns the decoded integer.
201 ///
202 /// # Errors
203 ///
204 /// Returns an input error or an invalid-data error when the payload is
205 /// malformed or violates the selected canonicality policy.
206 #[inline(always)]
207 fn read_uleb_u128_strict(&mut self) -> Result<u128> {
208 read_leb128_value!(self, u128, Strict)
209 }
210
211 /// Reads a non-strict unsigned LEB128 `usize`.
212 ///
213 /// # Returns
214 ///
215 /// Returns the decoded integer.
216 ///
217 /// # Errors
218 ///
219 /// Returns an input error or an invalid-data error when the payload is
220 /// malformed or violates the selected canonicality policy.
221 #[inline(always)]
222 fn read_uleb_usize_non_strict(&mut self) -> Result<usize> {
223 read_leb128_value!(self, usize, NonStrict)
224 }
225
226 /// Reads a strict unsigned LEB128 `usize`.
227 ///
228 /// # Returns
229 ///
230 /// Returns the decoded integer.
231 ///
232 /// # Errors
233 ///
234 /// Returns an input error or an invalid-data error when the payload is
235 /// malformed or violates the selected canonicality policy.
236 #[inline(always)]
237 fn read_uleb_usize_strict(&mut self) -> Result<usize> {
238 read_leb128_value!(self, usize, Strict)
239 }
240
241 /// Reads a non-strict signed LEB128 `i8`.
242 ///
243 /// # Returns
244 ///
245 /// Returns the decoded integer.
246 ///
247 /// # Errors
248 ///
249 /// Returns an input error or an invalid-data error when the payload is
250 /// malformed or violates the selected canonicality policy.
251 #[inline(always)]
252 fn read_sleb_i8_non_strict(&mut self) -> Result<i8> {
253 read_leb128_value!(self, i8, NonStrict)
254 }
255
256 /// Reads a strict signed LEB128 `i8`.
257 ///
258 /// # Returns
259 ///
260 /// Returns the decoded integer.
261 ///
262 /// # Errors
263 ///
264 /// Returns an input error or an invalid-data error when the payload is
265 /// malformed or violates the selected canonicality policy.
266 #[inline(always)]
267 fn read_sleb_i8_strict(&mut self) -> Result<i8> {
268 read_leb128_value!(self, i8, Strict)
269 }
270
271 /// Reads a non-strict signed LEB128 `i16`.
272 ///
273 /// # Returns
274 ///
275 /// Returns the decoded integer.
276 ///
277 /// # Errors
278 ///
279 /// Returns an input error or an invalid-data error when the payload is
280 /// malformed or violates the selected canonicality policy.
281 #[inline(always)]
282 fn read_sleb_i16_non_strict(&mut self) -> Result<i16> {
283 read_leb128_value!(self, i16, NonStrict)
284 }
285
286 /// Reads a strict signed LEB128 `i16`.
287 ///
288 /// # Returns
289 ///
290 /// Returns the decoded integer.
291 ///
292 /// # Errors
293 ///
294 /// Returns an input error or an invalid-data error when the payload is
295 /// malformed or violates the selected canonicality policy.
296 #[inline(always)]
297 fn read_sleb_i16_strict(&mut self) -> Result<i16> {
298 read_leb128_value!(self, i16, Strict)
299 }
300
301 /// Reads a non-strict signed LEB128 `i32`.
302 ///
303 /// # Returns
304 ///
305 /// Returns the decoded integer.
306 ///
307 /// # Errors
308 ///
309 /// Returns an input error or an invalid-data error when the payload is
310 /// malformed or violates the selected canonicality policy.
311 #[inline(always)]
312 fn read_sleb_i32_non_strict(&mut self) -> Result<i32> {
313 read_leb128_value!(self, i32, NonStrict)
314 }
315
316 /// Reads a strict signed LEB128 `i32`.
317 ///
318 /// # Returns
319 ///
320 /// Returns the decoded integer.
321 ///
322 /// # Errors
323 ///
324 /// Returns an input error or an invalid-data error when the payload is
325 /// malformed or violates the selected canonicality policy.
326 #[inline(always)]
327 fn read_sleb_i32_strict(&mut self) -> Result<i32> {
328 read_leb128_value!(self, i32, Strict)
329 }
330
331 /// Reads a non-strict signed LEB128 `i64`.
332 ///
333 /// # Returns
334 ///
335 /// Returns the decoded integer.
336 ///
337 /// # Errors
338 ///
339 /// Returns an input error or an invalid-data error when the payload is
340 /// malformed or violates the selected canonicality policy.
341 #[inline(always)]
342 fn read_sleb_i64_non_strict(&mut self) -> Result<i64> {
343 read_leb128_value!(self, i64, NonStrict)
344 }
345
346 /// Reads a strict signed LEB128 `i64`.
347 ///
348 /// # Returns
349 ///
350 /// Returns the decoded integer.
351 ///
352 /// # Errors
353 ///
354 /// Returns an input error or an invalid-data error when the payload is
355 /// malformed or violates the selected canonicality policy.
356 #[inline(always)]
357 fn read_sleb_i64_strict(&mut self) -> Result<i64> {
358 read_leb128_value!(self, i64, Strict)
359 }
360
361 /// Reads a non-strict signed LEB128 `i128`.
362 ///
363 /// # Returns
364 ///
365 /// Returns the decoded integer.
366 ///
367 /// # Errors
368 ///
369 /// Returns an input error or an invalid-data error when the payload is
370 /// malformed or violates the selected canonicality policy.
371 #[inline(always)]
372 fn read_sleb_i128_non_strict(&mut self) -> Result<i128> {
373 read_leb128_value!(self, i128, NonStrict)
374 }
375
376 /// Reads a strict signed LEB128 `i128`.
377 ///
378 /// # Returns
379 ///
380 /// Returns the decoded integer.
381 ///
382 /// # Errors
383 ///
384 /// Returns an input error or an invalid-data error when the payload is
385 /// malformed or violates the selected canonicality policy.
386 #[inline(always)]
387 fn read_sleb_i128_strict(&mut self) -> Result<i128> {
388 read_leb128_value!(self, i128, Strict)
389 }
390
391 /// Reads a non-strict signed LEB128 `isize`.
392 ///
393 /// # Returns
394 ///
395 /// Returns the decoded integer.
396 ///
397 /// # Errors
398 ///
399 /// Returns an input error or an invalid-data error when the payload is
400 /// malformed or violates the selected canonicality policy.
401 #[inline(always)]
402 fn read_sleb_isize_non_strict(&mut self) -> Result<isize> {
403 read_leb128_value!(self, isize, NonStrict)
404 }
405
406 /// Reads a strict signed LEB128 `isize`.
407 ///
408 /// # Returns
409 ///
410 /// Returns the decoded integer.
411 ///
412 /// # Errors
413 ///
414 /// Returns an input error or an invalid-data error when the payload is
415 /// malformed or violates the selected canonicality policy.
416 #[inline(always)]
417 fn read_sleb_isize_strict(&mut self) -> Result<isize> {
418 read_leb128_value!(self, isize, Strict)
419 }
420}
421
422impl<R> Leb128ReadExt for R where R: ByteInput + ?Sized {}