Implement basic range iterator

**Description**
 - Implement the basic range iterator which will returns tuples of
   `(key, value)`.
 - Add the `TreeMap::range` function and a doctest example
 - Remove some dead code comments that were lying around

**Motivation**
This is the central feature that I wanted to implement, the ability
to query a sub-section of the `TreeMap` using the native key types.

This commit only implements the `Range` iterator, not the `RangeMut`
iterator so that the initial commit is devoid of `macro_rules` stuff.

This commit also includes some useful machinery that I think could
be applied to the `Prefix*` iterators, namely the
`find_terminating_node` function.

**Testing Done**
Full nightly test. I was not able to run a fuzzer because of some
difficulties setting it up.

Author: declanvk

src/collections/map.rs

@@ -11,7 +11,13 @@ use crate::{
     InsertSearchResultType::Exact,
     LeafNode, NoPrefixesBytes, NodePtr, OpaqueNodePtr,
 };
-use std::{borrow::Borrow, fmt::Debug, hash::Hash, mem::ManuallyDrop, ops::Index};
+use std::{
+    borrow::Borrow,
+    fmt::Debug,
+    hash::Hash,
+    mem::ManuallyDrop,
+    ops::{Index, RangeBounds},
+};
 
 mod entry;
 mod entry_ref;
@@ -897,6 +903,7 @@ impl<K, V, const PREFIX_LEN: usize> TreeMap<K, V, PREFIX_LEN> {
     {
         self.extend(other.drain_filter(|_, _| true))
     }
+    */
 
     /// Constructs a double-ended iterator over a sub-range of elements in the
     /// map.
@@ -906,33 +913,37 @@ impl<K, V, const PREFIX_LEN: usize> TreeMap<K, V, PREFIX_LEN> {
     /// (exclusive). The range may also be entered as `(Bound<T>, Bound<T>)`, so
     /// for example `range((Excluded(4), Included(10)))` will yield a
     /// left-exclusive, right-inclusive range from 4 to 10.
-    //
-    // # Examples
-    //
-    // ```rust,should_panic
-    // use blart::TreeMap;
-    // use std::ops::Bound::Included;
-    //
-    // let mut map = TreeMap::<u8, _>::new();
-    // map.try_insert(3, "a").unwrap();
-    // map.try_insert(5, "b").unwrap();
-    // map.try_insert(8, "c").unwrap();
-    //
-    // for (key, &value) in map.range((Included(&4), Included(&8))) {
-    //     println!("{key:?}: {value}");
-    // }
-    // assert_eq!(map.range(&4..).next(), Some((&5, &"b")));
-    // ```
-    #[allow(dead_code)]
-    pub(crate) fn range<Q, R>(&self, _range: R) -> iterators::Range<K, V>
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use blart::TreeMap;
+    /// use std::ops::Bound::Included;
+    ///
+    /// let mut map = TreeMap::<u8, _>::new();
+    /// map.try_insert(3, "a").unwrap();
+    /// map.try_insert(5, "b").unwrap();
+    /// map.try_insert(8, "c").unwrap();
+    ///
+    /// for (key, &value) in map.range((Included(&4), Included(&8))) {
+    ///     println!("{key:?}: {value}");
+    /// }
+    /// assert_eq!(map.range(&4..).next(), Some((&5, &"b")));
+    /// ```
+    pub fn range<Q, R>(&self, range: R) -> iterators::Range<K, V, PREFIX_LEN>
     where
         Q: AsBytes + ?Sized,
         K: Borrow<Q> + AsBytes,
         R: RangeBounds<Q>,
     {
-        todo!()
+        iterators::Range::new(
+            self,
+            range.start_bound().map(AsBytes::as_bytes),
+            range.end_bound().map(AsBytes::as_bytes),
+        )
     }
 
+    /*
     /// Constructs a mutable double-ended iterator over a sub-range of elements
     /// in the map.
     ///

src/collections/map/iterators.rs

@@ -10,126 +10,5 @@ pub use into_iter::*;
 mod fuzzy;
 pub use fuzzy::*;
 
-/*
-/// An iterator over a sub-range of entries in a `TreeMap`.
-///
-/// This `struct` is created by the [`range`] method on `TreeMap`. See its
-/// documentation for more.
-///
-/// [`range`]: TreeMap::range
-pub struct Range<'a, K, V, H>(PhantomData<(&'a K, &'a V)>);
-
-impl<'a, K, V, H> Iterator for Range<'a, K, V, H> {
-    type Item = (&'a K, &'a V);
-
-    fn next(&mut self) -> Option<Self::Item> {
-        todo!()
-    }
-
-    fn last(mut self) -> Option<Self::Item>
-    where
-        Self: Sized,
-    {
-        self.next_back()
-    }
-
-    fn min(mut self) -> Option<Self::Item>
-    where
-        Self: Sized,
-        Self::Item: Ord,
-    {
-        self.next()
-    }
-
-    fn max(mut self) -> Option<Self::Item>
-    where
-        Self: Sized,
-        Self::Item: Ord,
-    {
-        self.next_back()
-    }
-
-    #[cfg(feature = "nightly")]
-    fn is_sorted(self) -> bool
-    where
-        Self: Sized,
-        Self::Item: PartialOrd,
-    {
-        true
-    }
-}
-
-impl<'a, K, V, H> DoubleEndedIterator for Range<'a, K, V, H> {
-    fn next_back(&mut self) -> Option<Self::Item> {
-        todo!()
-    }
-}
-
-/// A mutable iterator over a sub-range of entries in a `TreeMap`.
-///
-/// This `struct` is created by the [`range_mut`] method on `TreeMap`. See
-/// its documentation for more.
-///
-/// [`range_mut`]: TreeMap::range_mut
-pub struct RangeMut<'a, K, V, H>(PhantomData<(&'a K, &'a mut V)>);
-
-impl<'a, K, V, H> Iterator for RangeMut<'a, K, V, H> {
-    type Item = (&'a K, &'a mut V);
-
-    fn next(&mut self) -> Option<Self::Item> {
-        todo!()
-    }
-
-    fn last(mut self) -> Option<Self::Item>
-    where
-        Self: Sized,
-    {
-        self.next_back()
-    }
-
-    fn min(mut self) -> Option<Self::Item>
-    where
-        Self: Sized,
-        Self::Item: Ord,
-    {
-        self.next()
-    }
-
-    fn max(mut self) -> Option<Self::Item>
-    where
-        Self: Sized,
-        Self::Item: Ord,
-    {
-        self.next_back()
-    }
-
-    #[cfg(feature = "nightly")]
-    fn is_sorted(self) -> bool
-    where
-        Self: Sized,
-        Self::Item: PartialOrd,
-    {
-        true
-    }
-}
-
-impl<'a, K, V, H> DoubleEndedIterator for RangeMut<'a, K, V, H> {
-    fn next_back(&mut self) -> Option<Self::Item> {
-        todo!()
-    }
-}
-*/
-
-// /// An iterator produced by calling [`drain_filter`] on `TreeMap`. See its
-// /// documentation for more.
-// ///
-// /// [`drain_filter`]: TreeMap::range_mut
-// pub struct ExtractIf<K, V, H>(PhantomData<(K, V)>);
-
-// impl<K, V, H> Iterator for ExtractIf<K, V, H> {
-//     type Item = (K, V);
-
-//     fn next(&mut self) -> Option<Self::Item> {
-//         todo!()
-//     }
-// }
+mod range;
+pub use range::*;