compressed-intvec 0.6.0

Space-efficient integer vectors with fixed-width, variable-length, and sequence-oriented encodings.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

//! Convenience macros for creating an [`VarVec`] with a `vec!`-like syntax.
//!
//! These macros provide a familiar, ergonomic way to initialize a compressed
//! integer vector. They are shortcuts for the [`VarVec::builder`] and use a set
//! of reasonable defaults for compression and sampling rate.
//!
//! [`VarVec`]: crate::variable::VarVec
//! [`VarVec::builder`]: crate::variable::VarVec::builder

/// Creates a [`LEVarVec`] (a [`VarVec`] of [`u64`]s) containing the given elements.
///
/// `int_vec!` allows for concise initialization of a [`LEVarVec`], which is an
/// alias for `VarVec<u64, LE>`. It uses a set of reasonable defaults for its
/// build parameters:
///
/// - **Codec**: [`Codec::Auto`] is used to automatically select the
///   most space-efficient codec for the provided data.
/// - **Sampling Rate (`k`)**: A default value of `16` is used, offering a
///   good balance between random access speed and memory overhead.
///
/// # Note on Types
///
/// The macro infers the element type from the input. For explicit control over
/// parameters, use [`VarVec::builder`](crate::variable::VarVec::builder).
///
/// # Examples
///
/// Create an empty [`LEVarVec`]:
/// ```
/// # use compressed_intvec::int_vec;
/// # use compressed_intvec::prelude::LEVarVec;
/// let v: LEVarVec = int_vec![];
/// assert!(v.is_empty());
/// ```
///
/// Create a [`crate::variable::VarVec`] from a list of elements:
/// ```
/// # use compressed_intvec::int_vec;
///   let v = int_vec![100u32, 200, 300, 1024];
/// assert_eq!(v.len(), 4);
/// assert_eq!(v.get(1), Some(200));
/// ```
///
/// Create a [`crate::variable::VarVec`] with a repeated element:
/// ```
/// # use compressed_intvec::int_vec;
///   let v = int_vec![42u8; 100];
/// assert_eq!(v.len(), 100);
/// assert_eq!(v.get(50), Some(42));
/// ```
///
/// [`VarVec`]: crate::variable::VarVec
/// [`LEVarVec`]: crate::variable::LEVarVec
/// [`Codec::Auto`]: crate::variable::Codec::Auto
#[macro_export]
macro_rules! int_vec {
    () => {
        $crate::variable::VarVec::<u64, dsi_bitstream::prelude::LE>::builder().build(&[0u64; 0]).unwrap()
    };
    ($($elem:expr),* $(,)?) => {
        $crate::variable::VarVec::<_, dsi_bitstream::prelude::LE>::builder()
            .codec($crate::variable::Codec::Auto)
            .k(16)
            .build(&[$($elem),*])
            .unwrap()
    };
    ($elem:expr; $len:expr) => {
        {
            let mut v = ::std::vec::Vec::with_capacity($len);
            v.resize($len, $elem);
            $crate::variable::VarVec::<_, dsi_bitstream::prelude::LE>::builder()
                .codec($crate::variable::Codec::Auto)
                .k(16)
                .build(&v)
                .unwrap()
        }
    };
}

/// Creates a [`LESVarVec`] (a [`VarVec`] of [`i64`]s) containing the given elements.
///
/// `sint_vec!` allows for concise initialization of a [`LESVarVec`], which is an
/// alias for `VarVec<i64, LE>`. It uses a set of reasonable defaults:
///
/// - **Codec**: [`Codec::Auto`] is used to automatically select the
///   best codec based on the data's properties (via zig-zag encoding).
/// - **Sampling Rate (`k`)**: A default value of `16` is used.
///
/// # Note on Types
///
/// All input elements are automatically cast to [`i64`].
///
/// For more control over these parameters, or to use a different integer type,
/// please use the [`VarVec::builder`](crate::variable::VarVec::builder).
///
/// # Examples
///
/// Create an empty [`LESVarVec`]:
/// ```
/// # use compressed_intvec::sint_vec;
/// # use compressed_intvec::prelude::LESVarVec;
/// let v: LESVarVec = sint_vec![];
/// assert!(v.is_empty());
/// ```
///
/// Create an [`LESVarVec`] from a list of elements:
/// ```
/// # use compressed_intvec::sint_vec;
///   # use compressed_intvec::prelude::LESVarVec;
///   let v: LESVarVec = sint_vec![-100, 200, -300];
/// assert_eq!(v.len(), 3);
/// assert_eq!(v.get(2), Some(-300));
/// ```
///
/// Create an [`LESVarVec`] with a repeated element:
/// ```
/// # use compressed_intvec::sint_vec;
///   # use compressed_intvec::prelude::LESVarVec;
///   let v: LESVarVec = sint_vec![-42; 100];
/// assert_eq!(v.len(), 100);
/// assert_eq!(v.get(50), Some(-42));
/// ```
///
/// [`VarVec`]: crate::variable::VarVec
/// [`LESVarVec`]: crate::variable::LESVarVec
/// [`Codec::Auto`]: crate::variable::Codec::Auto
#[macro_export]
macro_rules! sint_vec {
    () => {
        $crate::variable::VarVec::<i64, dsi_bitstream::prelude::LE>::builder().build(&[0i64; 0]).unwrap()
    };
    ($($elem:expr),* $(,)?) => {
        $crate::variable::VarVec::<i64, dsi_bitstream::prelude::LE>::builder()
            .codec($crate::variable::Codec::Auto)
            .k(16)
            .build(&[$($elem as i64),*])
            .unwrap()
    };
    ($elem:expr; $len:expr) => {
        {
            let mut v = ::std::vec::Vec::with_capacity($len);
            v.resize($len, $elem as i64);
            $crate::variable::VarVec::<i64, dsi_bitstream::prelude::LE>::builder()
                .codec($crate::variable::Codec::Auto)
                .k(16)
                .build(&v)
                .unwrap()
        }
    };
}