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::ByteInput;
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.
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/// Decode a strict ZigZag value from a byte slice:
48///
49/// ```
50/// use std::io::Cursor;
51/// use qubit_io_binary::ZigZagReadExt;
52///
53/// let mut input = Cursor::new([0x53]);
54/// assert_eq!(input.read_zig_zag_i64_strict()?, -42);
55/// # Ok::<(), std::io::Error>(())
56/// ```
57pub trait ZigZagReadExt: ByteInput {
58    /// Reads a non-strict ZigZag `i8`.
59    ///
60    /// # Returns
61    ///
62    /// Returns the decoded integer.
63    ///
64    /// # Errors
65    ///
66    /// Returns an input error or an invalid-data error when the payload is
67    /// malformed or violates the selected canonicality policy.
68    #[inline(always)]
69    fn read_zig_zag_i8_non_strict(&mut self) -> Result<i8> {
70        read_zig_zag_value!(self, i8, NonStrict)
71    }
72
73    /// Reads a strict ZigZag `i8`.
74    ///
75    /// # Returns
76    ///
77    /// Returns the decoded integer.
78    ///
79    /// # Errors
80    ///
81    /// Returns an input error or an invalid-data error when the payload is
82    /// malformed or violates the selected canonicality policy.
83    #[inline(always)]
84    fn read_zig_zag_i8_strict(&mut self) -> Result<i8> {
85        read_zig_zag_value!(self, i8, Strict)
86    }
87
88    /// Reads a non-strict ZigZag `i16`.
89    ///
90    /// # Returns
91    ///
92    /// Returns the decoded integer.
93    ///
94    /// # Errors
95    ///
96    /// Returns an input error or an invalid-data error when the payload is
97    /// malformed or violates the selected canonicality policy.
98    #[inline(always)]
99    fn read_zig_zag_i16_non_strict(&mut self) -> Result<i16> {
100        read_zig_zag_value!(self, i16, NonStrict)
101    }
102
103    /// Reads a strict ZigZag `i16`.
104    ///
105    /// # Returns
106    ///
107    /// Returns the decoded integer.
108    ///
109    /// # Errors
110    ///
111    /// Returns an input error or an invalid-data error when the payload is
112    /// malformed or violates the selected canonicality policy.
113    #[inline(always)]
114    fn read_zig_zag_i16_strict(&mut self) -> Result<i16> {
115        read_zig_zag_value!(self, i16, Strict)
116    }
117
118    /// Reads a non-strict ZigZag `i32`.
119    ///
120    /// # Returns
121    ///
122    /// Returns the decoded integer.
123    ///
124    /// # Errors
125    ///
126    /// Returns an input error or an invalid-data error when the payload is
127    /// malformed or violates the selected canonicality policy.
128    #[inline(always)]
129    fn read_zig_zag_i32_non_strict(&mut self) -> Result<i32> {
130        read_zig_zag_value!(self, i32, NonStrict)
131    }
132
133    /// Reads a strict ZigZag `i32`.
134    ///
135    /// # Returns
136    ///
137    /// Returns the decoded integer.
138    ///
139    /// # Errors
140    ///
141    /// Returns an input error or an invalid-data error when the payload is
142    /// malformed or violates the selected canonicality policy.
143    #[inline(always)]
144    fn read_zig_zag_i32_strict(&mut self) -> Result<i32> {
145        read_zig_zag_value!(self, i32, Strict)
146    }
147
148    /// Reads a non-strict ZigZag `i64`.
149    ///
150    /// # Returns
151    ///
152    /// Returns the decoded integer.
153    ///
154    /// # Errors
155    ///
156    /// Returns an input error or an invalid-data error when the payload is
157    /// malformed or violates the selected canonicality policy.
158    #[inline(always)]
159    fn read_zig_zag_i64_non_strict(&mut self) -> Result<i64> {
160        read_zig_zag_value!(self, i64, NonStrict)
161    }
162
163    /// Reads a strict ZigZag `i64`.
164    ///
165    /// # Returns
166    ///
167    /// Returns the decoded integer.
168    ///
169    /// # Errors
170    ///
171    /// Returns an input error or an invalid-data error when the payload is
172    /// malformed or violates the selected canonicality policy.
173    #[inline(always)]
174    fn read_zig_zag_i64_strict(&mut self) -> Result<i64> {
175        read_zig_zag_value!(self, i64, Strict)
176    }
177
178    /// Reads a non-strict ZigZag `i128`.
179    ///
180    /// # Returns
181    ///
182    /// Returns the decoded integer.
183    ///
184    /// # Errors
185    ///
186    /// Returns an input error or an invalid-data error when the payload is
187    /// malformed or violates the selected canonicality policy.
188    #[inline(always)]
189    fn read_zig_zag_i128_non_strict(&mut self) -> Result<i128> {
190        read_zig_zag_value!(self, i128, NonStrict)
191    }
192
193    /// Reads a strict ZigZag `i128`.
194    ///
195    /// # Returns
196    ///
197    /// Returns the decoded integer.
198    ///
199    /// # Errors
200    ///
201    /// Returns an input error or an invalid-data error when the payload is
202    /// malformed or violates the selected canonicality policy.
203    #[inline(always)]
204    fn read_zig_zag_i128_strict(&mut self) -> Result<i128> {
205        read_zig_zag_value!(self, i128, Strict)
206    }
207
208    /// Reads a non-strict ZigZag `isize`.
209    ///
210    /// # Returns
211    ///
212    /// Returns the decoded integer.
213    ///
214    /// # Errors
215    ///
216    /// Returns an input error or an invalid-data error when the payload is
217    /// malformed or violates the selected canonicality policy.
218    #[inline(always)]
219    fn read_zig_zag_isize_non_strict(&mut self) -> Result<isize> {
220        read_zig_zag_value!(self, isize, NonStrict)
221    }
222
223    /// Reads a strict ZigZag `isize`.
224    ///
225    /// # Returns
226    ///
227    /// Returns the decoded integer.
228    ///
229    /// # Errors
230    ///
231    /// Returns an input error or an invalid-data error when the payload is
232    /// malformed or violates the selected canonicality policy.
233    #[inline(always)]
234    fn read_zig_zag_isize_strict(&mut self) -> Result<isize> {
235        read_zig_zag_value!(self, isize, Strict)
236    }
237}
238
239impl<R> ZigZagReadExt for R where R: ByteInput + ?Sized {}