Trait cuprate_database::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,
);

Object Safety

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>