Skip to main content

qubit_io_binary/ext/
async_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//! Asynchronous ZigZag reads.
9
10use core::future::Future;
11use std::io::Result;
12
13use qubit_codec_binary::NonStrict;
14use qubit_codec_binary::Strict;
15use qubit_codec_binary::ZigZagCodec;
16use qubit_io::AsyncInput;
17
18use crate::util::read_leb128_payload_async;
19
20/// Defines an asynchronous read method for one integer type and decoding
21/// policy.
22macro_rules! zig_zag_read_method {
23    ($doc:literal, $name:ident, $ty:ty, $policy:ty) => {
24        #[doc = $doc]
25        #[doc = ""]
26        #[doc = "# Returns"]
27        #[doc = ""]
28        #[doc = concat!("Returns the decoded `", stringify!($ty), "`.")]
29        #[doc = ""]
30        #[doc = "# Errors"]
31        #[doc = ""]
32        #[doc = "Returns an input error or an invalid-data error when the \
33                 payload is malformed or violates the selected policy."]
34        #[doc = ""]
35        #[doc = "# Cancellation safety"]
36        #[doc = ""]
37        #[doc = "This operation is not cancellation safe. Dropping the future \
38                 retains any bytes already consumed from the input."]
39        #[inline(always)]
40        fn $name(&mut self) -> impl Future<Output = Result<$ty>> + '_
41        where
42            Self: Unpin,
43        {
44            async move {
45                read_leb128_payload_async::<
46                    { ZigZagCodec::<$ty, $policy>::MAX_DECODE_UNITS_PER_VALUE },
47                    ZigZagCodec<$ty, $policy>,
48                    _,
49                >(self)
50                .await
51            }
52        }
53    };
54}
55
56/// Future-based ZigZag plus unsigned-LEB128 reads.
57///
58/// # Cancellation safety
59///
60/// These reads are not cancellation safe. Dropping a pending future leaves
61/// bytes already consumed from the input consumed.
62///
63/// # Examples
64///
65/// ```
66/// use qubit_io_binary::AsyncZigZagReadExt;
67///
68/// async fn read_i32<R>(input: &mut R) -> std::io::Result<i32>
69/// where
70///     R: AsyncZigZagReadExt + Unpin,
71/// {
72///     input.read_zig_zag_i32_strict_async().await
73/// }
74/// ```
75pub trait AsyncZigZagReadExt: AsyncInput<Item = u8> {
76    zig_zag_read_method!(
77        "Asynchronously reads non-strict ZigZag `i8`.",
78        read_zig_zag_i8_non_strict_async,
79        i8,
80        NonStrict
81    );
82    zig_zag_read_method!(
83        "Asynchronously reads strict ZigZag `i8`.",
84        read_zig_zag_i8_strict_async,
85        i8,
86        Strict
87    );
88    zig_zag_read_method!(
89        "Asynchronously reads non-strict ZigZag `i16`.",
90        read_zig_zag_i16_non_strict_async,
91        i16,
92        NonStrict
93    );
94    zig_zag_read_method!(
95        "Asynchronously reads strict ZigZag `i16`.",
96        read_zig_zag_i16_strict_async,
97        i16,
98        Strict
99    );
100    zig_zag_read_method!(
101        "Asynchronously reads non-strict ZigZag `i32`.",
102        read_zig_zag_i32_non_strict_async,
103        i32,
104        NonStrict
105    );
106    zig_zag_read_method!(
107        "Asynchronously reads strict ZigZag `i32`.",
108        read_zig_zag_i32_strict_async,
109        i32,
110        Strict
111    );
112    zig_zag_read_method!(
113        "Asynchronously reads non-strict ZigZag `i64`.",
114        read_zig_zag_i64_non_strict_async,
115        i64,
116        NonStrict
117    );
118    zig_zag_read_method!(
119        "Asynchronously reads strict ZigZag `i64`.",
120        read_zig_zag_i64_strict_async,
121        i64,
122        Strict
123    );
124    zig_zag_read_method!(
125        "Asynchronously reads non-strict ZigZag `i128`.",
126        read_zig_zag_i128_non_strict_async,
127        i128,
128        NonStrict
129    );
130    zig_zag_read_method!(
131        "Asynchronously reads strict ZigZag `i128`.",
132        read_zig_zag_i128_strict_async,
133        i128,
134        Strict
135    );
136    zig_zag_read_method!(
137        "Asynchronously reads non-strict ZigZag `isize`.",
138        read_zig_zag_isize_non_strict_async,
139        isize,
140        NonStrict
141    );
142    zig_zag_read_method!(
143        "Asynchronously reads strict ZigZag `isize`.",
144        read_zig_zag_isize_strict_async,
145        isize,
146        Strict
147    );
148}
149
150impl<R> AsyncZigZagReadExt for R where R: AsyncInput<Item = u8> + ?Sized {}