Crate tiny_varint

tiny-varint

A high-performance variable-length integer (VarInt) encoding/decoding library, fully compatible with no_std environments.

VarInt is an efficient way to encode integers into byte sequences, using fewer bytes for smaller values. It’s widely used in protocol buffers, data compression, and network transmission scenarios.

Features

• Generic Integer Support: Works with all integer types (u8-u128, i8-i128)
• Batch Processing API: Efficiently handle multiple values with state management
• Iterator-based API: Memory-efficient processing using iterator methods
• Basic Encoding Functions: Low-level functions for direct use
• ZigZag Support: Efficient encoding of signed integers
• Unified Value Type: VarintValue enum for type-aware encoding/decoding
• No-std Compatible: Works in embedded environments

Usage Examples

Generic API with different integer types

use tiny_varint::{encode, decode};
 
// Works with any integer type
let mut buf = [0u8; 10];
 
// Use with u32
let bytes_written = encode(42u32, &mut buf).unwrap();
let (value, bytes_read) = decode::<u32>(&buf).unwrap();
assert_eq!(value, 42u32);
 
// Use with i16
let bytes_written = encode(-42i16, &mut buf).unwrap();
let (value, bytes_read) = decode::<i16>(&buf).unwrap();
assert_eq!(value, -42i16);

Batch API

use tiny_varint::{VarIntEncoder, VarIntDecoder};
 
// Encode multiple values
let values = [1u64, 127, 128, 16383, 16384];
let mut buffer = [0u8; 100];
 
let mut encoder = VarIntEncoder::new(&mut buffer);
let bytes_written = encoder.write_batch(&values).unwrap();
 
// Decode multiple values
let mut decoded = [0u64; 5];
let mut decoder = VarIntDecoder::new(&buffer[..bytes_written]);
decoder.read_batch(&mut decoded).unwrap();

Iterator-based API

use tiny_varint::{bytes_of, values_from};
 
// Encode a value into bytes using iterator methods
let value = 16384u64;
for byte in bytes_of(value) {
    // Process each byte individually
    println!("{:02X}", byte);
}
 
// Decode values from a byte buffer using iterator methods
let buffer = [0x80, 0x80, 0x01]; // Encoded value 16384
for result in values_from::<u64>(&buffer) {
    match result {
        Ok(value) => println!("Decoded: {}", value),
        Err(e) => println!("Error: {:?}", e),
    }
}

VarintValue for mixed type data

use tiny_varint::{VarintValue, varint};

// Create values of different types
let values = [
    varint!(u32: 42),
    varint!(i16: -100),
    varint!(u64: 1000000)
];

// Serialize each value
let mut buffer = [0u8; 100];
let mut pos = 0;

for value in &values {
    let bytes_written = value.to_bytes(&mut buffer[pos..]).unwrap();
    pos += bytes_written;
}

// Deserialize values
let mut read_pos = 0;
let mut results = Vec::new();

while read_pos < pos {
    let (value, bytes_read) = VarintValue::from_bytes(&buffer[read_pos..pos]).unwrap();
    results.push(value);
    read_pos += bytes_read;
}

// Values are preserved with their original types
assert_eq!(results[0], varint!(u32: 42));
assert_eq!(results[1], varint!(i16: -100));
assert_eq!(results[2], varint!(u64: 1000000));

Macros

varint

Macro for creating VarintValue instances in a concise way

Structs

VarIntBytesIter

Iterator representing varint encoded bytes

VarIntDecoder

Batch decoder for VarInt values with state management

VarIntEncoder

Batch encoder for VarInt values with state management

VarIntValuesIter

Iterator for decoding varint values from a byte buffer

Enums

Error

Error type for varint encoding/decoding operations

VarintValue

Enum representing different integer types that can be encoded as varints. Each variant wraps a specific Rust integer type.

Traits

VarInt

Generic trait for variable-length integer encoding

ZigZag

Trait for ZigZag encoding

Functions

bytes_of

Helper function to create a bytes encoder for a value

decode

Decodes arbitrary VarInt type from varint format

decode_batch

Convenience function to decode a batch of u64 values

decode_zigzag

Decode a signed integer from a varint-encoded zigzag value

encode

Encodes arbitrary VarInt type to varint format

encode_batch

Convenience function to encode a batch of u64 values

encode_zigzag

Encode a signed integer using ZigZag, then encode it as a varint

values_from

Helper function to create a values decoder from a buffer

varint_size

Calculates the number of bytes needed to encode a VarInt value