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 {}