Implement Map wrapper over raw node operations

[declanvk]

Problem

• Currently all the tree operations are unsafe free functions which operate on the OpaqueNotePtr<V> type.
• This is an issue because these is not a very friendly interface and requires using unsafe blocks and fulfilling some of those requirements.
• I want a drop in replacement for the BTreeMap and BTreeSet types from the standard library.

Solution Sketch

• Copy over the APIs from BTreeMap and BTreeSet and update the types and parameters.

Standard Library BTreeMap API Outline

impl<K, V> BTreeMap<K, V> {
    pub fn new() -> BTreeMap<K, V>;

    pub fn clear(&mut self);

    pub fn get<Q>(&self, key: &Q) -> Option<&V> where
        K: Borrow<Q> + Ord,
        Q: Ord + ?Sized;

    pub fn get_key_value<Q>(&self, k: &Q) -> Option<(&K, &V)> where
        K: Borrow<Q> + Ord,
        Q: Ord + ?Sized; 

    pub fn first_key_value(&self) -> Option<(&K, &V)> where
        K: Ord;

    pub fn first_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>> where
        K: Ord;

    pub fn pop_first(&mut self) -> Option<(K, V)> where
        K: Ord;

    pub fn last_key_value(&self) -> Option<(&K, &V)> where
        K: Ord;

    pub fn last_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>> where
        K: Ord;

    pub fn pop_last(&mut self) -> Option<(K, V)> where
        K: Ord;

    pub fn contains_key<Q>(&self, key: &Q) -> bool where
        K: Borrow<Q> + Ord,
        Q: Ord + ?Sized;

    pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V> where
        K: Borrow<Q> + Ord,
        Q: Ord + ?Sized;

    pub fn insert(&mut self, key: K, value: V) -> Option<V> where
        K: Ord;

    pub fn try_insert(
        &mut self,
        key: K,
        value: V
    ) -> Result<&mut V, OccupiedError<'_, K, V>> where
        K: Ord;

    pub fn remove<Q>(&mut self, key: &Q) -> Option<V> where
        K: Borrow<Q> + Ord,
        Q: Ord + ?Sized;

    pub fn remove_entry<Q>(&mut self, key: &Q) -> Option<(K, V)> where
        K: Borrow<Q> + Ord,
        Q: Ord + ?Sized;

    pub fn retain<F>(&mut self, f: F) where
        K: Ord,
        F: FnMut(&K, &mut V) -> bool;

    pub fn append(&mut self, other: &mut BTreeMap<K, V>) where
        K: Ord;

    pub fn range<T, R>(&self, range: R) -> Range<'_, K, V> where
        T: Ord + ?Sized,
        K: Borrow<T> + Ord,
        R: RangeBounds<T>;

    pub fn range_mut<T, R>(&mut self, range: R) -> RangeMut<'_, K, V> where
        T: Ord + ?Sized,
        K: Borrow<T> + Ord,
        R: RangeBounds<T>; 

    pub fn entry(&mut self, key: K) -> Entry<'_, K, V> where
        K: Ord;

    pub fn split_off<Q>(&mut self, key: &Q) -> BTreeMap<K, V> where
        Q: Ord + ?Sized,
        K: Borrow<Q> + Ord;

    pub fn drain_filter<F>(&mut self, pred: F) -> DrainFilter<'_, K, V, F> where
        K: Ord,
        F: FnMut(&K, &mut V) -> bool;

    pub fn into_keys(self) -> IntoKeys<K, V>;


    pub fn into_values(self) -> IntoValues<K, V>;

    pub fn iter(&self) -> Iter<'_, K, V>;

    pub fn iter_mut(&mut self) -> IterMut<'_, K, V>;

    pub fn keys(&self) -> Keys<'_, K, V>;

    pub fn values(&self) -> Values<'_, K, V>;

    pub fn values_mut(&mut self) -> ValuesMut<'_, K, V>;

    pub fn len(&self) -> usize;

    pub fn is_empty(&self) -> bool;
}

[declanvk]

Needs examples in doc comments for all APIs.

[declanvk]

Remaining work after 543d273 was merged:

• Add examples to all doc comments
• Add equivalent TreeSet implementation, copying from BTreeSet API outline
• Implement range/range_mut iterators
• Implement drain_filter
• Implement split_off
• Implement append

[declanvk]

Created issues for remaining work #24 and #25, closing.

Most of code was done in 543d273