smol-bytes 0.1.5

//! The **Compact** strategy for `Bytes`.
//!
//! This module provides the [`Bytes`](crate::compact::Bytes) type alias configured with the
//! [`Compact`](crate::compact::Compact) strategy,
//! which prioritizes **memory efficiency** by aggressively converting heap allocations back
//! to inline storage whenever possible.
//!
//! # Key Characteristics
//!
//! - **Aggressive inlining**: Automatically converts heap→inline when data fits (≤62 bytes)
//! - **Memory-efficient**: Minimizes heap allocations and memory overhead
//! - **Smart optimization**: Operations like `advance()`, `truncate()`, and `split_to/off()` trigger conversions
//! - **Best for constrained environments**: Ideal for embedded systems and memory-critical applications
//!
//! # When to Use
//!
//! Choose this strategy when:
//!
//! - **Memory is limited**: Embedded systems, microcontrollers, or memory-constrained environments
//! - **Many small buffers**: You work with numerous buffers that frequently shrink over time
//! - **Rare `Bytes` conversions**: You don't often convert to/from `bytes::Bytes`
//! - **Allocation minimization**: You want to minimize heap allocations at the cost of occasional copies
//!
//! # Basic Usage
//!
//! ```rust
//! use smol_bytes::{compact::Bytes, Buf};
//!
//! // Small data (≤62 bytes) is stored inline
//! let small = Bytes::from_static(b"hello world");
//! assert!(!small.is_heap());
//!
//! // Large data starts on heap
//! let mut large = Bytes::from(vec![1u8; 100]);
//! assert!(large.is_heap());
//!
//! // After shrinking, automatically converts to inline!
//! large.advance(70); // 30 bytes remain
//! assert!(!large.is_heap()); // ✓ Now inline!
//! ```
//!
//! # Behavior Details
//!
//! ## Memory Layout (Same as Shared)
//!
//! ```text
//! ┌─────────────────────────────────────────┐
//! │  Bytes (64 bytes on stack)          │
//! ├─────────────────────────────────────────┤
//! │  Variant: Inline (≤62 bytes)            │
//! │  ┌────────────────────────────────────┐ │
//! │  │ [u8; 62] data                      │ │
//! │  │ u8 length                          │ │
//! │  │ u8 current_offset                  │ │
//! │  └────────────────────────────────────┘ │
//! │                                           │
//! │  Variant: Heap (>62 bytes only)         │
//! │  ┌────────────────────────────────────┐ │
//! │  │ bytes::Bytes (Arc<[u8]>)           │ │
//! │  └────────────────────────────────────┘ │
//! └─────────────────────────────────────────┘
//! ```
//!
//! ## Operations and Allocation Behavior
//!
//! ```rust
//! use smol_bytes::{compact::Bytes, Buf};
//!
//! // Start with large heap allocation
//! let mut data = Bytes::from(vec![1u8; 100]);
//! assert!(data.is_heap());
//!
//! // After advance, automatically inlined (Compact strategy)
//! data.advance(70); // 30 bytes remain
//! assert!(!data.is_heap()); // ✓ Converted to inline!
//! ```
//!
//! ## Comparison: Heap→Inline Conversion Triggers
//!
//! | Operation | Before | After | Conversion? |
//! |-----------|--------|-------|-------------|
//! | `advance(n)` | Heap (100 bytes) | Inline (30 bytes) | ✅ Yes (if ≤62 bytes remain) |
//! | `truncate(n)` | Heap (100 bytes) | Inline (30 bytes) | ✅ Yes (if n ≤62) |
//! | `split_to(n)` | Heap (100 bytes) | Inline (remaining) | ✅ Yes (if remaining ≤62) |
//! | `split_off(n)` | Heap (100 bytes) | Inline (first part) | ✅ Yes (if first ≤62) |
//! | `slice(range)` | Heap | Inline | ✅ Yes (if result ≤62) |
//!
//! # Performance Characteristics
//!
//! ## Fast Operations (O(1))
//!
//! - `clone()` when inline - Simple memcpy
//! - `advance()` when staying inline or heap
//! - `truncate()` when staying inline or heap
//! - Operations that don't trigger conversion
//!
//! ## Linear Operations (O(62) - copies up to 62 bytes)
//!
//! - **Heap→Inline conversion** - Copies data to stack (up to 62 bytes)
//! - `advance()` when triggering conversion
//! - `truncate()` when triggering conversion
//! - `split_to()` / `split_off()` when triggering conversion
//! - `into::<Bytes>()` when inline (must copy to heap)
//!
//! **Note**: Since the maximum copy size is fixed at 62 bytes, these operations are very fast in practice!
//!
//! # Examples
//!
//! ## Stream Processing with Automatic Inlining
//!
//! ```rust
//! use smol_bytes::{compact::Bytes, Buf};
//!
//! // Process incoming stream
//! let mut buffer = Bytes::from(vec![0u8; 1024]);
//! assert!(buffer.is_heap());
//!
//! // As we consume data, it automatically inlines
//! buffer.advance(1000); // 24 bytes remain
//! assert!(!buffer.is_heap()); // Saved memory!
//! ```
//!
//! ## Memory-Efficient Buffer Pool
//!
//! ```rust
//! use smol_bytes::compact::Bytes;
//!
//! struct BufferPool {
//!     buffers: Vec<Bytes>,
//! }
//!
//! impl BufferPool {
//!     fn new() -> Self {
//!         Self { buffers: Vec::new() }
//!     }
//!
//!     fn add(&mut self, data: Vec<u8>) {
//!         // Automatically inlines if small enough
//!         self.buffers.push(Bytes::from(data));
//!     }
//!
//!     fn total_heap_allocations(&self) -> usize {
//!         self.buffers.iter()
//!             .filter(|b| b.is_heap())
//!             .count()
//!     }
//! }
//!
//! let mut pool = BufferPool::new();
//!
//! // Add mix of small and large buffers
//! pool.add(vec![1; 10]);  // Inline
//! pool.add(vec![2; 30]);  // Inline
//! pool.add(vec![3; 100]); // Heap
//!
//! // Only one heap allocation!
//! assert_eq!(pool.total_heap_allocations(), 1);
//! ```
//!
//! ## Truncate for Memory Savings
//!
//! ```rust
//! use smol_bytes::compact::Bytes;
//!
//! let mut data = Bytes::from(vec![1u8; 100]);
//! assert!(data.is_heap());
//!
//! // Truncate to small size - automatically inlines
//! data.truncate(20);
//! assert!(!data.is_heap());
//! assert_eq!(data.len(), 20);
//! ```
//!
//! ## Smart Split Operations
//!
//! ```rust
//! use smol_bytes::compact::Bytes;
//!
//! let mut data = Bytes::from(vec![1u8; 100]);
//!
//! // Split off small portion - both parts optimize
//! let first = data.split_to(30);  // first: 30 bytes (inline)
//! // data: 70 bytes (heap)
//!
//! assert!(!first.is_heap()); // Automatically inlined!
//! assert!(data.is_heap());    // Still too large for inline
//! ```
//!
//! # Trade-offs vs Shared ImmutableStorage
//!
//! ## Advantages
//!
//! - ✅ **Lower memory usage**: Fewer heap allocations
//! - ✅ **Better cache locality**: More data on stack
//! - ✅ **Fewer allocations**: Automatic heap→inline conversion
//! - ✅ **Simpler deallocation**: Inline data needs no cleanup
//!
//! ## Disadvantages
//!
//! - ❌ **Conversion overhead**: O(62) copy when heap→inline (up to 62 bytes)
//! - ❌ **Bytes conversion cost**: Must copy when inline
//! - ❌ **More copies**: Cloning inline data copies all bytes
//! - ❌ **No zero-copy for small data**: Inline can't share with `Bytes`
//!
//! # Benchmarks
//!
//! Typical performance characteristics (on x86_64):
//!
//! - **Heap→Inline conversion**: ~10-20ns for 62 bytes
//! - **Inline clone**: ~5-10ns for 62 bytes
//! - **Memory saved**: 32 bytes per buffer (no heap overhead)
//!
//! # Migration Guide
//!
//! If you're currently using `shared::Bytes` and considering switching:
//!
//! ```rust
//! // Before (Shared strategy)
//! use smol_bytes::{shared, compact, Buf};
//!
//! let mut data = shared::Bytes::from(vec![1u8; 100]);
//! data.advance(70); // Still heap-allocated
//! let bytes: bytes::Bytes = data.into(); // Zero-copy ✓
//!
//! // After (Compact strategy)
//!
//! let mut data = compact::Bytes::from(vec![1u8; 100]);
//! data.advance(70); // Now inline! Saved memory ✓
//! let bytes: bytes::Bytes = data.into(); // Copies 30 bytes (still fast!)
//! ```
//!
//! **Rule of thumb**: If you convert to `Bytes` more than once per buffer lifetime,
//! use `Shared`. If memory is more important than conversion speed, use `Compact`.

