[−][src]Crate vint64
vint64
: simple and efficient variablelength integer encoding.
About
This crate implements a variablelength encoding for 64bit little endian integers with a number of properties which make it superior in almost every way to other variablelength integer encodings like LEB128, SQLite "Varuints", or CBOR:
 Capable of expressing the full 64bit integer range with a maximum of 9bytes
 Total length of a
vint64
can be determined via the first byte alone  Provides the most compact encoding possible for every value in range
 No loops involved in decoding: just (unaligned) loads, masks, and shifts
 No complex branchheavy logic: decoding is CTZ + shifts and sanity checks
Integers serialized as unsigned vint64
are (up to) 64bit unsigned little
endian integers, with the [0, (2⁶⁴)−1]
range supported.
They have serialized lengths from 1byte to 9bytes depending on what value they're representing. The number of remaining bytes is stored in the leading byte, indicated by the number of trailing zeroes in that byte.
Below is an example of how prefix bits signal the length of the integer value which follows:
Prefix  Precision  Total Bytes 

xxxxxxx1  7 bits  1 byte 
xxxxxx10  14 bits  2 bytes 
xxxxx100  21 bits  3 bytes 
xxxx1000  28 bits  4 bytes 
xxx10000  35 bits  5 bytes 
xx100000  42 bits  6 bytes 
x1000000  49 bits  7 bytes 
10000000  56 bits  8 bytes 
00000000  64 bits  9 bytes 
All arithmetic needed to serialize and deserialize vint64
can be performed
using only 64bit integers. The case of the prefix byte being allzero is
a special case, and any remaining arithmetic is performed on the remaining
bytes.
Some precedent for this sort of encoding can be found in the Extensible Binary Meta Language (used by e.g. the Matroska media container format), however note that the specific type of "vint" used by that format still requires a loop to decode.
Usage
// Encode a 64bit integer as a vint64 let encoded = vint64::encode(42); assert_eq!(encoded.as_ref(), &[0x55]); // Get the length of a `vint64` from its first byte. // NOTE: this is inclusive of the first byte itself. let encoded_len = vint64::length_hint(encoded.as_ref()[0]); // Decode an encoded vint64 with trailing data let mut slice: &[u8] = &[0x55, 0xde, 0xad, 0xbe, 0xef]; let decoded = vint64::decode(&mut slice).unwrap(); assert_eq!(decoded, 42); assert_eq!(slice, &[0xde, 0xad, 0xbe, 0xef]); // Zigzag encoding can be used to encode signed vint64s. // Decode with `vint64::decode_signed`. let signed = vint64::encode_signed(42); assert_eq!(signed.as_ref(), &[0xa7]);
Structs
Error  Error type: indicates decoding failure 
VInt64 

Constants
MAX_BYTES  Maximum length of a 
Functions
decode  Decode a 
decode_signed  Decode a zigzagencoded 
encode  Encode an unsigned 64bit integer as 
encode_signed  Encode a signed integer as a zigzagencoded 
length_hint  Get the length of a 