Supplant the Borrow bound on keys with a new AsKey trait

QP-trie keys are now bound by a new public trait, `AsKey`, rather than
`Borrow<[u8]>`. `AsKey` types must be borrowable both as a key slice,
much like in `Borrow`, and as `&[u8]`, which is used internally for
nybble operations.

The trait is implemented for common `std` types, roughly matching prior
coverage, and is amenable to further expansion.

Author: tapeinosyne

README.md

@@ -19,22 +19,21 @@ enable compilation of `Deserialize` and `Serialize` implementations for `Trie`.
 ## When should I use a QP-trie?
 
 QP-tries as implemented in this crate are key-value maps for any keys which
-implement `Borrow<[u8]>`. They are useful whenever you might need the same
-operations as a `HashMap` or `BTreeMap`, but need either a bit more speed
-(QP-tries are as fast or a bit faster as Rust's `HashMap` with the default
-hasher) and/or the ability to efficiently query for sets of elements with a
-given prefix.
+implement `qp_trie::AsKey`, a specialized trait akin to `Borrow<[u8]>`. They
+are useful whenever you might need the same operations as a `HashMap` or
+`BTreeMap`, but need either a bit more speed (QP-tries are as fast or a bit
+faster as Rust's `HashMap` with the default hasher) and/or the ability to
+efficiently query for sets of elements with a given prefix.
 
 QP-tries support efficient lookup/insertion/removal of individual elements,
 lookup/removal of sets of values with keys with a given prefix.
 
 ## Examples
 
-Keys can be any type which implements `Borrow<[u8]>`. Unfortunately at the
-moment, this rules out `String` - while this trie can still be used to store
-strings, it is necessary to manually convert them to byte slices and `Vec<u8>`s
-for use as keys. Here's a naive, simple example of putting 9 2-element byte arrays
-into the trie, and then removing all byte arrays which begin with "1":
+Keys can be any type which implements `AsKey`. Currently, this means strings as
+well as byte slices, vectors, and arrays. Here's a naive, simple example of
+putting 9 2-element byte arrays into the trie, and then removing all byte
+arrays which begin with "1":
 
 ```rust
 use qp_trie::Trie;
@@ -137,7 +136,7 @@ test bench_trie_insert       ... bench:  50,966,392 ns/iter (+/- 18,077,240)
 
 ## Future work
 
-- Add wrapper types for `String` and `str` to make working with strings easier.
+- Support more key types.
 
 ## License
 

src/key.rs

@@ -0,0 +1,203 @@
+use std::borrow::Borrow;
+
+
+/// A trait for keys in a QP-trie.
+///
+/// Implementing types must be borrowable in the form of both a key slice,
+/// such as `&str`, and the plain byte slice `&[u8]`. The former is used in
+/// the public `trie::Trie` API, while the latter is used internally to match
+/// and store keys.
+///
+/// Note that, as a consequence, keys which are not bytewise-equivalent will
+/// not associate to the same entry, even if they are equal under `Eq`.
+pub trait AsKey {
+    /// The borrowed form of this key type.
+    type Borrowed: ?Sized;
+
+    /// Borrow this key as a slice.
+    fn as_key_slice(&self) -> &Self::Borrowed;
+
+    /// View the key slice as a plain byte sequence.
+    fn as_key_bytes(key: &Self::Borrowed) -> &[u8];
+
+    /// Borrow the key as nybbles, in the form of a plain byte sequence.
+    #[inline]
+    fn as_nybbles(&self) -> &[u8] {
+        Self::as_key_bytes(self.as_key_slice())
+    }
+
+    /// View the nybbles of a value that can borrowed as a key slice.
+    #[inline]
+    fn nybbles_from<'a, Q: 'a + ?Sized>(val: &'a Q) -> &'a [u8]
+    where
+        Self::Borrowed: 'a,
+        Q: Borrow<Self::Borrowed>,
+    {
+        Self::as_key_bytes(val.borrow())
+    }
+}
+
+
+impl<'a> AsKey for &'a [u8] {
+    type Borrowed = [u8];
+
+    #[inline]
+    fn as_key_slice(&self) -> &Self::Borrowed {
+        self
+    }
+
+    #[inline]
+    fn as_key_bytes(key: &Self::Borrowed) -> &[u8] {
+        key
+    }
+}
+
+
+impl AsKey for Vec<u8> {
+    type Borrowed = [u8];
+
+    #[inline]
+    fn as_key_slice(&self) -> &Self::Borrowed {
+        self.as_slice()
+    }
+
+    #[inline]
+    fn as_key_bytes(key: &Self::Borrowed) -> &[u8] {
+        key
+    }
+}
+
+
+impl<'a> AsKey for &'a str {
+    type Borrowed = str;
+
+    #[inline]
+    fn as_key_slice(&self) -> &Self::Borrowed {
+        self
+    }
+
+    #[inline]
+    fn as_key_bytes(key: &Self::Borrowed) -> &[u8] {
+        key.as_bytes()
+    }
+}
+
+
+impl AsKey for String {
+    type Borrowed = str;
+
+    #[inline]
+    fn as_key_slice(&self) -> &Self::Borrowed {
+        self.as_str()
+    }
+
+    #[inline]
+    fn as_key_bytes(key: &Self::Borrowed) -> &[u8] {
+        key.as_bytes()
+    }
+}
+
+
+pub trait Break: AsKey {
+    fn empty<'a>() -> &'a <Self as AsKey>::Borrowed;
+    fn find_break(&self, loc: usize) -> &<Self as AsKey>::Borrowed;
+}
+
+
+impl<'b> Break for &'b [u8] {
+    #[inline]
+    fn empty<'a>() -> &'a [u8] {
+        <&'a [u8]>::default()
+    }
+
+    #[inline]
+    fn find_break(&self, loc: usize) -> &[u8] {
+        &self[..loc]
+    }
+}
+
+
+impl Break for Vec<u8> {
+    #[inline]
+    fn empty<'a>() -> &'a [u8] {
+        <&'a [u8]>::default()
+    }
+
+    #[inline]
+    fn find_break(&self, loc: usize) -> &[u8] {
+        &self[..loc]
+    }
+}
+
+
+impl<'b> Break for &'b str {
+    #[inline]
+    fn empty<'a>() -> &'a str {
+        <&'a str>::default()
+    }
+
+    #[inline]
+    fn find_break(&self, mut loc: usize) -> &str {
+        while !self.is_char_boundary(loc) {
+            loc -= 1;
+        }
+
+        &self[..loc]
+    }
+}
+
+
+impl Break for String {
+    #[inline]
+    fn empty<'a>() -> &'a str {
+        <&'a str>::default()
+    }
+
+    #[inline]
+    fn find_break(&self, mut loc: usize) -> &str {
+        while !self.is_char_boundary(loc) {
+            loc -= 1;
+        }
+
+        &self[..loc]
+    }
+}
+
+
+macro_rules! impl_for_arrays_of_size {
+    ($($length:expr)+) => { $(
+        impl AsKey for [u8; $length] {
+            type Borrowed = [u8];
+
+            #[inline]
+            fn as_key_slice(&self) -> &Self::Borrowed {
+                self.as_ref()
+            }
+
+            #[inline]
+            fn as_key_bytes(key: &Self::Borrowed) -> &[u8] {
+                key
+            }
+        }
+
+        impl Break for [u8; $length] {
+            #[inline]
+            fn empty<'a>() -> &'a [u8] {
+                <&'a [u8]>::default()
+            }
+
+            #[inline]
+            fn find_break(&self, loc: usize) -> &[u8] {
+                &self.as_key_slice()[..loc]
+            }
+        }
+    )+ }
+}
+
+
+impl_for_arrays_of_size! {
+    0  1  2  3  4  5  6  7  8  9
+    10 11 12 13 14 15 16 17 18 19
+    20 21 22 23 24 25 26 27 28 29
+    30 31 32
+}

src/serialization.rs

@@ -1,6 +1,6 @@
+use key::AsKey;
 use trie::Trie;
 
-use std::borrow::Borrow;
 use std::fmt;
 use std::marker::PhantomData;
 
@@ -9,7 +9,7 @@ use serde::ser::{Serialize, SerializeMap, Serializer};
 
 impl<K, V> Serialize for Trie<K, V>
 where
-    K: Serialize + Borrow<[u8]>,
+    K: Serialize + AsKey,
     V: Serialize,
 {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
@@ -38,7 +38,7 @@ impl<K, V> TrieVisitor<K, V> {
 
 impl<'de, K, V> Visitor<'de> for TrieVisitor<K, V>
 where
-    K: Deserialize<'de> + Borrow<[u8]>,
+    K: Deserialize<'de> + AsKey,
     V: Deserialize<'de>,
 {
     type Value = Trie<K, V>;
@@ -62,7 +62,7 @@ where
 
 impl<'de, K, V> Deserialize<'de> for Trie<K, V>
 where
-    K: Deserialize<'de> + Borrow<[u8]>,
+    K: Deserialize<'de> + AsKey,
     V: Deserialize<'de>,
 {
     fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>