Crate vlen 

vlen: High-performance variable-length numeric encoding

vlen is an enhanced version of the original vu128 variable-length numeric encoding. Numeric types up to 128 bits are supported (integers and floating-point), with smaller values being encoded using fewer bytes. Every integer width shares one wire format, so a value encoded as one type decodes as any wider type.

The compression matches the widely used VLQ and LEB128 encodings for values below 2^28 (and caps at 9 bytes for u64, where LEB128 needs up to 10), and it decodes faster on modern pipelined architectures because the encoded length is announced by the first byte instead of continuation bits spread across the value.

Quick Start

use vlen::{Decode, Encode};

let mut buf = [0u8; 5];
let value = 12345u32;

let len = value.encode(&mut buf)?;
assert_eq!(len, value.encoded_size());

let (decoded, decoded_len) = u32::decode(&buf[..len])?;
assert_eq!(decoded, value);
assert_eq!(decoded_len, len);

Two API layers

• The Encode and Decode traits (and the free encode(), decode(), and bulk_encode/bulk_decode functions) work on ordinary slices, validate their input, and return typed Errors. Use these for untrusted or tightly-sized data.
• The array-based functions (encode_u32, decode_u32, and friends) are the infallible fast core. They are all const fn, so they also work in compile-time contexts:

const LEN: usize = {
    let mut buf = [0u8; 5];
    vlen::encode_u32(&mut buf, 12345)
};
assert_eq!(LEN, 2);

Choosing an API

Need	Use
One checked value	Encode/Decode or encode()/decode()
Canonical first value	decode_canonical()
Exact whole input	decode_exact(); use decode_strict() when it must also be canonical
A mixed-type message	Writer and Reader; use Reader::read_canonical and Reader::finish for strict fields and framing
A homogeneous batch	bulk_encode()/bulk_decode(), or the specialized u32, u64, i32, and i64 variants
Lazy stream decoding	decode_iter(), or a specialized iterator such as decode_iter_u32()
An owned buffer (alloc)	encode_to_vec(), encode_append(), and the bulk Vec helpers
Compile-time or trusted fixed arrays	encode_u32()/decode_u32() and their typed counterparts

Exact and canonical decoding

The normal decoder accepts over-long encodings so protocols can reserve a fixed-width slot before its value is known. Opt into stricter validation when encoded bytes must have one deterministic representation:

let reserved = [0x85, 0x00]; // the value 5 in an over-long two-byte slot
assert_eq!(vlen::decode::<u32>(&reserved), Ok((5, 2)));
assert!(matches!(
    vlen::decode_strict::<u32>(&reserved),
    Err(vlen::StrictError::NonCanonical { .. })
));
assert_eq!(vlen::decode_exact::<u32>(&[5]), Ok(5));

Re-exports

pub use decode::Decode;

pub use decode::decode;

pub use decode::decode_canonical;

pub use decode::decode_exact;

pub use decode::decode_f32;

pub use decode::decode_f64;

pub use decode::decode_i8;

pub use decode::decode_i16;

pub use decode::decode_i32;

pub use decode::decode_i64;

pub use decode::decode_i128;

pub use decode::decode_strict;

pub use decode::decode_u8;

pub use decode::decode_u16;

pub use decode::decode_u32;

pub use decode::decode_u64;

pub use decode::decode_u128;

pub use encode::Encode;

pub use encode::encode;

pub use encode::encode_f32;

pub use encode::encode_f64;

pub use encode::encode_i8;

pub use encode::encode_i16;

pub use encode::encode_i32;

pub use encode::encode_i64;

pub use encode::encode_i128;

pub use encode::encode_u8;

pub use encode::encode_u16;

pub use encode::encode_u32;

pub use encode::encode_u64;

pub use encode::encode_u128;

pub use encode::encoded_len;

pub use encode::encoded_size;

pub use encode::encoded_size_u8;

pub use encode::encoded_size_u16;

pub use encode::encoded_size_u32;

pub use encode::encoded_size_u64;

pub use encode::encoded_size_u128;

pub use bulk::DecodeIter;

pub use bulk::DecodeIterI32;

pub use bulk::DecodeIterI64;

pub use bulk::DecodeIterU32;

pub use bulk::DecodeIterU64;

pub use bulk::bulk_decode;

pub use bulk::bulk_decode_i32;

pub use bulk::bulk_decode_i64;

pub use bulk::bulk_decode_u32;

pub use bulk::bulk_decode_u64;

pub use bulk::bulk_encode;

pub use bulk::bulk_encode_i32;

pub use bulk::bulk_encode_i64;

pub use bulk::bulk_encode_u32;

pub use bulk::bulk_encode_u64;

pub use bulk::decode_iter;

pub use bulk::decode_iter_i32;

pub use bulk::decode_iter_i64;

pub use bulk::decode_iter_u32;

pub use bulk::decode_iter_u64;

Modules

bulk

Bulk encoding and decoding of many values.

decode

Decoding functions for vlen.

encode

Encoding functions for vlen.

serdeserde

Serde integration for vlen encoding.

Structs

Reader

Reads consecutive values from a byte slice, tracking the position.

Writer

Writes consecutive values into a byte slice, tracking the position.

Enums

Error

Errors returned by the checked (slice-based) encode and decode APIs.

StrictError

Errors returned by strict and exact decoding APIs.

Functions

bulk_decode_valuesalloc

Decodes every value in a slice into a newly allocated vector.

bulk_encode_appendalloc

Appends the encodings of all values to a byte vector.

bulk_encode_to_vecalloc

Encodes a slice of values into a newly allocated buffer.

decode_value

Decodes a single value from a slice, discarding the length.

encode_appendalloc

Appends the encoding of value to a byte vector.

encode_to_vecalloc

Encodes a value into a newly allocated buffer.

Type Aliases

Result

Convenience alias for results produced by this crate.

StrictResult

Convenience alias for results produced by strict decoding APIs.