zexc 1.2.1

zex native lossless compressor — CLI zexc, library zexc, files *.zex
Documentation
//! Frame-level helpers: parse info without full decompression.

use crate::format::block::{BlockHeader, BlockType};
use crate::format::header::{HEADER_SIZE, ZexHeader};
use crate::{Error, Result};
use std::io::Read;

/// High-level frame metadata (for `zex info`).
#[derive(Debug, Clone)]
pub struct FrameInfo {
    /// Parsed header.
    pub header: ZexHeader,
    /// Number of data blocks (excluding End).
    pub block_count: usize,
    /// Total compressed payload bytes (sum of block payloads).
    pub compressed_payload: u64,
    /// Per-block type counts: (Raw, Zex).
    pub type_counts: [usize; 2],
}

/// Streaming frame reader for inspection / progressive decode.
pub struct FrameReader<R: Read> {
    reader: R,
    /// Header once read.
    pub header: Option<ZexHeader>,
}

impl<R: Read> FrameReader<R> {
    /// Wrap a reader.
    pub fn new(reader: R) -> Self {
        Self {
            reader,
            header: None,
        }
    }

    /// Read and validate the frame header.
    pub fn read_header(&mut self) -> Result<&ZexHeader> {
        if self.header.is_none() {
            let h = ZexHeader::read_from(&mut self.reader)?;
            self.header = Some(h);
        }
        Ok(self.header.as_ref().unwrap())
    }

    /// Read next block header. `None` when End block is reached.
    pub fn next_block_header(&mut self) -> Result<Option<BlockHeader>> {
        let bh = BlockHeader::read_from(&mut self.reader)?;
        if bh.block_type == BlockType::End {
            return Ok(None);
        }
        Ok(Some(bh))
    }

    /// Read exactly `n` payload bytes.
    pub fn read_payload(&mut self, n: usize) -> Result<Vec<u8>> {
        let mut buf = vec![0u8; n];
        self.reader.read_exact(&mut buf)?;
        Ok(buf)
    }

    /// Scan the whole frame for [`FrameInfo`] (consumes remaining stream).
    pub fn info(mut self) -> Result<FrameInfo> {
        let _ = self.read_header()?;
        let mut block_count = 0usize;
        let mut compressed_payload = 0u64;
        let mut type_counts = [0usize; 2];

        loop {
            let bh = BlockHeader::read_from(&mut self.reader)?;
            if bh.block_type == BlockType::End {
                break;
            }
            block_count += 1;
            compressed_payload += bh.compressed_size as u64;
            match bh.block_type {
                BlockType::Raw => type_counts[0] += 1,
                BlockType::Zex => type_counts[1] += 1,
                BlockType::End => {}
            }
            let mut skip = vec![0u8; bh.compressed_size as usize];
            self.reader.read_exact(&mut skip)?;
        }

        Ok(FrameInfo {
            header: self.header.take().unwrap(),
            block_count,
            compressed_payload,
            type_counts,
        })
    }
}

/// Probe first bytes for ZEX magic.
pub fn is_zex(data: &[u8]) -> bool {
    data.len() >= 4 && data[..4] == crate::format::header::MAGIC
}

/// Content size from header if present.
pub fn content_size_from_prefix(data: &[u8]) -> Result<Option<u64>> {
    if data.len() < HEADER_SIZE {
        return Err(Error::InvalidHeader("too short".into()));
    }
    let h = ZexHeader::from_bytes(&data[..HEADER_SIZE])?;
    if h.content_size == u64::MAX {
        Ok(None)
    } else {
        Ok(Some(h.content_size))
    }
}