compressed_intvec/variable/
macros.rs

1//! Convenience macros for creating an [`VarVec`] with a `vec!`-like syntax.
2//!
3//! These macros provide a familiar, ergonomic way to initialize a compressed
4//! integer vector. They are shortcuts for the [`VarVec::builder`] and use a set
5//! of reasonable defaults for compression and sampling rate.
6//!
7//! [`VarVec`]: crate::variable::VarVec
8//! [`VarVec::builder`]: crate::variable::VarVec::builder
9
10/// Creates a [`LEVarVec`] (a [`VarVec`] of [`u64`]s) containing the given elements.
11///
12/// `int_vec!` allows for concise initialization of a [`LEVarVec`], which is an
13/// alias for `VarVec<u64, LE>`. It uses a set of reasonable defaults for its
14/// build parameters:
15///
16/// - **Codec**: [`Codec::Auto`] is used to automatically select the
17///   most space-efficient codec for the provided data.
18/// - **Sampling Rate (`k`)**: A default value of `16` is used, offering a
19///   good balance between random access speed and memory overhead.
20///
21/// # Note on Types
22///
23/// The macro infers the element type from the input. For explicit control over
24/// parameters, use [`VarVec::builder`](crate::variable::VarVec::builder).
25///
26/// # Examples
27///
28/// Create an empty [`LEVarVec`]:
29/// ```
30/// # use compressed_intvec::int_vec;
31/// # use compressed_intvec::prelude::LEVarVec;
32/// let v: LEVarVec = int_vec![];
33/// assert!(v.is_empty());
34/// ```
35///
36/// Create a [`crate::variable::VarVec`] from a list of elements:
37/// ```
38/// # use compressed_intvec::int_vec;
39///   let v = int_vec![100u32, 200, 300, 1024];
40/// assert_eq!(v.len(), 4);
41/// assert_eq!(v.get(1), Some(200));
42/// ```
43///
44/// Create a [`crate::variable::VarVec`] with a repeated element:
45/// ```
46/// # use compressed_intvec::int_vec;
47///   let v = int_vec![42u8; 100];
48/// assert_eq!(v.len(), 100);
49/// assert_eq!(v.get(50), Some(42));
50/// ```
51///
52/// [`VarVec`]: crate::variable::VarVec
53/// [`LEVarVec`]: crate::variable::LEVarVec
54/// [`Codec::Auto`]: crate::variable::Codec::Auto
55#[macro_export]
56macro_rules! int_vec {
57    () => {
58        $crate::variable::VarVec::<u64, dsi_bitstream::prelude::LE>::builder().build(&[0u64; 0]).unwrap()
59    };
60    ($($elem:expr),* $(,)?) => {
61        $crate::variable::VarVec::<_, dsi_bitstream::prelude::LE>::builder()
62            .codec($crate::variable::Codec::Auto)
63            .k(16)
64            .build(&[$($elem),*])
65            .unwrap()
66    };
67    ($elem:expr; $len:expr) => {
68        {
69            let mut v = ::std::vec::Vec::with_capacity($len);
70            v.resize($len, $elem);
71            $crate::variable::VarVec::<_, dsi_bitstream::prelude::LE>::builder()
72                .codec($crate::variable::Codec::Auto)
73                .k(16)
74                .build(&v)
75                .unwrap()
76        }
77    };
78}
79
80/// Creates a [`LESVarVec`] (a [`VarVec`] of [`i64`]s) containing the given elements.
81///
82/// `sint_vec!` allows for concise initialization of a [`LESVarVec`], which is an
83/// alias for `VarVec<i64, LE>`. It uses a set of reasonable defaults:
84///
85/// - **Codec**: [`Codec::Auto`] is used to automatically select the
86///   best codec based on the data's properties (via zig-zag encoding).
87/// - **Sampling Rate (`k`)**: A default value of `16` is used.
88///
89/// # Note on Types
90///
91/// All input elements are automatically cast to [`i64`].
92///
93/// For more control over these parameters, or to use a different integer type,
94/// please use the [`VarVec::builder`](crate::variable::VarVec::builder).
95///
96/// # Examples
97///
98/// Create an empty [`LESVarVec`]:
99/// ```
100/// # use compressed_intvec::sint_vec;
101/// # use compressed_intvec::prelude::LESVarVec;
102/// let v: LESVarVec = sint_vec![];
103/// assert!(v.is_empty());
104/// ```
105///
106/// Create an [`LESVarVec`] from a list of elements:
107/// ```
108/// # use compressed_intvec::sint_vec;
109///   # use compressed_intvec::prelude::LESVarVec;
110///   let v: LESVarVec = sint_vec![-100, 200, -300];
111/// assert_eq!(v.len(), 3);
112/// assert_eq!(v.get(2), Some(-300));
113/// ```
114///
115/// Create an [`LESVarVec`] with a repeated element:
116/// ```
117/// # use compressed_intvec::sint_vec;
118///   # use compressed_intvec::prelude::LESVarVec;
119///   let v: LESVarVec = sint_vec![-42; 100];
120/// assert_eq!(v.len(), 100);
121/// assert_eq!(v.get(50), Some(-42));
122/// ```
123///
124/// [`VarVec`]: crate::variable::VarVec
125/// [`LESVarVec`]: crate::variable::LESVarVec
126/// [`Codec::Auto`]: crate::variable::Codec::Auto
127#[macro_export]
128macro_rules! sint_vec {
129    () => {
130        $crate::variable::VarVec::<i64, dsi_bitstream::prelude::LE>::builder().build(&[0i64; 0]).unwrap()
131    };
132    ($($elem:expr),* $(,)?) => {
133        $crate::variable::VarVec::<i64, dsi_bitstream::prelude::LE>::builder()
134            .codec($crate::variable::Codec::Auto)
135            .k(16)
136            .build(&[$($elem as i64),*])
137            .unwrap()
138    };
139    ($elem:expr; $len:expr) => {
140        {
141            let mut v = ::std::vec::Vec::with_capacity($len);
142            v.resize($len, $elem as i64);
143            $crate::variable::VarVec::<i64, dsi_bitstream::prelude::LE>::builder()
144                .codec($crate::variable::Codec::Auto)
145                .k(16)
146                .build(&v)
147                .unwrap()
148        }
149    };
150}
compressed_intvec/variable/macros.rs

compressed_intvec/variable/
macros.rs
