Struct bonsaidb_core::key::VarInt

pub struct VarInt<T>(pub T)
where
    T: VariableInteger;

A wrapper type for Rust’s built-in integer types that encodes with variable length and implements the Key trait.

This type supports all of Rust’s built-in integer types:

• u8
• u16
• u32
• u64
• u128
• usize
• i8
• i16
• i32
• i64
• i128
• isize

use bonsaidb_core::key::{Key, KeyEncoding, VarInt};

#[derive(Key, Default, Clone)]
struct UserId(u64);

// `UserId` type will always encode to 8 bytes, since u64 will encode
// using `u64::to_be_bytes`.
let default_key_len = UserId::default().as_ord_bytes().unwrap().len();
assert_eq!(default_key_len, 8);
let another_key_len = UserId(u64::MAX).as_ord_bytes().unwrap().len();
assert_eq!(another_key_len, 8);

#[derive(Key, Default, Clone)]
struct UserIdVariable(VarInt<u64>);

// However, `UserIdVariable` will be able to encode in as little as 1 byte,
// but can take up to 9 bytes if the entire u64 range is utilized.
let default_key_len = UserIdVariable::default().as_ord_bytes().unwrap().len();
assert_eq!(default_key_len, 1);
let another_key_len = UserIdVariable(VarInt(u64::MAX))
    .as_ord_bytes()
    .unwrap()
    .len();
assert_eq!(another_key_len, 9);

Why does this type exist?

The Key trait is implemented for all of Rust’s native integer types by using to_be_bytes()/from_be_bytes(). This provides some benefits: very fast encoding and decoding, and known-width encoding is faster to decode.

This type uses [ordered_varint] to encode the types using a variable length encoding that is still compatible with the Key trait. This allows a value of 0 to encode as a single byte while still preserving the correct sort order required by Key.

Additionally, this encoding format allows for upgrading the in-memory size transparently if the value range needs increases over time. This only works between types that are signed the same.

Behavior with Serde

This type implements serde::Serialize and serde::Deserialize transparently, as many serialization formats implement native variable integer encoding, and do not benefit from an ordered implementation.

Tuple Fields

0: T

Trait Implementations

impl<T> Add<T> for VarInt<T>

where T: Add<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the + operator.

fn add(self, rhs: T) -> Self::Output

Performs the + operation.

impl<T> BitAnd<T> for VarInt<T>

where T: BitAnd<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the & operator.

fn bitand(self, rhs: T) -> Self::Output

Performs the & operation.

impl<T> BitOr<T> for VarInt<T>

where T: BitOr<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the | operator.

fn bitor(self, rhs: T) -> Self::Output

Performs the | operation.

impl<T> BitXor<T> for VarInt<T>

where T: BitXor<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: T) -> Self::Output

Performs the ^ operation.

impl<T> Clone for VarInt<T>

where T: VariableInteger + Clone,

fn clone(&self) -> VarInt<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for VarInt<T>

where T: VariableInteger + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Default for VarInt<T>

where T: VariableInteger + Default,

fn default() -> VarInt<T>

Returns the “default value” for a type.

impl<T> Deref for VarInt<T>

where T: VariableInteger,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for VarInt<T>

where T: VariableInteger,

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de, T> Deserialize<'de> for VarInt<T>

where T: Deserialize<'de> + VariableInteger,

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Display for VarInt<T>

where T: Display + VariableInteger,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Div<T> for VarInt<T>

where T: Div<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the / operator.

fn div(self, rhs: T) -> Self::Output

Performs the / operation.

impl<T> From<T> for VarInt<T>

where T: VariableInteger,

fn from(value: T) -> Self

Converts to this type from the input type.

impl From<VarInt<i128>> for i128

fn from(value: VarInt<i128>) -> Self

Converts to this type from the input type.

impl From<VarInt<i16>> for i16

fn from(value: VarInt<i16>) -> Self

Converts to this type from the input type.

impl From<VarInt<i32>> for i32

fn from(value: VarInt<i32>) -> Self

Converts to this type from the input type.

impl From<VarInt<i64>> for i64

fn from(value: VarInt<i64>) -> Self

Converts to this type from the input type.

impl From<VarInt<i8>> for i8

