flederfuchs_amqp/unsigned/

uint.rs

//! This module provides tools for encoding and decoding `u32` values in specific AMQP-inspired formats.
//!
//! # Examples
//!
//! ```rust
//! use flederfuchs_amqp::{ser_uint, de_uint, UIntByteRepr};
//!
//! // Encoding examples
//! let zero = ser_uint(0);
//! assert_eq!(zero, UIntByteRepr::ZeroOctet([0x43]));
//!
//! let small = ser_uint(127);
//! assert_eq!(small, UIntByteRepr::SingleOctet([0x52, 127]));
//!
//! let large = ser_uint(0x01020304);
//! assert_eq!(large, UIntByteRepr::FourOctets([0x70, 0x01, 0x02, 0x03, 0x04]));
//!
//! // Decoding examples
//! let bytes = [0x43];
//! assert_eq!(de_uint(&bytes), Some((0, &[][..])));
//!
//! let bytes = [0x52, 0x7F];
//! assert_eq!(de_uint(&bytes), Some((127, &[][..])));
//!
//! let bytes = [0x70, 0x01, 0x02, 0x03, 0x04];
//! assert_eq!(de_uint(&bytes), Some((0x01020304, &[][..])));
//! ```

use crate::conditional::if_marker;
use crate::{de_fixed_width_empty, de_fixed_width_four, de_fixed_width_one};

type UInt = u32;

///
/// Represents the different byte encodings of a 32-bit unsigned signed.
///
/// This enum provides three variants based on the size of the signed's encoding:
/// - `ZeroOctet`: Represents an signed value of `0`, encoded as a single byte `[0x43]`.
/// - `SingleOctet`: Represents integers that can fit into a single byte, encoded as two bytes `[0x52, x]`.
/// - `FourOctets`: Represents integers requiring a full 32-bit representation, encoded as five bytes `[0x70, x1, x2, x3, x4]`.
///
/// These formats are designed to handle encoded AMQP integers.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub enum UIntByteRepr {
    /// Represents the zero-byte encoding of a 32-bit unsigned signed.
    ///
    /// This variant is used when the signed value is `0`. It is represented
    /// as a single byte `[0x43]`.
    ///
    /// # Example
    ///
    /// ```
    /// use flederfuchs_amqp::UIntByteRepr;
    ///
    /// let encoding = UIntByteRepr::ZeroOctet([0x43]);
    /// assert_eq!(encoding, UIntByteRepr::ZeroOctet([0x43]));
    /// ```
    ZeroOctet([u8; 1]),

    /// Represents the single-octet encoding of a 32-bit unsigned signed.
    ///
    /// This variant is used when the signed value fits within a single byte.
    /// It is represented as two bytes `[0x52, x]`, where `x` is the signed value.
    ///
    /// # Example
    ///
    /// ```
    /// use flederfuchs_amqp::UIntByteRepr;
    ///
    /// let encoding = UIntByteRepr::SingleOctet([0x52, 0x7F]);
    /// assert_eq!(encoding, UIntByteRepr::SingleOctet([0x52, 0x7F]));
    /// ```
    SingleOctet([u8; 2]),

    /// Represents the four-octet encoding of a 32-bit unsigned signed.
    ///
    /// This variant is used when the signed value requires the full 32-bit representation.
    /// It is represented as five bytes `[0x70, x1, x2, x3, x4]`, where `x1..x4` are the big-endian
    /// bytes of the signed value.
    ///
    /// # Example
    ///
    /// ```
    /// use flederfuchs_amqp::UIntByteRepr;
    ///
    /// let encoding = UIntByteRepr::FourOctets([0x70, 0x01, 0x02, 0x03, 0x04]);
    /// assert_eq!(encoding, UIntByteRepr::FourOctets([0x70, 0x01, 0x02, 0x03, 0x04]));
    /// ```
    FourOctets([u8; 5]),
}

/// Encode a 32-bit unsigned signed into its respective encoding format.
///
/// The encoding uses one of the following formats:
/// 1. `ZeroOctet` for an signed value of `0`. This is represented by a single byte `[0x43]`.
/// 2. `SingleOctet` for integers that fit into a single byte. This is represented by two bytes `[0x52, x]`,
///    where `x` is the signed value.
/// 3. `FourOctets` for integers that require full 32-bit representation. This is represented by five bytes
///    `[0x70, x1, x2, x3, x4]`, where `x1..x4` are the big-endian bytes of the signed value.
///
/// # Examples
///
/// ```rust
/// use flederfuchs_amqp::ser_uint;
/// use flederfuchs_amqp::UIntByteRepr;
///
/// // Encoding the number zero
/// assert!(matches!(
///     ser_uint(0),
///     UIntByteRepr::ZeroOctet([0x43])
/// ));
///
/// // Encoding a single byte signed
/// assert!(matches!(
///     ser_uint(127),
///     UIntByteRepr::SingleOctet([0x52, 127])
/// ));
///
/// // Encoding a full 32-bit signed
/// assert!(matches!(
///     ser_uint(0x01020304),
///     UIntByteRepr::FourOctets([0x70, 0x01, 0x02, 0x03, 0x04])
/// ));
/// ```
///
#[must_use]
pub fn ser_uint(number: u32) -> UIntByteRepr {
    if let Some(value) = ser_uint0(number) {
        return value;
    }

    if let Some(value) = ser_smalluint(number) {
        return value;
    }

    ser_uint_(number)
}

