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.