Trait TryDecodeFrom

Source

pub trait TryDecodeFrom<'a>: Sized {
    type Error;

    // Required method
    fn try_decode_from(bytes: &'a [u8]) -> Result<(Self, &'a [u8]), Self::Error>;
}

Expand description

Trait for fallibly decoding values from byte slices.

This trait provides zero-copy parsing of varint-encoded values from byte slices, returning both the decoded value and the remaining unconsumed bytes. This design enables efficient sequential parsing of multiple values from a single buffer.

§Lifetime Parameter

The 'a lifetime parameter ties the returned slice reference to the input buffer, preventing dangling references and enabling zero-copy parsing.

§Error Handling

Decoding can fail for several reasons:

Insufficient bytes in the input
Invalid varint encoding
Truncated data

Errors are returned as structured Error types with proper source chains for debugging.

§Performance

Decoding is highly optimized:

Zero allocations (returns slice references)
No data copying
Constant-time validation

§Thread Safety

This trait is Send + Sync safe. Implementations are stateless and can be called concurrently from multiple threads.

§Examples

§Basic Decoding

use multi_trait::TryDecodeFrom;

// Decode a single value
let bytes = vec![42];
let (value, remaining) = u8::try_decode_from(&bytes).unwrap();
assert_eq!(value, 42);
assert!(remaining.is_empty());

§Sequential Decoding

use multi_trait::TryDecodeFrom;

// Decode multiple values from one buffer
let bytes = vec![0x01, 0x02, 0x03];
let (first, rest) = u8::try_decode_from(&bytes).unwrap();
let (second, rest) = u8::try_decode_from(rest).unwrap();
let (third, rest) = u8::try_decode_from(rest).unwrap();

assert_eq!(first, 1);
assert_eq!(second, 2);
assert_eq!(third, 3);
assert!(rest.is_empty());

§Error Handling

use multi_trait::{TryDecodeFrom, Error};

// Handle decode errors
let empty: &[u8] = &[];
match u32::try_decode_from(empty) {
    Ok((value, _)) => println!("Decoded: {}", value),
    Err(Error::UnsignedVarintDecode { .. }) => {
        // Expected for empty input
    }
    Err(e) => panic!("Unexpected error: {}", e),
}

§Implemented For

bool: Decodes 0 as false, non-zero as true
u8, u16, u32, u64, u128: Variable-length decoding
usize: Platform-dependent (32-bit or 64-bit)

Required Associated Types§

Source

type Error

The error type returned on decoding failure.

For built-in implementations, this is Error.

Required Methods§

Source

fn try_decode_from(bytes: &'a [u8]) -> Result<(Self, &'a [u8]), Self::Error>

Try to decode a value from a byte slice.

On success, returns a tuple containing:

The decoded value
A slice reference to the remaining unconsumed bytes

The remaining bytes slice shares the same lifetime as the input, enabling zero-copy sequential parsing.

§Errors

Returns an error if:

The input slice is too short
The varint encoding is invalid
The encoded value is truncated

§Examples

use multi_trait::TryDecodeFrom;

let bytes = vec![0xFF, 0x01]; // Varint encoding of 255
let (value, remaining) = u8::try_decode_from(&bytes).unwrap();
assert_eq!(value, 255);
assert!(remaining.is_empty());