//! Variable-length integer encoding and decoding //! //! # Overview //! //! This module implements Google's Protocol Buffers variable-length integer encoding. //! Each byte uses: //! - 7 bits for the value //! - 1 "continuation" bit to indicate if more bytes follow //! //! `u8` and `i8` are omitted since those types do not benefit from varint encoding. //! //! `usize` and `isize` are omitted to prevent behavior from depending on the target architecture. //! //! [Uint](crate::Uint) encodes the same way at any width. //! //! # Usage Example //! //! ```rust //! use commonware_codec::{Encode, DecodeExt, varint::{UInt, SInt}}; //! //! // Unsigned example //! let one = UInt(42u128).encode(); //! assert_eq!(one.len(), 1); // 42 fits in a single byte //! let decoded: u128 = UInt::decode(one).unwrap().into(); //! assert_eq!(decoded, 42); //! //! // Signed example (ZigZag) //! let neg = SInt(-3i32).encode(); //! assert_eq!(neg.len(), 1); //! let decoded: i32 = SInt::decode(neg).unwrap().into(); //! assert_eq!(decoded, -3); //! ``` use crate::{Buf, EncodeSize, Error, FixedSize, MaxEncodeSize, Read, Write}; use bytes::BufMut; use commonware_macros::stability; use core::{fmt::Debug, mem::size_of}; use sealed::{SPrim, UPrim}; /// The number of bits in a byte. const BITS_PER_BYTE: usize = 8; /// The number of data-bearing bits in a byte. /// That is, the number of bits in a byte excluding the continuation bit. const DATA_BITS_PER_BYTE: usize = 7; /// The mask for the data-bearing bits in a byte. const DATA_BITS_MASK: u8 = 0x7F; /// The mask for the continuation bit in a byte. /// /// In varint encoding, each byte uses 7 bits for data and 1 bit (the most significant) /// to indicate whether more bytes follow. If this bit is set, the varint continues, /// if clear this is the final byte. const CONTINUATION_BIT_MASK: u8 = 0x80; /// Maximum encoded size of a u16 varint in bytes. pub const MAX_U16_VARINT_SIZE: usize = (size_of::() * BITS_PER_BYTE).div_ceil(DATA_BITS_PER_BYTE); /// Maximum encoded size of a u32 varint in bytes. pub const MAX_U32_VARINT_SIZE: usize = (size_of::() * BITS_PER_BYTE).div_ceil(DATA_BITS_PER_BYTE); /// Maximum encoded size of a u64 varint in bytes. pub const MAX_U64_VARINT_SIZE: usize = (size_of::() * BITS_PER_BYTE).div_ceil(DATA_BITS_PER_BYTE); /// Maximum encoded size of a u128 varint in bytes. pub const MAX_U128_VARINT_SIZE: usize = (size_of::() * BITS_PER_BYTE).div_ceil(DATA_BITS_PER_BYTE); /// An incremental varint decoder for reading varints byte-by-byte from streams. /// /// This is useful when reading from async streams where you receive one byte at a time /// and need to know when the varint is complete while also building up the decoded value. /// /// # Example /// /// ``` /// use commonware_codec::varint::Decoder; /// /// let mut decoder = Decoder::::new(); /// /// // Feed bytes one at a time (e.g., from a stream) /// // 300 encodes as [0xAC, 0x02] /// assert_eq!(decoder.feed(0xAC).unwrap(), None); // continuation bit set, need more /// assert_eq!(decoder.feed(0x02).unwrap(), Some(300)); // complete! /// ``` #[derive(Debug, Clone)] pub struct Decoder { result: U, bits_read: usize, } impl Default for Decoder { fn default() -> Self { Self::new() } } impl Decoder { /// Creates a new decoder ready to receive bytes. #[inline] pub fn new() -> Self { Self { result: U::from_u8(0), bits_read: 0, } } /// Feeds a byte to the decoder. /// /// Returns: /// - `Ok(Some(value))` when the varint is complete /// - `Ok(None)` when more bytes are needed /// - `Err(InvalidVarint)` if the varint is malformed (overflow or invalid encoding) #[inline] pub fn feed(&mut self, byte: u8) -> Result, Error> { let max_bits = U::BITS; // If this is not the first byte, but the byte is completely zero, we have an invalid // varint. This is because this byte has no data bits and no continuation, so there was no // point in continuing to this byte in the first place. While the output could still result // in a valid value, we ensure that every value has exactly one unique, valid encoding. if byte == 0 && self.bits_read > 0 { return Err(Error::InvalidVarint(U::SIZE)); } // If this must be the last byte, check for overflow (i.e. set bits beyond the size of T). // Because the continuation bit is the most-significant bit, this check also happens to // check for an invalid continuation bit. // // If we have reached what must be the last byte, this check prevents continuing to read // from the buffer by ensuring that the conditional (`if byte & CONTINUATION_BIT_MASK == 0`) // always evaluates to true. let remaining_bits = max_bits.checked_sub(self.bits_read).unwrap(); if remaining_bits <= DATA_BITS_PER_BYTE { let relevant_bits = BITS_PER_BYTE - byte.leading_zeros() as usize; if relevant_bits > remaining_bits { return Err(Error::InvalidVarint(U::SIZE)); } } // Write the 7 bits of data to the result. self.result |= U::from_u8(byte & DATA_BITS_MASK) << self.bits_read; // Check if complete (continuation bit not set) if byte & CONTINUATION_BIT_MASK == 0 { return Ok(Some(self.result)); } self.bits_read += DATA_BITS_PER_BYTE; Ok(None) } } #[doc(hidden)] mod sealed { use super::*; use core::ops::{BitOrAssign, Shl, ShrAssign}; /// A trait for unsigned integers that can be varint encoded. pub trait UPrim: Copy + Sized + FixedSize + ShrAssign + Shl + BitOrAssign + PartialOrd + Debug { /// Number of bits in the integer. const BITS: usize; /// Returns the integer holding `byte`. The byte must fit the integer's width. fn from_u8(byte: u8) -> Self; /// Returns the number of leading zeros in the integer. fn leading_zeros(self) -> usize; /// Returns the least significant byte of the integer. fn as_u8(self) -> u8; } // Implements the `UPrim` trait for all unsigned integer types. macro_rules! impl_uint { ($type:ty) => { impl UPrim for $type { const BITS: usize = size_of::<$type>() * BITS_PER_BYTE; #[inline(always)] fn from_u8(byte: u8) -> Self { Self::from(byte) } #[inline(always)] fn leading_zeros(self) -> usize { self.leading_zeros() as usize } #[inline(always)] fn as_u8(self) -> u8 { self as u8 } } }; } impl_uint!(u16); impl_uint!(u32); impl_uint!(u64); impl_uint!(u128); #[stability(ALPHA)] impl UPrim for crate::Uint { const BITS: usize = BITS; #[inline(always)] fn from_u8(byte: u8) -> Self { let mut limbs = [0; LIMBS]; if let Some(limb) = limbs.first_mut() { *limb = u64::from(byte); } Self::from_limbs(limbs) } #[inline(always)] fn leading_zeros(self) -> usize { Self::leading_zeros(&self) } #[inline(always)] fn as_u8(self) -> u8 { self.as_limbs() .first() .map_or(0, |limb| limb.to_le_bytes()[0]) } } /// A trait for signed integer primitives that can be converted to and from unsigned integer /// primitives of the equivalent size. /// /// When converted to unsigned integers, the encoding is done using ZigZag encoding, which moves the /// sign bit to the least significant bit (shifting all other bits to the left by one). This allows /// for more efficient encoding of numbers that are close to zero, even if they are negative. pub trait SPrim: Copy + Sized + FixedSize + PartialOrd + Debug { /// The unsigned equivalent type of the signed integer. /// This type must be the same size as the signed integer type. type UnsignedEquivalent: UPrim; /// Converts the signed integer to an unsigned integer using ZigZag encoding. fn as_zigzag(&self) -> Self::UnsignedEquivalent; /// Converts a (ZigZag'ed) unsigned integer back to a signed integer. fn un_zigzag(value: Self::UnsignedEquivalent) -> Self; } /// Asserts that two types are the same size at compile time. #[inline(always)] const fn assert_equal_size() { assert!( size_of::() == size_of::(), "Unsigned integer must be the same size as the signed integer" ); } // Implements the `SPrim` trait for all signed integer types. macro_rules! impl_sint { ($type:ty, $utype:ty) => { impl SPrim for $type { type UnsignedEquivalent = $utype; #[inline] fn as_zigzag(&self) -> $utype { // TODO: Re-evaluate assertion placement after `generic_const_exprs` is stable. const { assert_equal_size::<$type, $utype>(); } let shr = size_of::<$utype>() * 8 - 1; ((self << 1) ^ (self >> shr)) as $utype } #[inline] fn un_zigzag(value: $utype) -> Self { // TODO: Re-evaluate assertion placement after `generic_const_exprs` is stable. const { assert_equal_size::<$type, $utype>(); } ((value >> 1) as $type) ^ (-((value & 1) as $type)) } } }; } impl_sint!(i16, u16); impl_sint!(i32, u32); impl_sint!(i64, u64); impl_sint!(i128, u128); } /// An ergonomic wrapper to allow for encoding and decoding of unsigned integers as varints rather /// than the default fixed-width integers. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct UInt(pub U); // Implements `Into` for `UInt` for all unsigned integer types. // This allows for easy conversion from `UInt` to `U` using `.into()`. macro_rules! impl_varuint_into { ($($type:ty),+) => { $( impl From> for $type { fn from(val: UInt<$type>) -> Self { val.0 } } )+ }; } impl_varuint_into!(u16, u32, u64, u128); #[stability(ALPHA)] impl From> for crate::Uint { fn from(val: UInt) -> Self { val.0 } } impl Write for UInt { fn write(&self, buf: &mut impl BufMut) { write(self.0, buf); } } impl Read for UInt { type Cfg = (); fn read_cfg(buf: &mut impl Buf, _: &()) -> Result { read(buf).map(UInt) } } impl EncodeSize for UInt { fn encode_size(&self) -> usize { size(self.0) } } // Each varint width has a known maximum encoded size. macro_rules! impl_varuint_max { ($($type:ty => $max:expr),+ $(,)?) => { $( impl MaxEncodeSize for UInt<$type> { const MAX_ENCODE_SIZE: usize = $max; } )+ }; } impl_varuint_max!( u16 => MAX_U16_VARINT_SIZE, u32 => MAX_U32_VARINT_SIZE, u64 => MAX_U64_VARINT_SIZE, u128 => MAX_U128_VARINT_SIZE, ); #[stability(ALPHA)] impl MaxEncodeSize for UInt> { const MAX_ENCODE_SIZE: usize = if BITS == 0 { 1 } else { BITS.div_ceil(DATA_BITS_PER_BYTE) }; } #[cfg(feature = "arbitrary")] impl arbitrary::Arbitrary<'_> for UInt where U: for<'a> arbitrary::Arbitrary<'a>, { fn arbitrary(u: &mut arbitrary::Unstructured<'_>) -> arbitrary::Result { let value = U::arbitrary(u)?; Ok(Self(value)) } } /// An ergonomic wrapper to allow for encoding and decoding of primitive signed integers as /// varints rather than the default fixed-width integers. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct SInt(pub S); // Implements `Into` for `SInt` for all signed integer types. // This allows for easy conversion from `SInt` to `S` using `.into()`. macro_rules! impl_varsint_into { ($($type:ty),+) => { $( impl From> for $type { fn from(val: SInt<$type>) -> Self { val.0 } } )+ }; } impl_varsint_into!(i16, i32, i64, i128); impl Write for SInt { fn write(&self, buf: &mut impl BufMut) { write_signed::(self.0, buf); } } impl Read for SInt { type Cfg = (); fn read_cfg(buf: &mut impl Buf, _: &()) -> Result { read_signed::(buf).map(SInt) } } impl EncodeSize for SInt { fn encode_size(&self) -> usize { size_signed::(self.0) } } #[cfg(feature = "arbitrary")] impl arbitrary::Arbitrary<'_> for SInt where S: for<'a> arbitrary::Arbitrary<'a>, { fn arbitrary(u: &mut arbitrary::Unstructured<'_>) -> arbitrary::Result { let value = S::arbitrary(u)?; Ok(Self(value)) } } /// Encodes an unsigned integer as a varint fn write(value: T, buf: &mut impl BufMut) { // A width of at most seven bits holds only values that take one byte, and cannot hold the // continuation threshold. if T::BITS <= DATA_BITS_PER_BYTE { buf.put_u8(value.as_u8()); return; } // Fast path for small values (common case for lengths). `as_u8()` does not truncate such a // value or leave a continuation bit. let continuation_threshold = T::from_u8(CONTINUATION_BIT_MASK); if value < continuation_threshold { buf.put_u8(value.as_u8()); return; } // Stage the encoded bytes on the stack so the buffer receives bulk writes. The stage holds the // longest primitive encoding, and only an integer whose encoding can be longer flushes a full // stage. Whether a type's encoding can be longer is a constant, so the primitives' loop // carries no flush. let mut bytes = [0u8; MAX_U128_VARINT_SIZE]; let flushes = T::BITS.div_ceil(DATA_BITS_PER_BYTE) > bytes.len(); let mut len = 0; let mut val = value; while val >= continuation_threshold { if flushes && len == bytes.len() { buf.put_slice(&bytes); len = 0; } bytes[len] = val.as_u8() | CONTINUATION_BIT_MASK; len += 1; val >>= DATA_BITS_PER_BYTE; } if flushes && len == bytes.len() { buf.put_slice(&bytes); len = 0; } bytes[len] = val.as_u8(); buf.put_slice(&bytes[..=len]); } /// Decodes an unsigned integer from a varint. /// /// Returns an error if: /// - The varint is invalid (too long or malformed) /// - The buffer ends while reading fn read(buf: &mut impl Buf) -> Result { // Fast path for single-byte values. A width below seven bits cannot hold all of them, so its // byte goes to the decoder. let mut byte = buf.try_get_u8().map_err(|_| Error::EndOfBuffer)?; if byte & CONTINUATION_BIT_MASK == 0 && T::BITS >= DATA_BITS_PER_BYTE { return Ok(T::from_u8(byte)); } // The decoder enforces canonical encodings and rejects overflow, starting with the byte // already read. let mut decoder = Decoder::::new(); loop { if let Some(value) = decoder.feed(byte)? { return Ok(value); } byte = buf.try_get_u8().map_err(|_| Error::EndOfBuffer)?; } } /// Calculates the number of bytes needed to encode an unsigned integer as a varint. fn size(value: T) -> usize { let data_bits = T::BITS - value.leading_zeros(); usize::max(1, data_bits.div_ceil(DATA_BITS_PER_BYTE)) } /// Encodes a signed integer as a varint using ZigZag encoding. fn write_signed(value: S, buf: &mut impl BufMut) { write(value.as_zigzag(), buf); } /// Decodes a signed integer from varint ZigZag encoding. fn read_signed(buf: &mut impl Buf) -> Result { Ok(S::un_zigzag(read(buf)?)) } /// Calculates the number of bytes needed to encode a signed integer as a varint. fn size_signed(value: S) -> usize { size(value.as_zigzag()) } #[cfg(test)] mod tests { use super::*; use crate::{Copying, DecodeExt, Encode, ReadExt, U256, Uint, error::Error}; use bytes::{Buf as _, Bytes}; #[test] fn test_fragmented_varint() { let mut buf = Bytes::from_static(&[0x80]).chain(Bytes::from_static(&[0x01, 0x07])); assert_eq!(read::(&mut buf).unwrap(), 128); assert_eq!(read::(&mut buf).unwrap(), 7); assert_eq!(buf.remaining(), 0); } #[test] fn test_end_of_buffer() { let mut buf: Bytes = Bytes::from_static(&[]); assert!(matches!(read::(&mut buf), Err(Error::EndOfBuffer))); let mut buf: Bytes = Bytes::from_static(&[0x80, 0x8F]); assert!(matches!(read::(&mut buf), Err(Error::EndOfBuffer))); let mut buf: Bytes = Bytes::from_static(&[0xFF, 0x8F]); assert!(matches!(read::(&mut buf), Err(Error::EndOfBuffer))); } #[test] fn test_overflow() { let mut buf: Bytes = Bytes::from_static(&[0xFF, 0xFF, 0xFF, 0xFF, 0x0F]); assert_eq!(read::(&mut buf).unwrap(), u32::MAX); let mut buf: Bytes = Bytes::from_static(&[0xFF, 0xFF, 0xFF, 0xFF, 0x1F]); assert!(matches!( read::(&mut buf), Err(Error::InvalidVarint(u32::SIZE)) )); let mut buf = Bytes::from_static(&[0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x02]); assert!(matches!( read::(&mut buf), Err(Error::InvalidVarint(u64::SIZE)) )); } #[test] fn test_overcontinuation() { let mut buf: Bytes = Bytes::from_static(&[0x80, 0x80, 0x80, 0x80, 0x80]); let result = read::(&mut buf); assert!(matches!(result, Err(Error::InvalidVarint(u32::SIZE)))); } #[test] fn test_zeroed_byte() { let mut buf = Bytes::from_static(&[0xFF, 0x00]); let result = read::(&mut buf); assert!(matches!(result, Err(Error::InvalidVarint(u64::SIZE)))); } /// A wide integer's varint is the same bytes as a primitive's for the values both hold, and /// its widest values stage past the primitive buffer. #[test] fn test_uint_round_trips_at_any_width() { // A value that fits a `u64` encodes as the primitive does and decodes back. for value in [0u64, 1, 127, 128, 300, 0x3FFF, 0x4000, u64::MAX] { let wide = UInt(U256::from(value)).encode(); assert_eq!(wide, UInt(value).encode()); assert_eq!(UInt::::decode(wide).unwrap().0, U256::from(value)); } // The value at bit 139 fills the staging buffer exactly before its final byte. let filling = U256::from_limbs([0, 0, 1 << 11, 0]); let beyond = U256::from_limbs([u64::MAX, 1, 0, 1 << 63]); for value in [filling, beyond, U256::MAX] { let encoded = UInt(value).encode(); assert_eq!(encoded.len(), UInt(value).encode_size()); assert_eq!(UInt::::decode(encoded).unwrap().0, value); } assert_eq!( UInt(U256::MAX).encode_size(), as MaxEncodeSize>::MAX_ENCODE_SIZE ); assert_eq!( as MaxEncodeSize>::MAX_ENCODE_SIZE, 37); // A bit beyond the width, a trailing zero byte, and a truncated encoding are refused. let mut bytes = UInt(U256::MAX).encode().to_vec(); *bytes.last_mut().unwrap() |= 0x10; assert!(matches!( UInt::::decode(Copying(&bytes)), Err(Error::InvalidVarint(32)) )); assert!(matches!( UInt::::decode(Copying(&[0xFF, 0x00])), Err(Error::InvalidVarint(32)) )); assert!(matches!( UInt::::decode(Copying(&[0xFF; 36])), Err(Error::EndOfBuffer) )); } /// Widths that are not a multiple of eight bits bound their encodings by their exact width. #[test] fn test_uint_partial_widths() { // Eight bits spill their top bit into a second byte. That byte holds nothing more. type U8 = Uint<8, 1>; assert_eq!(UInt(U8::MAX).encode().as_ref(), [0xFF, 0x01]); assert_eq!( UInt::::decode(Copying(&[0xFF, 0x01])).unwrap().0, U8::MAX ); assert!(matches!( UInt::::decode(Copying(&[0xFF, 0x02])), Err(Error::InvalidVarint(1)) )); // Thirty-six bits leave one bit for a sixth byte. type U36 = Uint<36, 1>; assert_eq!( as MaxEncodeSize>::MAX_ENCODE_SIZE, 6); let encoded = UInt(U36::MAX).encode(); assert_eq!(encoded.len(), 6); assert_eq!(UInt::::decode(encoded).unwrap().0, U36::MAX); assert!(matches!( UInt::::decode(Copying(&[0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x1F])), Err(Error::InvalidVarint(5)) )); // A width that is a multiple of seven bits fills its last byte, and a continuation there // is refused before another byte is read. type U14 = Uint<14, 1>; assert_eq!(UInt(U14::MAX).encode().as_ref(), [0xFF, 0x7F]); assert_eq!( UInt::::decode(Copying(&[0xFF, 0x7F])).unwrap().0, U14::MAX ); let mut buf = Bytes::from_static(&[0xFF, 0xFF, 0x01]); assert!(matches!( UInt::::read(&mut buf), Err(Error::InvalidVarint(2)) )); assert_eq!(buf.remaining(), 1); } /// A width of at most seven bits takes one byte, bounded by its exact width like any other. #[test] fn test_uint_narrow_widths() { // A bit beyond the width and a continuation are refused. type U4 = Uint<4, 1>; assert_eq!( as MaxEncodeSize>::MAX_ENCODE_SIZE, 1); assert_eq!(UInt(U4::MAX).encode().as_ref(), [0x0F]); assert_eq!(UInt::::decode(Copying(&[0x0F])).unwrap().0, U4::MAX); for refused in [&[0x10][..], &[0x8F, 0x01]] { assert!(matches!( UInt::::decode(Copying(refused)), Err(Error::InvalidVarint(1)) )); } // Seven bits fill the byte, so only a continuation is left to refuse. type U7 = Uint<7, 1>; assert_eq!( as MaxEncodeSize>::MAX_ENCODE_SIZE, 1); assert_eq!(UInt(U7::MAX).encode().as_ref(), [0x7F]); assert_eq!(UInt::::decode(Copying(&[0x7F])).unwrap().0, U7::MAX); assert!(matches!( UInt::::decode(Copying(&[0xFF, 0x01])), Err(Error::InvalidVarint(1)) )); // A width of zero bits holds only zero. Zero still takes a byte. type U0 = Uint<0, 0>; assert_eq!( as MaxEncodeSize>::MAX_ENCODE_SIZE, 1); assert_eq!(UInt(U0::ZERO).encode_size(), 1); assert_eq!(UInt(U0::ZERO).encode().as_ref(), [0x00]); assert_eq!(UInt::::decode(Copying(&[0x00])).unwrap().0, U0::ZERO); assert!(matches!( UInt::::decode(Copying(&[0x01])), Err(Error::InvalidVarint(0)) )); // The byte-at-a-time decoder applies the same bound. assert_eq!(Decoder::::new().feed(0x0F).unwrap(), Some(U4::MAX)); assert!(Decoder::::new().feed(0x10).is_err()); } /// Core round-trip check, generic over any UPrim. fn varuint_round_trip>() { const CASES: &[u128] = &[ 0, 1, 127, 128, 129, 0xFF, 0x100, 0x3FFF, 0x4000, 0x1_FFFF, 0xFF_FFFF, 0x1_FF_FF_FF_FF, 0xFF_FF_FF_FF_FF_FF, 0x1_FF_FF_FF_FF_FF_FF_FF_FF_FF_FF_FF_FF, u16::MAX as u128, u32::MAX as u128, u64::MAX as u128, u128::MAX, ]; for &raw in CASES { // skip values that don't fit into T let Ok(value) = raw.try_into() else { continue }; let value: T = value; // size matches encoding length let mut buf = Vec::new(); write(value, &mut buf); assert_eq!(buf.len(), size(value)); // decode matches original value let mut slice = Copying(&buf); let decoded: T = read(&mut slice).unwrap(); assert_eq!(decoded, value); assert!(slice.0.is_empty()); // UInt wrapper let encoded = UInt(value).encode(); assert_eq!(UInt::::decode(encoded).unwrap(), UInt(value)); } } #[test] fn test_varuint() { varuint_round_trip::(); varuint_round_trip::(); varuint_round_trip::(); varuint_round_trip::(); } fn varsint_round_trip>() { const CASES: &[i128] = &[ 0, 1, -1, 2, -2, 127, -127, 128, -128, 129, -129, 0x7FFFFFFF, -0x7FFFFFFF, 0x7FFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF, -0x7FFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF, i16::MIN as i128, i16::MAX as i128, i32::MIN as i128, i32::MAX as i128, i64::MIN as i128, i64::MAX as i128, ]; for &raw in CASES { // skip values that don't fit into T let Ok(value) = raw.try_into() else { continue }; let value: T = value; // size matches encoding length let mut buf = Vec::new(); write_signed(value, &mut buf); assert_eq!(buf.len(), size_signed(value)); // decode matches original value let mut slice = Copying(&buf); let decoded: T = read_signed(&mut slice).unwrap(); assert_eq!(decoded, value); assert!(slice.0.is_empty()); // SInt wrapper let encoded = SInt(value).encode(); assert_eq!(SInt::::decode(encoded).unwrap(), SInt(value)); } } #[test] fn test_varsint() { varsint_round_trip::(); varsint_round_trip::(); varsint_round_trip::(); varsint_round_trip::(); } #[test] fn test_varuint_into() { let v32: u32 = 0x1_FFFF; let out32: u32 = UInt(v32).into(); assert_eq!(v32, out32); let v64: u64 = 0x1_FF_FF_FF_FF; let out64: u64 = UInt(v64).into(); assert_eq!(v64, out64); } #[test] fn test_varsint_into() { let s32: i32 = -123_456; let out32: i32 = SInt(s32).into(); assert_eq!(s32, out32); let s64: i64 = 987_654_321; let out64: i64 = SInt(s64).into(); assert_eq!(s64, out64); } #[test] fn test_conformity() { assert_eq!(0usize.encode(), &[0x00][..]); assert_eq!(1usize.encode(), &[0x01][..]); assert_eq!(127usize.encode(), &[0x7F][..]); assert_eq!(128usize.encode(), &[0x80, 0x01][..]); assert_eq!(16383usize.encode(), &[0xFF, 0x7F][..]); assert_eq!(16384usize.encode(), &[0x80, 0x80, 0x01][..]); assert_eq!(2097151usize.encode(), &[0xFF, 0xFF, 0x7F][..]); assert_eq!(2097152usize.encode(), &[0x80, 0x80, 0x80, 0x01][..]); assert_eq!( (u32::MAX as usize).encode(), &[0xFF, 0xFF, 0xFF, 0xFF, 0x0F][..] ); } #[test] fn test_all_u16_values() { // Exhaustively test all u16 values to ensure size matches encoding for i in 0..=u16::MAX { let value = i; let calculated_size = size(value); let mut buf = Vec::new(); write(value, &mut buf); assert_eq!( buf.len(), calculated_size, "Size mismatch for u16 value {value}", ); // Also verify UInt wrapper let uint = UInt(value); assert_eq!( uint.encode_size(), buf.len(), "UInt encode_size mismatch for value {value}", ); } } #[test] fn test_all_i16_values() { // Exhaustively test all i16 values to ensure size matches encoding for i in i16::MIN..=i16::MAX { let value = i; let calculated_size = size_signed(value); let mut buf = Vec::new(); write_signed(value, &mut buf); assert_eq!( buf.len(), calculated_size, "Size mismatch for i16 value {value}", ); // Also verify SInt wrapper let sint = SInt(value); assert_eq!( sint.encode_size(), buf.len(), "SInt encode_size mismatch for value {value}", ); // Verify we can decode it back correctly let mut slice = Copying(&buf); let decoded: i16 = read_signed(&mut slice).unwrap(); assert_eq!(decoded, value, "Decode mismatch for value {value}"); assert!( slice.0.is_empty(), "Buffer not fully consumed for value {value}", ); } } #[test] fn test_exact_bit_boundaries() { // Test values with exactly N bits set fn test_exact_bits + core::fmt::Display>() { for bits in 1..=128 { // Create a value with exactly 'bits' bits // e.g., bits=3 -> 0b111 = 7 let val = if bits == 128 { u128::MAX } else { (1u128 << bits) - 1 }; let Ok(value) = T::try_from(val) else { continue; }; // Compute expected size let expected_size = (bits as usize).div_ceil(DATA_BITS_PER_BYTE); let calculated_size = size(value); assert_eq!( calculated_size, expected_size, "Size calculation wrong for {val} with {bits} bits", ); // Compare encoded size let mut buf = Vec::new(); write(value, &mut buf); assert_eq!( buf.len(), expected_size, "Encoded size wrong for {val} with {bits} bits", ); } } test_exact_bits::(); test_exact_bits::(); test_exact_bits::(); test_exact_bits::(); } #[test] fn test_single_bit_boundaries() { // Test values with only a single bit set at different positions fn test_single_bits + core::fmt::Display>() { for bit_pos in 0..128 { // Create a value with only a single bit set at the given position let val = 1u128 << bit_pos; let Ok(value) = T::try_from(val) else { continue; }; // Compute expected size let expected_size = ((bit_pos + 1) as usize).div_ceil(DATA_BITS_PER_BYTE); let calculated_size = size(value); assert_eq!( calculated_size, expected_size, "Size wrong for 1<<{bit_pos} = {val}", ); // Compare encoded size let mut buf = Vec::new(); write(value, &mut buf); assert_eq!( buf.len(), expected_size, "Encoded size wrong for 1<<{bit_pos} = {val}", ); } } test_single_bits::(); test_single_bits::(); test_single_bits::(); test_single_bits::(); } #[test] fn test_max_varint_size_constants() { let mut buf = Vec::new(); write(u16::MAX, &mut buf); assert_eq!(buf.len(), MAX_U16_VARINT_SIZE); assert_eq!(buf.len(), UInt::::MAX_ENCODE_SIZE); buf.clear(); write(u32::MAX, &mut buf); assert_eq!(buf.len(), MAX_U32_VARINT_SIZE); assert_eq!(buf.len(), UInt::::MAX_ENCODE_SIZE); buf.clear(); write(u64::MAX, &mut buf); assert_eq!(buf.len(), MAX_U64_VARINT_SIZE); assert_eq!(buf.len(), UInt::::MAX_ENCODE_SIZE); buf.clear(); write(u128::MAX, &mut buf); assert_eq!(buf.len(), MAX_U128_VARINT_SIZE); assert_eq!(buf.len(), UInt::::MAX_ENCODE_SIZE); } #[cfg(feature = "arbitrary")] mod conformance { use super::*; use crate::conformance::CodecConformance; commonware_conformance::conformance_tests! { CodecConformance>, CodecConformance>, CodecConformance>, CodecConformance>, CodecConformance>, CodecConformance>, CodecConformance>, CodecConformance>, CodecConformance>, } } }