use super::ImmutableStorage;
use crate::{
  buffer::{Buffer, INLINE_CAP},
  bytes::raw::{RawBytes, Repr},
  error::*,
};
use bytes::Buf;
use core::mem;
use core::ops::RangeBounds;

#[cfg(feature = "pyo3")]
mod python;
#[cfg(feature = "pyo3")]
pub use python::PyCompactBytes;

#[cfg(feature = "wasm")]
mod wasm;

/// A strategy that aggressively inlines data to minimize heap allocations and memory usage.
///
/// # Overview
///
/// The `Compact` strategy prioritizes **memory efficiency** over conversion speed. It
/// automatically converts heap-allocated data back to inline storage whenever possible
/// (when data size ≤62 bytes) after operations like `advance()`, `truncate()`, or
/// `split_to/off()`.
///
/// This makes `Compact` ideal when:
/// - Memory footprint is critical
/// - You want to minimize heap allocations
/// - You're working with small, frequently-modified buffers
/// - Conversions to `Bytes` are rare
///
/// # Behavior
///
/// - **Inline → Inline**: Small data stays inline (≤62 bytes)
/// - **Heap → Inline**: Automatically inlines when data shrinks ≤62 bytes
/// - **Smart optimization**: Operations like `advance()`, `truncate()`, and `split_to/off()`
///   can trigger heap→inline conversion
///
/// ## Example
///
/// ```rust
/// use smol_bytes::compact::Bytes;
/// use bytes::Buf;
///
/// // Create heap-allocated bytes (>62 bytes)
/// let mut data = Bytes::from(vec![1u8; 100]);
/// assert!(data.is_heap());
///
/// // Advance past most data
/// data.advance(70); // Only 30 bytes remain
///
/// // Automatically converted to inline! (Compact strategy saves memory)
/// assert!(!data.is_heap());
/// ```
///
/// # Comparison with Shared
///
/// | Operation | Compact | Shared |
/// |-----------|---------|--------|
/// | Heap→Inline on shrink | ✅ Yes | ❌ No |
/// | Bytes conversion | 📋 May copy | ⚡ Zero-copy |
/// | Memory usage | 💾 Lower | 💾 Higher |
/// | Best for | Memory efficiency | Speed, Bytes interop |
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Compact(());

impl From<bytes::Bytes> for RawBytes<Compact> {
  fn from(bytes: bytes::Bytes) -> Self {
    if bytes.len() <= INLINE_CAP {
      // SAFETY: length checked against INLINE_CAP above.
      Self::inline(unsafe { Buffer::copy_from_slice(&bytes) })
    } else {
      Self::heap(bytes)
    }
  }
}

impl ImmutableStorage for RawBytes<Compact> {
  fn slice(&self, range: impl RangeBounds<usize>) -> Self {
    self.try_slice(range).unwrap_or_else(|e| panic!("{e}"))
  }

  fn try_slice(&self, range: impl RangeBounds<usize>) -> Result<Self, crate::RangeOutOfBounds>
  where
    Self: Sized,
  {
    match &self.repr {
      Repr::Inline(storage) => storage.try_slice(range).map(Self::inline),
      Repr::Heap(bytes) => {
        let len = bytes.len();
        let (begin, end) = normalize_range(range, len)?;

        let slen = end - begin;
        if slen == 0 {
          return Ok(Self::new());
        }

        if slen <= INLINE_CAP {
          // SAFETY: `normalize_range` proves the source range is initialized,
          // and `slen <= INLINE_CAP` proves it fits in `Buffer`.
          return Ok(Self::inline(unsafe {
            Buffer::copy_from_slice(&self.as_slice()[begin..end])
          }));
        }

        Ok(Self::heap(bytes.slice(begin..end)))
      }
    }
  }

  fn split_to(&mut self, at: usize) -> Self {
    let len = self.len();
    if at == len {
      return mem::take(self);
    }
    if at == 0 {
      return Self::new();
    }
    assert!(at <= len, "split_to out of bounds: {:?} <= {:?}", at, len);

    let remaining = len - at;

    match &mut self.repr {
      Repr::Inline(storage) => {
        Self::inline(storage.try_split_to(at).expect("already checked bounds"))
      }
      Repr::Heap(bytes) => {
        // Build the returned prefix.
        let ret = if at <= INLINE_CAP {
          // SAFETY: at <= INLINE_CAP, checked above.
          Self::inline(unsafe { Buffer::copy_from_slice(&bytes[..at]) })
        } else {
          // Both halves are large — use native split (avoids clone+truncate).
          // bytes::Bytes::split_to advances self for us, so we only need
          // to check for compact-inline conversion below.
          let prefix = bytes.split_to(at);
          // If self's remainder fits inline, compact-convert it.
          if remaining <= INLINE_CAP {
            // SAFETY: remaining <= INLINE_CAP, checked above.
            let repr = Repr::inline(unsafe { Buffer::copy_from_slice(&bytes[..]) });
            let _ = mem::replace(&mut self.repr, repr);
          }
          return Self::heap(prefix);
        };

        // Prefix was copied into inline; now advance or compact self.
        if remaining <= INLINE_CAP {
          // SAFETY: remaining <= INLINE_CAP, checked above.
          let repr = Repr::inline(unsafe { Buffer::copy_from_slice(&bytes[at..]) });
          let _ = mem::replace(&mut self.repr, repr);
        } else {
          bytes.advance(at);
        }
        ret
      }
    }
  }

