Introduce Wavelet Matrix (#10)

* implemented wavelet matrix
* rank and select functions
* quantile functions and convenience functions for special quantiles
* added the ability to generate secondary iterators to the vector-macro call
* several iterators over the wavelet tree
* predecessor and successor functions
* prefix counting constructor
* documentation and test cases

src/bit_vec/fast_rs_vec/mod.rs

@@ -90,8 +90,8 @@ pub struct RsVec {
     blocks: Vec<BlockDescriptor>,
     super_blocks: Vec<SuperBlockDescriptor>,
     select_blocks: Vec<SelectSuperBlockDescriptor>,
-    rank0: usize,
-    rank1: usize,
+    pub(crate) rank0: usize,
+    pub(crate) rank1: usize,
 }
 
 impl RsVec {

src/lib.rs

@@ -59,11 +59,12 @@
 //! - `serde` (disabled by default): Enables serialization and deserialization support for all
 //!   data structures in this crate using the `serde` crate.
 
-pub use crate::elias_fano::EliasFanoVec;
 pub use bit_vec::fast_rs_vec::RsVec;
 pub use bit_vec::BitVec;
+pub use elias_fano::EliasFanoVec;
 pub use rmq::binary_rmq::BinaryRmq;
 pub use rmq::fast_rmq::FastRmq;
+pub use wavelet::WaveletMatrix;
 
 pub mod bit_vec;
 
@@ -73,4 +74,7 @@ pub mod elias_fano;
 #[forbid(unsafe_code)]
 pub mod rmq;
 
+#[forbid(unsafe_code)]
+mod wavelet;
+
 pub(crate) mod util;

src/util/general_iter.rs

@@ -166,7 +166,7 @@ macro_rules! gen_vector_iter_impl {
 /// It expects that the iterator type has a constructor named `new` that takes only a
 /// reference to / value of the data structure and returns an iterator.
 ///
-/// This macro is used by all vector types including EliasFanoVec
+/// This macro is used by all vector types including `EliasFanoVec`
 ///
 /// The macro generates the following items:
 /// - An `impl` block for `VecType` that implements `IntoIterator<Item = u64>` for `VecType`.
@@ -222,19 +222,23 @@ macro_rules! impl_into_iterator_impls {
 /// If not provided, it defaults to `get_unchecked` and `get` as the function names and `u64` as
 /// the return type.
 ///
+/// If the optional parameters are supplied, it also accepts an optional token "special", which
+/// generates the iterators but not the `iter` and `into_iter` functions.
+/// This way the macro can be used to generate specialized iterators that are constructed
+/// differently.
+///
 /// The macro expects the vector type to implement a function called `len()`.
 ///
-/// This macro is not used for the EliasFanoVec, because that exploits internal structure for faster
-/// iteration, while this macro just calls get() repeatedly
+/// This macro is not used for the `EliasFanoVec`, because that exploits internal structure for faster
+/// iteration, while this macro just calls `get()` repeatedly
 ///
 /// The macro generates the following items:
 /// - A struct named `VecTypeIter` that implements `Iterator<Item = u64>` for `VecType`.
 /// - A struct named `VecTypeRefIter` that implements `Iterator<Item = u64>` for `&VecType` and `$mut VecType`.
 macro_rules! impl_vector_iterator {
     ($type:ty, $own:ident, $bor:ident) => { impl_vector_iterator! { $type, $own, $bor, get_unchecked, get, u64 } };
-    ($type:ty, $own:ident, $bor:ident, $get_unchecked:ident, $get:ident, $return_type:ty) => {
+    ($type:ty, $own:ident, $bor:ident, $get_unchecked:ident, $get:ident, $return_type:ty, special) => {
         #[doc = concat!("An owning iterator for `", stringify!($type), "`.")]
-        #[doc = concat!("This struct is created by the `into_iter` trait implementation of `", stringify!($type), "`.")]
         #[derive(Clone, Debug)]
         pub struct $own {
             vec: $type,
@@ -244,16 +248,7 @@ macro_rules! impl_vector_iterator {
             back_index: Option<usize>,
         }
 
-        impl $type {
-            #[doc = concat!("Returns an iterator over the elements of `", stringify!($type), "`.")]
-            #[must_use]
-            pub fn iter(&self) -> $bor<'_> {
-                $bor::new(self)
-            }
-        }
-
         #[doc = concat!("A borrowing iterator for `", stringify!($type), "`.")]
-        #[doc = concat!("This struct is created by the `iter` method of `", stringify!($type), "`.")]
         #[derive(Clone, Debug)]
         pub struct $bor<'a> {
             vec: &'a $type,
@@ -263,11 +258,23 @@ macro_rules! impl_vector_iterator {
             back_index: Option<usize>,
         }
 
-        crate::util::impl_into_iterator_impls!($type, $own, $bor, $return_type);
-
         crate::util::gen_vector_iter_impl!($own, $type, $return_type, $get_unchecked, $get);
 
         crate::util::gen_vector_iter_impl!('a, $bor, $type, $return_type, $get_unchecked, $get);
+    };
+    ($type:ty, $own:ident, $bor:ident, $get_unchecked:ident, $get:ident, $return_type:ty) => {
+        impl_vector_iterator! { $type, $own, $bor, $get_unchecked, $get, $return_type, special }
+
+        impl $type {
+            #[doc = concat!("Returns an iterator over the elements of `", stringify!($type), "`.")]
+            #[doc = concat!("The iterator returns `", stringify!($return_type), "` elements.")]
+            #[must_use]
+            pub fn iter(&self) -> $bor<'_> {
+                $bor::new(self)
+            }
+        }
+
+        crate::util::impl_into_iterator_impls!($type, $own, $bor, $return_type);
     }
 }