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 String: Borrow<str> and 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] of type O that was supplied upon collection creation. This total order can only compare values of its [OrderedType] associated type, and hence keys used for lookups must implement [SortableBy<O>] in order that the sort key can be extracted.

Example

```rust use copse::{BTreeSet, SortableBy, TotalOrder}; use std::cmp::Ordering;

// 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 { this.get(self.n).cmp(&that.get(self.n)) } }

// define lookup key types for collections sorted by our total order impl SortableBy for [u8] { fn sortkey(&self) -> &[u8] { self } } impl SortableBy for str { fn sortkey(&self) -> &[u8] { self.asbytes() } } impl SortableBy for String { fn sortkey(&self) -> &[u8] { SortableBy::::sortkey(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 [OrdKeyType], which yields behaviour analagous to the standard library collections (i.e. sorted by the [Ord] trait); explicitly using these items indicates that you could (and probably should) 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: