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::{
14    NonStrict,
15    Strict,
16    ZigZagCodec,
17};
18use qubit_io::AsyncInput;
19
20use crate::util::read_leb128_payload_async;
21
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.
62pub trait AsyncZigZagReadExt: AsyncInput<Item = u8> {
63    zig_zag_read_method!(
64        "Asynchronously reads non-strict ZigZag `i8`.",
65        read_zig_zag_i8_non_strict_async,
66        i8,
67        NonStrict
68    );
69    zig_zag_read_method!(
70        "Asynchronously reads strict ZigZag `i8`.",
71        read_zig_zag_i8_strict_async,
72        i8,
73        Strict
74    );
75    zig_zag_read_method!(
76        "Asynchronously reads non-strict ZigZag `i16`.",
77        read_zig_zag_i16_non_strict_async,
78        i16,
79        NonStrict
80    );
81    zig_zag_read_method!(
82        "Asynchronously reads strict ZigZag `i16`.",
83        read_zig_zag_i16_strict_async,
84        i16,
85        Strict
86    );
87    zig_zag_read_method!(
88        "Asynchronously reads non-strict ZigZag `i32`.",
89        read_zig_zag_i32_non_strict_async,
90        i32,
91        NonStrict
92    );
93    zig_zag_read_method!(
94        "Asynchronously reads strict ZigZag `i32`.",
95        read_zig_zag_i32_strict_async,
96        i32,
97        Strict
98    );
99    zig_zag_read_method!(
100        "Asynchronously reads non-strict ZigZag `i64`.",
101        read_zig_zag_i64_non_strict_async,
102        i64,
103        NonStrict
104    );
105    zig_zag_read_method!(
106        "Asynchronously reads strict ZigZag `i64`.",
107        read_zig_zag_i64_strict_async,
108        i64,
109        Strict
110    );
111    zig_zag_read_method!(
112        "Asynchronously reads non-strict ZigZag `i128`.",
113        read_zig_zag_i128_non_strict_async,
114        i128,
115        NonStrict
116    );
117    zig_zag_read_method!(
118        "Asynchronously reads strict ZigZag `i128`.",
119        read_zig_zag_i128_strict_async,
120        i128,
121        Strict
122    );
123    zig_zag_read_method!(
124        "Asynchronously reads non-strict ZigZag `isize`.",
125        read_zig_zag_isize_non_strict_async,
126        isize,
127        NonStrict
128    );
129    zig_zag_read_method!(
130        "Asynchronously reads strict ZigZag `isize`.",
131        read_zig_zag_isize_strict_async,
132        isize,
133        Strict
134    );
135}
136
137impl<R> AsyncZigZagReadExt for R where R: AsyncInput<Item = u8> + ?Sized {}