compressed_intvec/variable/
macros.rs

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

compressed_intvec/variable/
macros.rs
