Direct ports of the standard library's BTreeMap, BTreeSet and BinaryHeap collections, but which sort according to a specified [TotalOrder] rather than relying upon the [Ord] trait.

This is primarily useful when the [TotalOrder] depends upon runtime state, 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 [TotalOrder] supplied upon collection creation. This total order can only compare values of its OrderedType associated type, and hence keys used for lookups must implement [LookupKey<O>] in order that the conversion can be performed.

Example

```rust // define a total order struct OrderByNthByte { n: usize, // runtime state }

impl TotalOrder for OrderByNthByte { type OrderedType = [u8]; fn cmp(&self, this: &[u8], that: &[u8]) -> Ordering { match (this.get(self.n), that.get(self.n)) { (Some(lhs), Some(rhs)) => lhs.cmp(rhs), (Some(), None) => Ordering::Greater, (None, Some()) => Ordering::Less, (None, None) => Ordering::Equal, } } }

// define lookup key types for collections sorted by our total order impl LookupKey for [u8] { fn key(&self) -> &[u8] { self } } impl LookupKey for str { fn key(&self) -> &[u8] { self.asbytes() } } impl LookupKey for String { fn key(&self) -> &[u8] { LookupKey::::key(self.asstr()) } }

// create a collection using our total order let mut set = BTreeSet::new(OrderByNthByte { n: 9 }); assert!(set.insert("abcdefghijklm".tostring())); assert!(!set.insert("xxxxxxxxxjxx".tostring())); assert!(set.contains("jjjjjjjjjj")); ```

Collection type parameters

In addition to the type parameters familiar from the standard library collections, copse's collections are additionally parameterised by the type of the [TotalOrder]. If the total order is not explicitly named, it defaults to the [OrdTotalOrder] for the storage key's DefaultComparisonKey, which yields behaviour analagous to the standard library collections (i.e. sorted by the Ord trait). If you find yourself using these items, then you should probably ditch copse for the standard library instead.

Crate feature flags

This crate defines a number of feature flags, none of which are enabled by default: