dx-serializer 0.1.0

//! DX-Inline: Aggressive Small Value Inlining
//!
//! rkyv uses pointers for all strings.
//! DX-Inline stores small values directly in the struct.
//!
//! Result: 4× faster string access for common cases (no pointer chase)

/// Maximum inline size for strings (23 bytes + 1 length = 24 bytes total)
pub const MAX_INLINE_STRING: usize = 23;

/// Maximum inline size for bytes (23 bytes + 1 length = 24 bytes total)
pub const MAX_INLINE_BYTES: usize = 23;

/// Inline string that avoids pointer chasing for short strings
///
/// Layout (24 bytes total):
/// - `[0-22]`:   Inline data (up to 23 bytes)
/// - `[23]`:    Length or marker (0-23 = inline length, 255 = heap pointer follows)
///
/// For heap strings, the layout becomes:
/// - `[0-7]`:    Heap pointer (u64)
/// - `[8-11]`:   Length (u32)
/// - `[12-22]`:  Padding
/// - `[23]`:     255 (heap marker)
#[repr(C)]
#[derive(Clone, Copy)]
pub struct DxInlineString {
    /// Raw data (23 bytes inline + 1 byte length)
    data: [u8; 24],
}

impl DxInlineString {
    /// Heap marker value
    pub const HEAP_MARKER: u8 = 255;

    /// Create an empty inline string
    #[inline(always)]
    pub const fn new() -> Self {
        Self { data: [0; 24] }
    }

    /// Create from a string slice
    ///
    /// Returns None if the string is too long to inline.
    /// For heap strings, use `from_heap`.
    #[inline]
    pub fn from_str(s: &str) -> Option<Self> {
        Self::from_bytes(s.as_bytes())
    }

    /// Create from bytes
    #[inline]
    pub fn from_bytes(bytes: &[u8]) -> Option<Self> {
        if bytes.len() > MAX_INLINE_BYTES {
            return None;
        }

        let mut result = Self::new();
        result.data[..bytes.len()].copy_from_slice(bytes);
        result.data[23] = bytes.len() as u8;

        Some(result)
    }

    /// Create from heap reference
    #[inline]
    pub fn from_heap(ptr: u64, len: u32) -> Self {
        let mut result = Self::new();

        // Write pointer
        result.data[0..8].copy_from_slice(&ptr.to_le_bytes());

        // Write length
        result.data[8..12].copy_from_slice(&len.to_le_bytes());

        // Set heap marker
        result.data[23] = Self::HEAP_MARKER;

        result
    }

    /// Check if this is an inline string
    #[inline(always)]
    pub const fn is_inline(&self) -> bool {
        self.data[23] != Self::HEAP_MARKER
    }

    /// Check if this is a heap string
    #[inline(always)]
    pub const fn is_heap(&self) -> bool {
        self.data[23] == Self::HEAP_MARKER
    }

    /// Get the inline length (panics if heap)
    #[inline(always)]
    pub const fn inline_len(&self) -> usize {
        debug_assert!(self.is_inline());
        self.data[23] as usize
    }

    /// Get the heap pointer (panics if inline)
    #[inline(always)]
    pub fn heap_ptr(&self) -> u64 {
        debug_assert!(self.is_heap());
        u64::from_le_bytes([
            self.data[0],
            self.data[1],
            self.data[2],
            self.data[3],
            self.data[4],
            self.data[5],
            self.data[6],
            self.data[7],
        ])
    }

    /// Get the heap length (panics if inline)
    #[inline(always)]
    pub fn heap_len(&self) -> u32 {
        debug_assert!(self.is_heap());
        u32::from_le_bytes([self.data[8], self.data[9], self.data[10], self.data[11]])
    }

    /// Get as string slice (inline only, no pointer chase!)
    ///
    /// This is the hot path - no pointer dereference needed.
    #[inline(always)]
    pub fn as_inline_str(&self) -> Option<&str> {
        if !self.is_inline() {
            return None;
        }

        let len = self.inline_len();
        // SAFETY: DxInlineString can only be constructed via from_str() or from_bytes(),
        // both of which validate UTF-8 on construction. The data is stored inline and
        // never modified after construction, so the UTF-8 validity is preserved.
        unsafe { Some(core::str::from_utf8_unchecked(&self.data[..len])) }
    }

    /// Get as byte slice (inline only)
    #[inline(always)]
    pub fn as_inline_bytes(&self) -> Option<&[u8]> {
        if !self.is_inline() {
            return None;
        }

        let len = self.inline_len();
        Some(&self.data[..len])
    }

    /// Get string with heap resolution
    ///
    /// For inline strings, returns immediately (no pointer chase).
    /// For heap strings, looks up in the provided heap buffer.
    #[inline]
    pub fn as_str_with_heap<'a>(&'a self, heap: &'a [u8]) -> Option<&'a str> {
        if self.is_inline() {
            self.as_inline_str()
        } else {
            let ptr = self.heap_ptr() as usize;
            let len = self.heap_len() as usize;

            if ptr + len > heap.len() {
                return None;
            }

            core::str::from_utf8(&heap[ptr..ptr + len]).ok()
        }
    }

    /// Compare with a string (SIMD-friendly for inline)
    #[inline]
    pub fn eq_str(&self, other: &str) -> bool {
        if let Some(s) = self.as_inline_str() {
            s == other
        } else {
            false // Can't compare heap strings without heap access
        }
    }

    /// Compare two inline strings directly
    #[inline]
    pub fn eq_inline(&self, other: &Self) -> bool {
        if !self.is_inline() || !other.is_inline() {
            return false;
        }

        // Compare all 24 bytes at once (SIMD-friendly)
        self.data == other.data
    }
}

impl Default for DxInlineString {
    fn default() -> Self {
        Self::new()
    }
}

impl core::fmt::Debug for DxInlineString {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        if self.is_inline() {
            if let Some(s) = self.as_inline_str() {
                write!(f, "DxInlineString::Inline({:?})", s)
            } else {
                write!(f, "DxInlineString::Inline(<invalid utf8>)")
            }
        } else {
            write!(f, "DxInlineString::Heap(ptr={}, len={})", self.heap_ptr(), self.heap_len())
        }
    }
}

/// Inline bytes for binary data
#[repr(C)]
#[derive(Clone, Copy)]
pub struct DxInlineBytes {
    data: [u8; 24],
}

impl DxInlineBytes {
    pub const HEAP_MARKER: u8 = 255;

    /// Create empty
    #[inline(always)]
    pub const fn new() -> Self {
        Self { data: [0; 24] }
    }

    /// Create from bytes
    #[inline]
    pub fn from_bytes(bytes: &[u8]) -> Option<Self> {
        if bytes.len() > MAX_INLINE_BYTES {
            return None;
        }

        let mut result = Self::new();
        result.data[..bytes.len()].copy_from_slice(bytes);
        result.data[23] = bytes.len() as u8;

        Some(result)
    }

    /// Create from heap reference
    #[inline]
    pub fn from_heap(ptr: u64, len: u32) -> Self {
        let mut result = Self::new();
        result.data[0..8].copy_from_slice(&ptr.to_le_bytes());
        result.data[8..12].copy_from_slice(&len.to_le_bytes());
        result.data[23] = Self::HEAP_MARKER;
        result
    }

    /// Check if inline
    #[inline(always)]
    pub const fn is_inline(&self) -> bool {
        self.data[23] != Self::HEAP_MARKER
    }

    /// Get inline bytes (no pointer chase!)
    #[inline(always)]
    pub fn as_inline(&self) -> Option<&[u8]> {
        if !self.is_inline() {
            return None;
        }
        let len = self.data[23] as usize;
        Some(&self.data[..len])
    }

    /// Get with heap resolution
    #[inline]
    pub fn as_bytes_with_heap<'a>(&'a self, heap: &'a [u8]) -> Option<&'a [u8]> {
        if self.is_inline() {
            self.as_inline()
        } else {
            let ptr = u64::from_le_bytes([
                self.data[0],
                self.data[1],
                self.data[2],
                self.data[3],
                self.data[4],
                self.data[5],
                self.data[6],
                self.data[7],
            ]) as usize;
            let len = u32::from_le_bytes([self.data[8], self.data[9], self.data[10], self.data[11]])
                as usize;

            if ptr + len > heap.len() {
                return None;
            }

            Some(&heap[ptr..ptr + len])
        }
    }
}

impl Default for DxInlineBytes {
    fn default() -> Self {
        Self::new()
    }
}

/// Statistics about inline vs heap usage
#[derive(Debug, Default, Clone, Copy)]
pub struct InlineStats {
    /// Number of inline strings
    pub inline_count: usize,
    /// Number of heap strings
    pub heap_count: usize,
    /// Total inline bytes saved
    pub bytes_saved: usize,
}

impl InlineStats {
    /// Calculate inline percentage
    pub fn inline_percentage(&self) -> f64 {
        let total = self.inline_count + self.heap_count;
        if total == 0 {
            return 100.0;
        }
        (self.inline_count as f64 / total as f64) * 100.0
    }
}

/// Collect statistics from a batch of strings
pub fn collect_inline_stats(strings: &[&str]) -> InlineStats {
    let mut stats = InlineStats::default();

    for s in strings {
        if s.len() <= MAX_INLINE_STRING {
            stats.inline_count += 1;
            // Saved bytes = pointer (8) + length (4) - actual length
            stats.bytes_saved += 12usize.saturating_sub(s.len());
        } else {
            stats.heap_count += 1;
        }
    }

    stats
}

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

    #[test]
    fn test_inline_string_short() {
        let s = DxInlineString::from_str("Hello").unwrap();
        assert!(s.is_inline());
        assert_eq!(s.as_inline_str(), Some("Hello"));
        assert_eq!(s.inline_len(), 5);
    }

    #[test]
    fn test_inline_string_max() {
        let long = "12345678901234567890123"; // 23 chars - max inline
        let s = DxInlineString::from_str(long).unwrap();
        assert!(s.is_inline());
        assert_eq!(s.as_inline_str(), Some(long));
    }

    #[test]
    fn test_inline_string_too_long() {
        let too_long = "123456789012345678901234"; // 24 chars - too long
        let s = DxInlineString::from_str(too_long);
        assert!(s.is_none());
    }

    #[test]
    fn test_inline_string_empty() {
        let s = DxInlineString::from_str("").unwrap();
        assert!(s.is_inline());
        assert_eq!(s.as_inline_str(), Some(""));
        assert_eq!(s.inline_len(), 0);
    }

    #[test]
    fn test_heap_string() {
        let s = DxInlineString::from_heap(1000, 50);
        assert!(s.is_heap());
        assert_eq!(s.heap_ptr(), 1000);
        assert_eq!(s.heap_len(), 50);
    }

    #[test]
    fn test_string_comparison() {
        let s1 = DxInlineString::from_str("Test").unwrap();
        let s2 = DxInlineString::from_str("Test").unwrap();
        let s3 = DxInlineString::from_str("Other").unwrap();

        assert!(s1.eq_str("Test"));
        assert!(!s1.eq_str("Other"));
        assert!(s1.eq_inline(&s2));
        assert!(!s1.eq_inline(&s3));
    }

    #[test]
    fn test_with_heap() {
        // Create heap data
        let heap = b"This is the heap data for testing longer strings.";

        // Create inline string that fits
        let inline = DxInlineString::from_str("Short").unwrap();
        assert_eq!(inline.as_str_with_heap(heap), Some("Short"));

        // Create heap reference
        let heap_ref = DxInlineString::from_heap(0, 10);
        assert_eq!(heap_ref.as_str_with_heap(heap), Some("This is th"));
    }

    #[test]
    fn test_inline_bytes() {
        let bytes = DxInlineBytes::from_bytes(&[1, 2, 3, 4, 5]).unwrap();
        assert!(bytes.is_inline());
        assert_eq!(bytes.as_inline(), Some([1, 2, 3, 4, 5].as_slice()));
    }

    #[test]
    fn test_inline_stats() {
        let strings = vec![
            "Hello",
            "World",
            "This is a much longer string that won't fit",
        ];
        let stats = collect_inline_stats(&strings);

        assert_eq!(stats.inline_count, 2);
        assert_eq!(stats.heap_count, 1);
        assert!(stats.inline_percentage() > 60.0);
    }

    #[test]
    fn test_size() {
        // Ensure the inline string is exactly 24 bytes
        assert_eq!(core::mem::size_of::<DxInlineString>(), 24);
        assert_eq!(core::mem::size_of::<DxInlineBytes>(), 24);
    }
}