const fn ser_uint_(number: u32) -> UIntByteRepr {
    let split_bytes = number.to_be_bytes();
    UIntByteRepr::FourOctets([
        0x70,
        split_bytes[0],
        split_bytes[1],
        split_bytes[2],
        split_bytes[3],
    ])
}

fn ser_smalluint(number: u32) -> Option<UIntByteRepr> {
    if let Ok(value) = u8::try_from(number) {
        return Some(UIntByteRepr::SingleOctet([0x52, value]));
    }
    None
}

const fn ser_uint0(number: u32) -> Option<UIntByteRepr> {
    if number == 0 {
        return Some(UIntByteRepr::ZeroOctet([0x43]));
    }
    None
}

/// Try and parse a ushort primitive value from a byte slice.
///
/// This function attempts to decode a `UShort` (a 16-bit unsigned signed) from a byte slice.
/// The first byte should match the expected prefix (`0x60`), followed by two bytes representing
/// the big-endian encoded `UShort`. Any remaining bytes are returned as part of the result.
///
/// # Examples
///
/// ```
/// use flederfuchs_amqp::de_ushort;
///
/// // Parsing a valid ushort primitive with no extra bytes
/// let bytes = &[0x60, 0x03, 0xE8];
/// let result = de_ushort(bytes);
/// assert_eq!(result, Some((1000, &[] as &[u8])));
///
/// // Parsing a valid ushort primitive with additional bytes
/// let bytes_with_extra = &[0x60, 0x03, 0xE8, 0x00];
/// let result = de_ushort(bytes_with_extra);
/// assert_eq!(result, Some((1000, &[0x00_u8][..])));
///
/// // Failing to parse due to an incorrect prefix
/// let invalid_bytes = &[0x50, 0x03, 0xE8];
/// let result = de_ushort(invalid_bytes);
/// assert_eq!(result, None);
///
/// // Failing to parse due to not enough bytes
/// let incomplete_bytes = &[0x60, 0x03];
/// let result = de_ushort(incomplete_bytes);
/// assert_eq!(result, None);
/// ```
#[must_use]
pub fn de_uint(b: &[u8]) -> Option<(UInt, &[u8])> {
    Some(b)
        .and_then(de_uint_uint0)
        .or_else(|| de_uint_smalluint(b))
        .or_else(|| de_uint_(b))
}

fn de_uint_uint0(b: &[u8]) -> Option<(UInt, &[u8])> {
    Some(b)
        .and_then(if_marker(0x43_u8))
        .and_then(de_fixed_width_empty)
        .map(|((), rest)| (0, rest))
}

fn de_uint_smalluint(b: &[u8]) -> Option<(UInt, &[u8])> {
    Some(b)
        .and_then(if_marker(0x52))
        .and_then(de_fixed_width_one)
        .map(|(first, rest)| (UInt::from(first[0]), rest))
}

fn de_uint_(b: &[u8]) -> Option<(UInt, &[u8])> {
    Some(b)
        .and_then(if_marker(0x70))
        .and_then(de_fixed_width_four)
        .map(|(data, rest)| {
            (
                UInt::from(u32::from_be_bytes([data[0], data[1], data[2], data[3]])),
                rest,
            )
        })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_zero_encoding() {
        assert_eq!(ser_uint(0), UIntByteRepr::ZeroOctet([0x43]));
    }

    #[test]
    fn test_single_octet_encoding() {
        assert_eq!(ser_uint(127), UIntByteRepr::SingleOctet([0x52, 127]));
        assert_eq!(ser_uint(1), UIntByteRepr::SingleOctet([0x52, 1]));
    }

    #[test]
    fn test_four_octets_encoding() {
        assert_eq!(
            ser_uint(0x0102_0304),
            UIntByteRepr::FourOctets([0x70, 0x01, 0x02, 0x03, 0x04])
        );
        assert_eq!(
            ser_uint(0xFFFF_FFFF),
            UIntByteRepr::FourOctets([0x70, 0xFF, 0xFF, 0xFF, 0xFF])
        );
    }

    #[test]
    fn test_zero_decoding() {
        let input = [0x43];
        assert_eq!(de_uint(&input), Some((0, &[][..])));
    }

    #[test]
    fn test_single_octet_decoding() {
        let input = [0x52, 0x7F];
        assert_eq!(de_uint(&input), Some((127, &[][..])));

        let input = [0x52, 0x7F, 0x00];
        assert_eq!(de_uint(&input), Some((127, &[0x00][..])));
    }

    #[test]
    fn test_four_octets_decoding() {
        let input = [0x70, 0x01, 0x02, 0x03, 0x04];
        assert_eq!(de_uint(&input), Some((0x0102_0304, &[][..])));

        let input = [0x70, 0x01, 0x02, 0x03, 0x04, 0xFF];
        assert_eq!(de_uint(&input), Some((0x0102_0304, &[0xFF][..])));
    }

    #[test]
    fn test_invalid_decoding() {
        let empty: [u8; 0] = [];
        assert_eq!(de_uint(&empty), None);

        let invalid_prefix = [0x00];
        assert_eq!(de_uint(&invalid_prefix), None);

        let incomplete = [0x70, 0x01, 0x02];
        assert_eq!(de_uint(&incomplete), None);
    }
}