randomio/block/

block.rs

/// Data block at a specific offset
///
/// The buffer type `B` is generic and can be any type that implements
/// `AsRef<[u8]> + Send`, allowing for:
/// - `bytes::Bytes` — zero-copy slices
/// - `Vec<u8>` — owned buffers
/// - `Box<[u8]>` — boxed slices
/// - DMA buffers
/// - Custom zero-copy types
///
/// The default buffer type is `bytes::Bytes`, which provides zero-copy
/// slices for I/O operations.
#[cfg(feature = "bytes")]
pub struct Block<B = bytes::Bytes> {
    /// Absolute byte offset where the block starts
    pub offset: u64,
    /// Buffer containing the block data
    pub data: B,
}

/// Data block at a specific offset
///
/// The buffer type `B` is generic and can be any type that implements
/// `AsRef<[u8]> + Send`, allowing for:
/// - `Vec<u8>` — owned buffers
/// - `Box<[u8]>` — boxed slices
/// - DMA buffers
/// - Custom zero-copy types
#[cfg(not(feature = "bytes"))]
pub struct Block<B> {
    /// Absolute byte offset where the block starts
    pub offset: u64,
    /// Buffer containing the block data
    pub data: B,
}

impl<B: AsRef<[u8]>> Block<B> {
    /// Create a new block at the given offset with the given data
    #[inline]
    pub const fn new(offset: u64, data: B) -> Self {
        Self { offset, data }
    }

    /// Returns the range covered by this block
    #[inline]
    pub fn range(&self) -> crate::Range {
        let len = self.data.as_ref().len() as u64;
        crate::Range::new(self.offset, self.offset.saturating_add(len))
    }

    /// Returns the length of the block data
    #[inline]
    pub fn len(&self) -> usize {
        self.data.as_ref().len()
    }

    /// Returns true if the block has no data
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.data.as_ref().is_empty()
    }
}

impl<B: AsRef<[u8]>> AsRef<[u8]> for Block<B> {
    #[inline]
    fn as_ref(&self) -> &[u8] {
        self.data.as_ref()
    }
}

impl<B: AsRef<[u8]> + Clone> Clone for Block<B> {
    fn clone(&self) -> Self {
        Self {
            offset: self.offset,
            data: self.data.clone(),
        }
    }
}

impl<B: AsRef<[u8]> + core::fmt::Debug> core::fmt::Debug for Block<B> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("Block")
            .field("offset", &self.offset)
            .field("len", &self.len())
            .field("data", &self.data)
            .finish()
    }
}

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

    #[test]
    fn test_block_basic() {
        let data = alloc::vec![1, 2, 3, 4, 5];
        let block = Block::new(100, data);

        assert_eq!(block.offset, 100);
        assert_eq!(block.len(), 5);
        assert!(!block.is_empty());
        assert_eq!(block.as_ref(), &[1, 2, 3, 4, 5]);
    }

    #[test]
    fn test_block_range() {
        let block = Block::new(100, alloc::vec![1, 2, 3, 4, 5]);
        let range = block.range();

        assert_eq!(range.start, 100);
        assert_eq!(range.end, 105);
    }

    #[test]
    fn test_block_empty() {
        let block = Block::new(100, alloc::vec::Vec::<u8>::new());
        assert!(block.is_empty());
        assert_eq!(block.len(), 0);
        assert_eq!(block.range().start, 100);
        assert_eq!(block.range().end, 100);
    }

    #[test]
    fn test_block_clone() {
        let block = Block::new(50, alloc::vec![10, 20, 30]);
        let cloned = block.clone();

        assert_eq!(cloned.offset, block.offset);
        assert_eq!(cloned.len(), block.len());
        assert_eq!(cloned.as_ref(), block.as_ref());
    }

    #[test]
    fn test_block_zero_offset() {
        let block = Block::new(0, alloc::vec![1, 2, 3]);
        assert_eq!(block.offset, 0);
        assert_eq!(block.range().start, 0);
        assert_eq!(block.range().end, 3);
    }

    #[test]
    fn test_block_large_offset() {
        let large_offset = u64::MAX - 100;
        let block = Block::new(large_offset, alloc::vec![1, 2, 3]);
        assert_eq!(block.offset, large_offset);
        assert_eq!(block.range().start, large_offset);
    }

    #[test]
    fn test_block_single_byte() {
        let block = Block::new(1000, alloc::vec![42]);
        assert_eq!(block.len(), 1);
        assert_eq!(block.as_ref(), &[42]);
        assert!(!block.is_empty());
    }

    #[test]
    fn test_block_box_slice() {
        let data: alloc::boxed::Box<[u8]> = alloc::vec![1, 2, 3, 4].into_boxed_slice();
        let block = Block::new(500, data);

        assert_eq!(block.offset, 500);
        assert_eq!(block.len(), 4);
        assert_eq!(block.as_ref(), &[1, 2, 3, 4]);
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_block_debug() {
        let block = Block::new(123, vec![1, 2, 3]);
        let debug_str = format!("{:?}", block);
        assert!(debug_str.contains("Block"));
        assert!(debug_str.contains("123")); // offset
        assert!(debug_str.contains("3")); // len
    }

    #[cfg(feature = "bytes")]
    #[test]
    fn test_block_with_bytes() {
        use bytes::Bytes;

        let data = Bytes::from_static(b"hello world");
        let block = Block::new(2000, data);

        assert_eq!(block.offset, 2000);
        assert_eq!(block.len(), 11);
        assert_eq!(block.as_ref(), b"hello world");
        assert_eq!(block.range(), crate::Range::new(2000, 2011));
    }

    #[cfg(feature = "bytes")]
    #[test]
    fn test_block_bytes_clone() {
        use bytes::Bytes;

        let data = Bytes::from_static(b"test data");
        let block = Block::new(100, data);
        let cloned = block.clone();

        // Bytes cloning is shallow (cheap)
        assert_eq!(cloned.offset, block.offset);
        assert_eq!(cloned.as_ref(), block.as_ref());
    }
}