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