Crate prefix_uvarint

This module implements a prefix-based variable length integer coding scheme.

Unlike an LEB128-style encoding scheme, this encoding uses a unary prefix code in the first byte of the value to indicate how many subsequent bytes need to be read followed by the big endian encoding of any remaining bytes. This improves coding speed compared to LEB128 by reducing the number of branches evaluated to code longer values, and allows those branches to be different to improve branch mis-prediction.

The PrefixVarInt trait is implemented for u64, u32, u16, i64, i32, and i16, with values closer to zero producing small output. Signed values are written using a Zigzag coding to ensure that small negative numbers produce small output.

PrefixVarInt includes methods to code values directly to/from byte slices, but traits are provided to extend bytes::{Buf,BufMut}, and to handle these values in `std::io::{Write,Read}.

use bytes::Buf;
use prefix_uvarint::{PrefixVarInt, PrefixVarIntBufMut, PrefixVarIntBuf};

// value_buf is the maximum size needed to encode a value.
let mut value_buf = [0u8; prefix_uvarint::MAX_LEN];
assert_eq!(167894u64.encode_prefix_varint(&mut value_buf), 3);
assert_eq!((167894u64, 3), u64::decode_prefix_varint(&value_buf).unwrap());

let mut buf_mut = vec![];
for v in (0..100).step_by(3) {
  buf_mut.put_prefix_varint(v);
}

// NB: need a mutable slice to use as PrefixVarIntBufMut
let mut buf = buf_mut.as_slice();
while let Ok(v) = buf.get_prefix_varint::<u64>() {
  assert_eq!(v % 3, 0);
}
assert!(!buf.has_remaining());

Structs

EncodedPrefixVarInt

A single encoded prefix varint value for with PrefixVarInt.to_prefix_varint_bytes().

PrefixVarIntIter

An iterator over PrefixVarInt values in a Buf.

Enums

DecodeError

Errors that may occur when decoding a PrefixVarInt.

Constants

MAX_LEN

Maximum number of bytes a single encoded uvarint will occupy.

Traits

PrefixVarInt

Trait for integer types that can be prefix varint coded.

PrefixVarIntBuf

Extension for buf::Buf to read any PrefixVarInt type.

PrefixVarIntBufMut

Extension for buf::BufMut to write any PrefixVarInt type.

Functions

read_prefix_varint

Read and decode a prefix varint value from r. Prefer read_prefix_varint_buf() wherever possible as it should be more efficient.

read_prefix_varint_buf

Read and decode a prefix varint value from r.

write_prefix_varint

Prefix varint code a value and write it to w. Returns the number of bytes written.