Skip to main content

qubit_io_binary/ext/
zig_zag_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 ZigZag-encoded integers from streams.
10
11use std::io::Result;
12
13use qubit_codec_binary::NonStrict;
14use qubit_codec_binary::Strict;
15use qubit_codec_binary::ZigZagCodec;
16use qubit_io::Input;
17
18use crate::util::read_leb128_payload;
19
20/// Decodes one ZigZag value using the selected integer type and canonicality
21/// policy.
22macro_rules! read_zig_zag_value {
23    ($reader:expr, $ty:ty, $policy:ty) => {
24        read_leb128_payload::<
25            { ZigZagCodec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
26            ZigZagCodec<$ty, $policy>,
27            _,
28        >($reader)
29    };
30}
31
32/// Extension methods for reading ZigZag + unsigned LEB128 integers.
33///
34/// # Target-width integers
35///
36/// `isize` methods use the current Rust target's pointer width. Prefer
37/// fixed-width integer methods such as [`Self::read_zig_zag_i64_non_strict`]
38/// for persistent files and cross-platform protocols.
39/// Non-strict methods use the `_non_strict` suffix; canonical-only methods use
40/// the corresponding `_strict` suffix.
41pub trait ZigZagReadExt: Input<Item = u8> {
42    /// Reads a non-strict ZigZag `i8`.
43    ///
44    /// # Returns
45    ///
46    /// Returns the decoded integer.
47    ///
48    /// # Errors
49    ///
50    /// Returns an input error or an invalid-data error when the payload is
51    /// malformed or violates the selected canonicality policy.
52    #[inline(always)]
53    fn read_zig_zag_i8_non_strict(&mut self) -> Result<i8> {
54        read_zig_zag_value!(self, i8, NonStrict)
55    }
56
57    /// Reads a strict ZigZag `i8`.
58    ///
59    /// # Returns
60    ///
61    /// Returns the decoded integer.
62    ///
63    /// # Errors
64    ///
65    /// Returns an input error or an invalid-data error when the payload is
66    /// malformed or violates the selected canonicality policy.
67    #[inline(always)]
68    fn read_zig_zag_i8_strict(&mut self) -> Result<i8> {
69        read_zig_zag_value!(self, i8, Strict)
70    }
71
72    /// Reads a non-strict ZigZag `i16`.
73    ///
74    /// # Returns
75    ///
76    /// Returns the decoded integer.
77    ///
78    /// # Errors
79    ///
80    /// Returns an input error or an invalid-data error when the payload is
81    /// malformed or violates the selected canonicality policy.
82    #[inline(always)]
83    fn read_zig_zag_i16_non_strict(&mut self) -> Result<i16> {
84        read_zig_zag_value!(self, i16, NonStrict)
85    }
86
87    /// Reads a strict ZigZag `i16`.
88    ///
89    /// # Returns
90    ///
91    /// Returns the decoded integer.
92    ///
93    /// # Errors
94    ///
95    /// Returns an input error or an invalid-data error when the payload is
96    /// malformed or violates the selected canonicality policy.
97    #[inline(always)]
98    fn read_zig_zag_i16_strict(&mut self) -> Result<i16> {
99        read_zig_zag_value!(self, i16, Strict)
100    }
101
102    /// Reads a non-strict ZigZag `i32`.
103    ///
104    /// # Returns
105    ///
106    /// Returns the decoded integer.
107    ///
108    /// # Errors
109    ///
110    /// Returns an input error or an invalid-data error when the payload is
111    /// malformed or violates the selected canonicality policy.
112    #[inline(always)]
113    fn read_zig_zag_i32_non_strict(&mut self) -> Result<i32> {
114        read_zig_zag_value!(self, i32, NonStrict)
115    }
116
117    /// Reads a strict ZigZag `i32`.
118    ///
119    /// # Returns
120    ///
121    /// Returns the decoded integer.
122    ///
123    /// # Errors
124    ///
125    /// Returns an input error or an invalid-data error when the payload is
126    /// malformed or violates the selected canonicality policy.
127    #[inline(always)]
128    fn read_zig_zag_i32_strict(&mut self) -> Result<i32> {
129        read_zig_zag_value!(self, i32, Strict)
130    }
131
132    /// Reads a non-strict ZigZag `i64`.
133    ///
134    /// # Returns
135    ///
136    /// Returns the decoded integer.
137    ///
138    /// # Errors
139    ///
140    /// Returns an input error or an invalid-data error when the payload is
141    /// malformed or violates the selected canonicality policy.
142    #[inline(always)]
143    fn read_zig_zag_i64_non_strict(&mut self) -> Result<i64> {
144        read_zig_zag_value!(self, i64, NonStrict)
145    }
146
147    /// Reads a strict ZigZag `i64`.
148    ///
149    /// # Returns
150    ///
151    /// Returns the decoded integer.
152    ///
153    /// # Errors
154    ///
155    /// Returns an input error or an invalid-data error when the payload is
156    /// malformed or violates the selected canonicality policy.
157    #[inline(always)]
158    fn read_zig_zag_i64_strict(&mut self) -> Result<i64> {
159        read_zig_zag_value!(self, i64, Strict)
160    }
161
162    /// Reads a non-strict ZigZag `i128`.
163    ///
164    /// # Returns
165    ///
166    /// Returns the decoded integer.
167    ///
168    /// # Errors
169    ///
170    /// Returns an input error or an invalid-data error when the payload is
171    /// malformed or violates the selected canonicality policy.
172    #[inline(always)]
173    fn read_zig_zag_i128_non_strict(&mut self) -> Result<i128> {
174        read_zig_zag_value!(self, i128, NonStrict)
175    }
176
177    /// Reads a strict ZigZag `i128`.
178    ///
179    /// # Returns
180    ///
181    /// Returns the decoded integer.
182    ///
183    /// # Errors
184    ///
185    /// Returns an input error or an invalid-data error when the payload is
186    /// malformed or violates the selected canonicality policy.
187    #[inline(always)]
188    fn read_zig_zag_i128_strict(&mut self) -> Result<i128> {
189        read_zig_zag_value!(self, i128, Strict)
190    }
191
192    /// Reads a non-strict ZigZag `isize`.
193    ///
194    /// # Returns
195    ///
196    /// Returns the decoded integer.
197    ///
198    /// # Errors
199    ///
200    /// Returns an input error or an invalid-data error when the payload is
201    /// malformed or violates the selected canonicality policy.
202    #[inline(always)]
203    fn read_zig_zag_isize_non_strict(&mut self) -> Result<isize> {
204        read_zig_zag_value!(self, isize, NonStrict)
205    }
206
207    /// Reads a strict ZigZag `isize`.
208    ///
209    /// # Returns
210    ///
211    /// Returns the decoded integer.
212    ///
213    /// # Errors
214    ///
215    /// Returns an input error or an invalid-data error when the payload is
216    /// malformed or violates the selected canonicality policy.
217    #[inline(always)]
218    fn read_zig_zag_isize_strict(&mut self) -> Result<isize> {
219        read_zig_zag_value!(self, isize, Strict)
220    }
221}
222
223impl<R> ZigZagReadExt for R where R: Input<Item = u8> + ?Sized {}