Skip to main content

qubit_io_binary/ext/
async_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//! Asynchronous LEB128 reads.
9
10use core::future::Future;
11use std::io::Result;
12
13use qubit_codec_binary::Leb128Codec;
14use qubit_codec_binary::NonStrict;
15use qubit_codec_binary::Strict;
16use qubit_io::AsyncInput;
17
18use crate::util::read_leb128_payload_async;
19
20macro_rules! read_leb128_value_async {
21    ($reader:expr, $ty:ty, $policy:ty) => {
22        read_leb128_payload_async::<
23            { Leb128Codec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
24            Leb128Codec<$ty, $policy>,
25            _,
26        >($reader)
27        .await
28    };
29}
30
31macro_rules! leb128_read_method {
32    ($doc:literal, $name:ident, $ty:ty, $policy:ty) => {
33        #[doc = $doc]
34        #[doc = ""]
35        #[doc = "# Returns"]
36        #[doc = ""]
37        #[doc = concat!("Returns the decoded `", stringify!($ty), "`.")]
38        #[doc = ""]
39        #[doc = "# Errors"]
40        #[doc = ""]
41        #[doc = "Returns an input error or an invalid-data error when the \
42                 payload is malformed or violates the selected policy."]
43        #[doc = ""]
44        #[doc = "# Cancellation safety"]
45        #[doc = ""]
46        #[doc = "This operation is not cancellation safe. Dropping the future \
47                 retains any bytes already consumed from the input."]
48        #[inline(always)]
49        fn $name(&mut self) -> impl Future<Output = Result<$ty>> + '_
50        where
51            Self: Unpin,
52        {
53            async move { read_leb128_value_async!(self, $ty, $policy) }
54        }
55    };
56}
57
58/// Future-based LEB128 integer reads from runtime-neutral async inputs.
59///
60/// Target-width `usize` and `isize` formats remain platform dependent. Use
61/// fixed-width methods for persistent files and cross-platform protocols.
62///
63/// # Cancellation safety
64///
65/// These reads are not cancellation safe. Dropping a pending future leaves
66/// bytes already consumed from the input consumed.
67///
68/// # Examples
69///
70/// Define a generic async helper that reads a strict unsigned LEB128 value:
71///
72/// ```
73/// use qubit_io::AsyncInput;
74/// use qubit_io_binary::AsyncLeb128ReadExt;
75///
76/// async fn read_id<I>(input: &mut I) -> std::io::Result<u64>
77/// where
78///     I: AsyncInput<Item = u8> + Unpin,
79/// {
80///     input.read_uleb_u64_strict_async().await
81/// }
82/// ```
83pub trait AsyncLeb128ReadExt: AsyncInput<Item = u8> {
84    leb128_read_method!(
85        "Asynchronously reads a non-strict LEB128 `u8`.",
86        read_uleb_u8_non_strict_async,
87        u8,
88        NonStrict
89    );
90    leb128_read_method!(
91        "Asynchronously reads a strict LEB128 `u8`.",
92        read_uleb_u8_strict_async,
93        u8,
94        Strict
95    );
96    leb128_read_method!(
97        "Asynchronously reads a non-strict LEB128 `u16`.",
98        read_uleb_u16_non_strict_async,
99        u16,
100        NonStrict
101    );
102    leb128_read_method!(
103        "Asynchronously reads a strict LEB128 `u16`.",
104        read_uleb_u16_strict_async,
105        u16,
106        Strict
107    );
108    leb128_read_method!(
109        "Asynchronously reads a non-strict LEB128 `u32`.",
110        read_uleb_u32_non_strict_async,
111        u32,
112        NonStrict
113    );
114    leb128_read_method!(
115        "Asynchronously reads a strict LEB128 `u32`.",
116        read_uleb_u32_strict_async,
117        u32,
118        Strict
119    );
120    leb128_read_method!(
121        "Asynchronously reads a non-strict LEB128 `u64`.",
122        read_uleb_u64_non_strict_async,
123        u64,
124        NonStrict
125    );
126    leb128_read_method!(
127        "Asynchronously reads a strict LEB128 `u64`.",
128        read_uleb_u64_strict_async,
129        u64,
130        Strict
131    );
132    leb128_read_method!(
133        "Asynchronously reads a non-strict LEB128 `u128`.",
134        read_uleb_u128_non_strict_async,
135        u128,
136        NonStrict
137    );
138    leb128_read_method!(
139        "Asynchronously reads a strict LEB128 `u128`.",
140        read_uleb_u128_strict_async,
141        u128,
142        Strict
143    );
144    leb128_read_method!(
145        "Asynchronously reads a non-strict LEB128 `usize`.",
146        read_uleb_usize_non_strict_async,
147        usize,
148        NonStrict
149    );
150    leb128_read_method!(
151        "Asynchronously reads a strict LEB128 `usize`.",
152        read_uleb_usize_strict_async,
153        usize,
154        Strict
155    );
156    leb128_read_method!(
157        "Asynchronously reads a non-strict LEB128 `i8`.",
158        read_sleb_i8_non_strict_async,
159        i8,
160        NonStrict
161    );
162    leb128_read_method!(
163        "Asynchronously reads a strict LEB128 `i8`.",
164        read_sleb_i8_strict_async,
165        i8,
166        Strict
167    );
168    leb128_read_method!(
169        "Asynchronously reads a non-strict LEB128 `i16`.",
170        read_sleb_i16_non_strict_async,
171        i16,
172        NonStrict
173    );
174    leb128_read_method!(
175        "Asynchronously reads a strict LEB128 `i16`.",
176        read_sleb_i16_strict_async,
177        i16,
178        Strict
179    );
180    leb128_read_method!(
181        "Asynchronously reads a non-strict LEB128 `i32`.",
182        read_sleb_i32_non_strict_async,
183        i32,
184        NonStrict
185    );
186    leb128_read_method!(
187        "Asynchronously reads a strict LEB128 `i32`.",
188        read_sleb_i32_strict_async,
189        i32,
190        Strict
191    );
192    leb128_read_method!(
193        "Asynchronously reads a non-strict LEB128 `i64`.",
194        read_sleb_i64_non_strict_async,
195        i64,
196        NonStrict
197    );
198    leb128_read_method!(
199        "Asynchronously reads a strict LEB128 `i64`.",
200        read_sleb_i64_strict_async,
201        i64,
202        Strict
203    );
204    leb128_read_method!(
205        "Asynchronously reads a non-strict LEB128 `i128`.",
206        read_sleb_i128_non_strict_async,
207        i128,
208        NonStrict
209    );
210    leb128_read_method!(
211        "Asynchronously reads a strict LEB128 `i128`.",
212        read_sleb_i128_strict_async,
213        i128,
214        Strict
215    );
216    leb128_read_method!(
217        "Asynchronously reads a non-strict LEB128 `isize`.",
218        read_sleb_isize_non_strict_async,
219        isize,
220        NonStrict
221    );
222    leb128_read_method!(
223        "Asynchronously reads a strict LEB128 `isize`.",
224        read_sleb_isize_strict_async,
225        isize,
226        Strict
227    );
228}
229
230impl<R> AsyncLeb128ReadExt for R where R: AsyncInput<Item = u8> + ?Sized {}