  fn split_off(&mut self, at: usize) -> Self {
    let len = self.len();
    if at == len {
      return Self::new();
    }
    if at == 0 {
      return mem::take(self);
    }
    assert!(at <= len, "split_off out of bounds: {:?} <= {:?}", at, len);

    let output_size = len - at;

    match &mut self.repr {
      Repr::Inline(storage) => {
        Self::inline(storage.try_split_off(at).expect("already checked bounds"))
      }
      Repr::Heap(bytes) => {
        // Build the returned tail.
        let ret = if output_size <= INLINE_CAP {
          // SAFETY: output_size <= INLINE_CAP, checked above.
          Self::inline(unsafe { Buffer::copy_from_slice(&bytes[at..]) })
        } else {
          // Both halves are large — use native split_off (avoids clone+advance).
          // bytes::Bytes::split_off truncates self for us.
          let tail = bytes.split_off(at);
          // If self fits inline after truncation, compact-convert it.
          if at <= INLINE_CAP {
            // SAFETY: at <= INLINE_CAP, checked above.
            let repr = Repr::inline(unsafe { Buffer::copy_from_slice(&bytes[..]) });
            let _ = mem::replace(&mut self.repr, repr);
          }
          return Self::heap(tail);
        };

        // Tail was copied into inline; now truncate or compact self.
        if at <= INLINE_CAP {
          // SAFETY: at <= INLINE_CAP, checked above.
          let repr = Repr::inline(unsafe { Buffer::copy_from_slice(&bytes[..at]) });
          let _ = mem::replace(&mut self.repr, repr);
        } else {
          bytes.truncate(at);
        }
        ret
      }
    }
  }

  fn truncate(&mut self, new_len: usize) {
    if new_len >= self.len() {
      return;
    }

    match &mut self.repr {
      Repr::Inline(storage) => {
        storage.truncate(new_len);
      }
      Repr::Heap(bytes) => {
        if new_len <= INLINE_CAP {
          // SAFETY: the early return proves `new_len < bytes.len()`, and
          // `new_len <= INLINE_CAP` proves the initialized prefix fits inline.
          let repr = Repr::inline(unsafe { Buffer::copy_from_slice(&bytes[..new_len]) });
          let _ = mem::replace(&mut self.repr, repr);
        } else {
          bytes.truncate(new_len);
        }
      }
    }
  }

  fn advance(&mut self, cnt: usize) {
    match &mut self.repr {
      Repr::Inline(storage) => {
        storage.advance(cnt);
      }
      Repr::Heap(bytes) => {
        if cnt == 0 {
          return;
        }

        // check if we can make inline after advance
        let len = bytes.len();
        assert!(
          cnt <= len,
          "cannot advance past `remaining`: {:?} <= {:?}",
          cnt,
          len,
        );

        let remaining = len - cnt;
        if remaining <= INLINE_CAP {
          // SAFETY: bounds checked above, and we are slicing within inline capacity.
          let repr = Repr::inline(unsafe { Buffer::copy_from_slice(&bytes[cnt..]) });
          let _ = mem::replace(&mut self.repr, repr);
        } else {
          bytes.advance(cnt);
        }
      }
    }
  }

  fn copy_to_bytes(&mut self, len: usize) -> bytes::Bytes {
    self.split_to(len).into()
  }

  fn clear(&mut self) {
    // Compact keeps heap storage only for payloads that cannot fit inline;
    // clearing drops the allocation instead of retaining an empty heap handle.
    *self = Self::new();
  }
}

/// A memory-efficient byte buffer that aggressively inlines data to minimize heap usage.
///
/// This type alias uses the [`Compact`] strategy.
///
/// # When to use
///
/// Use `Bytes` (with `Compact` strategy) when:
/// - Memory footprint is critical
/// - You're working with small, frequently-modified buffers
/// - Heap allocations should be minimized
/// - Conversions to `bytes::Bytes` are infrequent
///
/// For applications that frequently convert to/from `Bytes`, consider [`shared::Bytes`](super::shared::Bytes) instead.
///
/// ## Example
///
/// ```rust
/// use smol_bytes::compact::Bytes;
/// use bytes::Buf;
///
/// let mut data = Bytes::from(vec![1u8; 100]);
/// assert!(data.is_heap());
///
/// // After advancing, automatically converts to inline
/// data.advance(70);
/// assert!(!data.is_heap()); // Saved memory!
/// ```
pub type Bytes = RawBytes<Compact>;

/// A compact, memory-efficient UTF-8 string type alias using the [`Compact`] strategy.
///
/// This is the compact-strategy immutable UTF-8 wrapper.
pub type Utf8Bytes = crate::utf8_bytes::Utf8Bytes<Compact>;