fn from(value: VarInt<i8>) -> Self

Converts to this type from the input type.

impl From<VarInt<isize>> for isize

fn from(value: VarInt<isize>) -> Self

Converts to this type from the input type.

impl From<VarInt<u128>> for u128

fn from(value: VarInt<u128>) -> Self

Converts to this type from the input type.

impl From<VarInt<u16>> for u16

fn from(value: VarInt<u16>) -> Self

Converts to this type from the input type.

impl From<VarInt<u32>> for u32

fn from(value: VarInt<u32>) -> Self

Converts to this type from the input type.

impl From<VarInt<u64>> for u64

fn from(value: VarInt<u64>) -> Self

Converts to this type from the input type.

impl From<VarInt<u8>> for u8

fn from(value: VarInt<u8>) -> Self

Converts to this type from the input type.

impl From<VarInt<usize>> for usize

fn from(value: VarInt<usize>) -> Self

Converts to this type from the input type.

impl<T> Hash for VarInt<T>

where T: VariableInteger + Hash,

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'k, T> Key<'k> for VarInt<T>

where T: VariableInteger,

const CAN_OWN_BYTES: bool = false

If true, this type can benefit from an owned Vec<u8>. This flag is used as a hint of whether to attempt to do memcpy operations in some decoding operations to avoid extra allocations.

fn from_ord_bytes<'e>(bytes: ByteSource<'k, 'e>) -> Result<Self, Self::Error>

Deserialize a sequence of bytes previously encoded with KeyEncoding::as_ord_bytes.

fn first_value() -> Result<Self, NextValueError>

Return the first value in sequence for this type. Not all types implement this.

fn next_value(&self) -> Result<Self, NextValueError>

Return the next value in sequence for this type. Not all types implement this. Instead of wrapping/overflowing, None should be returned.

impl<T> KeyEncoding for VarInt<T>

where T: VariableInteger,

type Error = Error

The error type that can be produced by either serialization or deserialization.

const LENGTH: Option<usize> = None

The size of the key, if constant. If this type doesn’t produce the same number of bytes for each value, this should be None.

fn describe<Visitor>(visitor: &mut Visitor)

where Visitor: KeyVisitor,

Describes this type by invoking functions on visitor describing the key being encoded.

fn as_ord_bytes(&self) -> Result<Cow<'_, [u8]>, Self::Error>

Convert self into a Cow<'_, [u8]> containing bytes that are able to be compared via memcmp in a way that is comptaible with its own Ord implementation.

impl<T> Mul<T> for VarInt<T>

where T: Mul<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the * operator.

fn mul(self, rhs: T) -> Self::Output

Performs the * operation.

impl<T> Not for VarInt<T>

where T: Not<Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl<T> Ord for VarInt<T>

where T: VariableInteger + Ord,

fn cmp(&self, other: &VarInt<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<T> PartialEq for VarInt<T>

where T: VariableInteger + PartialEq,

fn eq(&self, other: &VarInt<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for VarInt<T>

where T: VariableInteger + PartialOrd,

fn partial_cmp(&self, other: &VarInt<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Rem<T> for VarInt<T>

where T: Rem<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the % operator.

fn rem(self, rhs: T) -> Self::Output

Performs the % operation.

impl<T> Serialize for VarInt<T>

where T: Serialize + VariableInteger,

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> Shl<T> for VarInt<T>

where T: Shl<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the << operator.

fn shl(self, rhs: T) -> Self::Output

Performs the << operation.

impl<T> Shr<T> for VarInt<T>

where T: Shr<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the >> operator.

fn shr(self, rhs: T) -> Self::Output

Performs the >> operation.

impl<T> Sub<T> for VarInt<T>

where T: Sub<T, Output = T> + VariableInteger,

type Output = VarInt<T>

The resulting type after applying the - operator.

fn sub(self, rhs: T) -> Self::Output

Performs the - operation.

impl<T> Copy for VarInt<T>

where T: VariableInteger + Copy,

impl<T> Eq for VarInt<T>

where T: VariableInteger + Eq,

impl<T> StructuralEq for VarInt<T>

where T: VariableInteger,

impl<T> StructuralPartialEq for VarInt<T>

where T: VariableInteger,