Trait Key

pub trait Key:
    Storable
    + Sized
    + Ord {
    const KEY_COMPARE: KeyCompare = KeyCompare::Default;
}

Database Table key metadata.

Purely compile time information for database table keys.

Comparison

There are 2 differences between Key and Storable:

1. Key must be Sized
2. Key represents a Storable type that defines a comparison function

The database backends will use Key::KEY_COMPARE to sort the keys within database tables.

Key::KEY_COMPARE is pre-implemented as a straight byte comparison.

This default is overridden for numbers, which use a number comparison. For example, u64 keys are sorted as {0, 1, 2 ... 999_998, 999_999, 1_000_000}.

If you would like to re-define this for number types, consider;

1. Creating a wrapper type around primitives like a struct SortU8(pub u8)
2. Implement Key on that wrapper
3. Define a custom Key::KEY_COMPARE

Provided Associated Constants

const KEY_COMPARE: KeyCompare = KeyCompare::Default

Compare 2 Key’s against each other.

Defaults for types

For arrays and vectors that contain a T: Storable, this does a straight byte comparison, not a comparison of the key’s value.

For StorableStr, this will use str::cmp, i.e. it is the same as the default behavior; it is a lexicographical comparison

For all primitive number types (u8, i128, etc), this will convert the bytes to the number using Storable::from_bytes, then do a number comparison.

Example

// Normal byte comparison.
let vec1 = StorableVec(vec![0, 1]);
let vec2 = StorableVec(vec![255, 0]);
assert_eq!(
    <StorableVec<u8> as Key>::KEY_COMPARE
        .as_compare_fn::<StorableVec<u8>>()(&vec1, &vec2),
    std::cmp::Ordering::Less,
);

// Integer comparison.
let byte1 = [0, 1]; // 256
let byte2 = [255, 0]; // 255
let num1 = u16::from_le_bytes(byte1);
let num2 = u16::from_le_bytes(byte2);
assert_eq!(num1, 256);
assert_eq!(num2, 255);
assert_eq!(
    //                                               256 > 255
    <u16 as Key>::KEY_COMPARE.as_compare_fn::<u16>()(&byte1, &byte2),
    std::cmp::Ordering::Greater,
);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl Key for i8

const KEY_COMPARE: KeyCompare = _

impl Key for i16

const KEY_COMPARE: KeyCompare = _

impl Key for i32

const KEY_COMPARE: KeyCompare = _

impl Key for i64

const KEY_COMPARE: KeyCompare = _

impl Key for i128

const KEY_COMPARE: KeyCompare = _

impl Key for isize

const KEY_COMPARE: KeyCompare = _

impl Key for u8

const KEY_COMPARE: KeyCompare = _

impl Key for u16

const KEY_COMPARE: KeyCompare = _

impl Key for u32

const KEY_COMPARE: KeyCompare = KeyCompare::Number

impl Key for u64

const KEY_COMPARE: KeyCompare = KeyCompare::Number

impl Key for u128

const KEY_COMPARE: KeyCompare = _

impl Key for ()

Ord comparison for misc types.

This is not a blanket implementation because it allows outer crates to define their own comparison functions for their T: Storable types.

impl Key for usize

const KEY_COMPARE: KeyCompare = KeyCompare::Number

impl<const N: usize, T> Key for [T; N]

where T: Key + Storable + Sized + Pod,

Ord comparison for arrays/vectors.

Implementors

impl Key for StorableBytes

impl Key for StorableStr

impl<T: Pod + Debug + Ord> Key for StorableVec<T>