Initial release

Cargo.toml

@@ -3,6 +3,51 @@ name = "copse"
 version = "0.1.0"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/eggyal/copse.git"
+description = "Direct ports of the standard library's B-Tree collections, but that sort according to a specified comparator rather than the `Ord` trait"
 edition = "2021"
+keywords = ["b-tree", "collections", "map", "set", "runtime"]
+categories = ["data-structures", "no-std"]
+
+[features]
+unstable = [
+    "allocator_api",
+    "bound_map",
+    "core_intrinsics",
+    "dropck_eyepatch",
+    "error_in_core",
+    "exact_size_is_empty",
+    "exclusive_range_pattern",
+    "extend_one",
+    "hasher_prefixfree_extras",
+    "map_try_insert",
+    "maybe_uninit_slice",
+    "new_uninit",
+    "rustc_attrs",
+    "slice_ptr_get",
+    "specialization",
+    "type_alias_impl_trait",
+]
+allocator_api = []
+bound_map = []
+core_intrinsics = []
+dropck_eyepatch = []
+error_in_core = []
+exact_size_is_empty = []
+exclusive_range_pattern = []
+extend_one = []
+hasher_prefixfree_extras = []
+map_try_insert = []
+maybe_uninit_slice = []
+new_uninit = []
+rustc_attrs = []
+slice_ptr_get = []
+specialization = []
+type_alias_impl_trait = []
+std = []
 
 [dependencies]
+cfg-if = "1.0.0"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

README.md

@@ -0,0 +1,83 @@
+Direct ports of the standard library's [`BTreeMap`][std::collections::BTreeMap] and
+[`BTreeSet`][std::collections::BTreeSet] collections, but which sort according to a specified
+[`Comparator`] rather than relying upon the [`Ord`] trait.
+
+This is primarily useful when the [`Comparator`] is not defined until runtime, and therefore
+cannot be provided as an [`Ord`] implementation for any type.
+
+# Lookup keys
+In the standard library's collections, certain lookups can be performed using a key of type
+`&Q` where the collection's storage key type `K` implements [`Borrow<Q>`]; for example, one
+can use `&str` keys to perform lookups into collections that store `String` keys.  This is
+possible because the [`Borrow`] trait stipulates that borrowed values must preserve [`Ord`]
+order.
+
+However, copse's collections do not use the [`Ord`] trait; instead, lookups can only ever
+be performed using the [`Comparator<T>`] supplied upon collection creation.  This comparator
+can only compare values of type `&T` for which it was defined, and hence such type must be
+reachable from any key type `&Q` used to perform lookups in the collection.  copse ensures
+this via its [`Sortable`] trait, which will typically be implemented by the stored key type
+`K`; its [`State`][Sortable::State] associated type then specifies the `T` in which
+comparisons will be performed, and values of type `&Q` can be used as lookup keys provided
+that `Q: Borrow<T>`.
+
+For example, a collection using a `Comparator<str>` comparator can store keys of type
+`String` because `String` implements `Sortable<State = str>`; moreover, lookups can be
+performed using keys of type `&str` because `str` implements `Borrow<str>` (due to the
+reflexive blanket implementation).
+
+Implementations of [`Sortable`] are provided for primitive and some common standard library
+types, but storing keys of other foreign types may require newtyping.
+
+# Function item types
+In addition to the type parameters familiar from the standard library collections, copse's
+collections are additionally parameterised by the type of the [`Comparator`].  If the
+comparator type is not explicitly named, it defaults to the type of the [`Ord::cmp`]
+function for `K::State`.  As noted in the documentation of the [`CmpFn`] type alias, this
+is only a zero-sized function item type if the unstable `type_alias_impl_trait` feature is
+enabled; otherwise it is a function pointer type, with ensuing size and indirect call
+implications.  Collections built using the zero-sized function item type can still be
+used in stable code, however; just not using the default type parameter.  For example:
+
+```rust
+let mut ord_map = BTreeMap::new(Ord::cmp);
+```
+
+However, naming this type carries the usual problems associated with anonymous types like
+closures; in certain situations you may be able to use `impl Comparator` for the type
+parameter, but in other situations (in stable code) the function pointer may be
+unavoidable.
+
+# Crate feature flags
+This crate defines a number of feature flags, none of which are enabled by default:
+
+* the `std` feature provides [`Sortable`] implementations for some libstd types
+  that are not available in libcore + liballoc, namely [`OsString`] and [`PathBuf`];
+
+* the `unstable` feature enables all other crate features, each of which enables the
+  like-named unstable compiler feature that is used by the standard library's collection
+  implementations (and which therefore require a nightly compiler)—most such behaviour
+  is polyfilled when the features are disabled, so they should rarely be required, but
+  they are nevertheless included to ease tracking of the stdlib implementations.
+
+  The most visible differences to library users will be:
+    * `allocator_api` enables the `new_in` methods for use of custom allocators;
+    * `specialization` adds the collection type name to some panic messages;
+    * `type_alias_impl_trait`, as mentioned above, ensures that the *default*
+       [`Comparator`] type parameter for the collections is the zero-sized function
+       item type of the `K::State::cmp` function.
+
+[std::collections::BTreeMap]: https://doc.rust-lang.org/std/collections/struct.BTreeMap.html
+[std::collections::BTreeSet]: https://doc.rust-lang.org/std/collections/struct.BTreeSet.html
+[`Ord`]: https://doc.rust-lang.org/std/cmp/trait.Ord.html
+[`Borrow`]: https://doc.rust-lang.org/std/borrow/trait.Borrow.html
+[`Borrow<Q>`]: https://doc.rust-lang.org/std/borrow/trait.Borrow.html
+[`Ord::cmp`]: https://doc.rust-lang.org/std/cmp/trait.Ord.html#tymethod.cmp
+[`OsString`]: https://doc.rust-lang.org/std/ffi/os_str/struct.OsString.html
+[`PathBuf`]: https://doc.rust-lang.org/std/path/struct.PathBuf.html
+
+[`CmpFn`]: https://docs.rs/copse/latest/copse/type.CmpFn.html
+[`Comparator`]: https://docs.rs/copse/latest/copse/trait.Comparator.html
+[`Comparator<T>`]: https://docs.rs/copse/latest/copse/trait.Comparator.html
+[`Sortable`]: https://docs.rs/copse/latest/copse/trait.Sortable.html
+[Sortable::State]: https://docs.rs/copse/latest/copse/trait.Sortable.html#associatedtype.State

src/btree/append.rs

@@ -1,6 +1,6 @@
 use super::merge_iter::MergeIterInner;
 use super::node::{self, Root};
-use core::alloc::Allocator;
+use crate::{Allocator, Comparator};
 use core::iter::FusedIterator;
 
 impl<K, V> Root<K, V> {
@@ -20,13 +20,13 @@ impl<K, V> Root<K, V> {
         left: I,
         right: I,
         length: &mut usize,
+        comparator: impl Comparator<(K, V)>,
         alloc: A,
     ) where
-        K: Ord,
         I: Iterator<Item = (K, V)> + FusedIterator,
     {
         // We prepare to merge `left` and `right` into a sorted sequence in linear time.
-        let iter = MergeIter(MergeIterInner::new(left, right));
+        let iter = MergeIter(MergeIterInner::new(left, right), comparator);
 
         // Meanwhile, we build a tree from the sorted sequence in linear time.
         self.bulk_push(iter, length, alloc)
@@ -91,17 +91,18 @@ impl<K, V> Root<K, V> {
 }
 
 // An iterator for merging two sorted sequences into one
-struct MergeIter<K, V, I: Iterator<Item = (K, V)>>(MergeIterInner<I>);
+struct MergeIter<K, V, C, I: Iterator<Item = (K, V)>>(MergeIterInner<I>, C);
 
-impl<K: Ord, V, I> Iterator for MergeIter<K, V, I>
+impl<K, V, C, I> Iterator for MergeIter<K, V, C, I>
 where
+    C: Comparator<(K, V)>,
     I: Iterator<Item = (K, V)> + FusedIterator,
 {
     type Item = (K, V);
 
     /// If two keys are equal, returns the key-value pair from the right source.
     fn next(&mut self) -> Option<(K, V)> {
-        let (a_next, b_next) = self.0.nexts(|a: &(K, V), b: &(K, V)| K::cmp(&a.0, &b.0));
+        let (a_next, b_next) = self.0.nexts(&self.1);
         b_next.or(a_next)
     }
 }

src/btree/borrow/tests.rs

@@ -3,7 +3,7 @@ use super::DormantMutRef;
 #[test]
 fn test_borrow() {
     let mut data = 1;
-    let mut stack = vec![];
+    let mut stack = alloc::vec![];
     let mut rr = &mut data;
     for factor in [2, 3, 7].iter() {
         let (r, dormant_r) = DormantMutRef::new(rr);

src/btree/dedup_sorted_iter.rs

@@ -1,32 +1,37 @@
 use core::iter::Peekable;
 
+use crate::{Sortable, Comparator};
+
 /// A iterator for deduping the key of a sorted iterator.
 /// When encountering the duplicated key, only the last key-value pair is yielded.
 ///
 /// Used by [`BTreeMap::bulk_build_from_sorted_iter`][1].
 ///
 /// [1]: crate::collections::BTreeMap::bulk_build_from_sorted_iter
-pub struct DedupSortedIter<K, V, I>
+pub struct DedupSortedIter<'a, K, V, C, I>
 where
     I: Iterator<Item = (K, V)>,
 {
     iter: Peekable<I>,
+    comparator: &'a C,
 }
 
-impl<K, V, I> DedupSortedIter<K, V, I>
+impl<'a, K, V, C, I> DedupSortedIter<'a, K, V, C, I>
 where
     I: Iterator<Item = (K, V)>,
 {
-    pub fn new(iter: I) -> Self {
+    pub fn new(iter: I, comparator: &'a C) -> Self {
         Self {
             iter: iter.peekable(),
+            comparator,
         }
     }
 }
 
-impl<K, V, I> Iterator for DedupSortedIter<K, V, I>
+impl<K, V, C, I> Iterator for DedupSortedIter<'_, K, V, C, I>
 where
-    K: Eq,
+    K: Sortable,
+    C: Comparator<K::State>,
     I: Iterator<Item = (K, V)>,
 {
     type Item = (K, V);
@@ -43,7 +48,7 @@ where
                 None => return Some(next),
             };
 
-            if next.0 != peeked.0 {
+            if self.comparator.cmp(next.0.borrow(), peeked.0.borrow()).is_ne() {
                 return Some(next);
             }
         }

src/btree/fix.rs

@@ -1,6 +1,6 @@
 use super::map::MIN_LEN;
 use super::node::{marker, ForceResult::*, Handle, LeftOrRight::*, NodeRef, Root};
-use core::alloc::Allocator;
+use crate::Allocator;
 
 impl<'a, K: 'a, V: 'a> NodeRef<marker::Mut<'a>, K, V, marker::LeafOrInternal> {
     /// Stocks up a possibly underfull node by merging with or stealing from a