binseq 0.10.0

use crate::{BitSize, Result, error::WriteError};

/// A zero-copy (borrowed) record used to write sequences to any BINSEQ format.
///
/// # Example
///
/// ```
/// use binseq::SequencingRecordBuilder;
///
/// let record = SequencingRecordBuilder::default()
///     .s_seq(b"ACGTACGT")
///     .s_qual(b"IIIIFFFF")
///     .s_header(b"seq_001")
///     .flag(42)
///     .build()
///     .unwrap();
/// ```
#[derive(Clone, Copy, Default)]
pub struct SequencingRecord<'a> {
    pub s_seq: &'a [u8],
    pub s_qual: Option<&'a [u8]>,
    pub s_header: Option<&'a [u8]>,
    pub x_seq: Option<&'a [u8]>,
    pub x_qual: Option<&'a [u8]>,
    pub x_header: Option<&'a [u8]>,
    pub flag: Option<u64>,
}

impl<'a> SequencingRecord<'a> {
    #[inline]
    #[must_use]
    pub fn new(
        s_seq: &'a [u8],
        s_qual: Option<&'a [u8]>,
        s_header: Option<&'a [u8]>,
        x_seq: Option<&'a [u8]>,
        x_qual: Option<&'a [u8]>,
        x_header: Option<&'a [u8]>,
        flag: Option<u64>,
    ) -> Self {
        Self {
            s_seq,
            s_qual,
            s_header,
            x_seq,
            x_qual,
            x_header,
            flag,
        }
    }

    /// Returns the encoded size of this record for CBQ, given the writer configuration.
    ///
    /// Extra data the writer won't use is not counted.
    #[inline]
    #[must_use]
    pub fn configured_size_cbq(
        &self,
        is_paired: bool,
        has_flags: bool,
        has_headers: bool,
        has_qualities: bool,
    ) -> usize {
        // CBQ uses 2-bit encoding: 4 nucleotides per byte, 32 per u64 word
        const NUCS_PER_WORD: usize = 32;

        let mut size = 0;

        // Sequence size (encoded into u64 words)
        let s_chunks = self.s_seq.len().div_ceil(NUCS_PER_WORD);
        size += s_chunks * 8;

        // Extended sequence (only if writer is configured for paired)
        if is_paired {
            let x_chunks = self.x_seq.map_or(0, |x| x.len().div_ceil(NUCS_PER_WORD));
            size += x_chunks * 8;
        }

        // Flag size (only if writer is configured for flags)
        if has_flags {
            size += 8; // u64
        }

        // Header size (only if writer is configured for headers)
        if has_headers {
            size += self.s_header.map_or(0, <[u8]>::len);
            if is_paired {
                size += self.x_header.map_or(0, <[u8]>::len);
            }
        }

        // Quality size (only if writer is configured for qualities)
        if has_qualities {
            size += self.s_qual.map_or(0, <[u8]>::len);
            if is_paired {
                size += self.x_qual.map_or(0, <[u8]>::len);
            }
        }

        size
    }

    /// Returns the encoded size of this record for VBQ (row-based, length-prefixed),
    /// given the writer configuration.
    ///
    /// Extra data the writer won't use is not counted.
    /// See [`vbq`](crate::vbq) for the record layout.
    #[inline]
    #[must_use]
    pub fn configured_size_vbq(
        &self,
        is_paired: bool,
        has_flags: bool,
        has_headers: bool,
        has_qualities: bool,
        bitsize: BitSize,
    ) -> usize {
        // Calculate how many nucleotides fit per byte for the given bitsize
        let nucs_per_byte = if matches!(bitsize, BitSize::Two) {
            4
        } else {
            2
        };
        // VBQ packs sequences into u64 words
        let nucs_per_word = nucs_per_byte * 8;

        let mut size = 0;

        // Length prefixes: s_len and x_len (always present)
        size += 16; // 2 * u64

        // Flag (8 bytes, if has_flags)
        if has_flags {
            size += 8;
        }

        // Primary sequence (encoded into u64 words)
        let s_chunks = self.s_seq.len().div_ceil(nucs_per_word);
        size += s_chunks * 8;

        // Extended sequence (only if writer is configured for paired)
        if is_paired {
            let x_chunks = self.x_seq.map_or(0, |x| x.len().div_ceil(nucs_per_word));
            size += x_chunks * 8;
        }

        // Quality scores (raw bytes, only if writer configured for qualities)
        if has_qualities {
            size += self.s_qual.map_or(0, <[u8]>::len);
            if is_paired {
                size += self.x_qual.map_or(0, <[u8]>::len);
            }
        }

        // Headers (length prefix + raw bytes, only if writer configured for headers)
        if has_headers {
            if let Some(h) = self.s_header {
                size += 8 + h.len(); // length prefix + header bytes
            }
            if is_paired && let Some(h) = self.x_header {
                size += 8 + h.len(); // length prefix + header bytes
            }
        }

        size
    }

    #[inline]
    #[must_use]
    pub fn is_paired(&self) -> bool {
        self.x_seq.is_some()
    }

    #[inline]
    #[must_use]
    pub fn has_flags(&self) -> bool {
        self.flag.is_some()
    }

    #[inline]
    #[must_use]
    pub fn has_headers(&self) -> bool {
        self.s_header.is_some() || self.x_header.is_some()
    }

    #[inline]
    #[must_use]
    pub fn has_qualities(&self) -> bool {
        self.s_qual.is_some() || self.x_qual.is_some()
    }
}

/// Builder for a [`SequencingRecord`]
///
/// # Example
///
/// ```
/// use binseq::SequencingRecordBuilder;
///
/// // Build a simple unpaired record
/// let record = SequencingRecordBuilder::default()
///     .s_seq(b"ACGTACGT")
///     .build()
///     .unwrap();
///
/// // Build a paired record with quality scores
/// let paired = SequencingRecordBuilder::default()
///     .s_seq(b"ACGTACGT")
///     .s_qual(b"IIIIFFFF")
///     .x_seq(b"TGCATGCA")
///     .x_qual(b"FFFFHHHH")
///     .flag(1)
///     .build()
///     .unwrap();
/// ```
#[derive(Default)]
pub struct SequencingRecordBuilder<'a> {
    s_seq: Option<&'a [u8]>,
    s_qual: Option<&'a [u8]>,
    s_header: Option<&'a [u8]>,
    x_seq: Option<&'a [u8]>,
    x_qual: Option<&'a [u8]>,
    x_header: Option<&'a [u8]>,
    flag: Option<u64>,
}

impl<'a> SequencingRecordBuilder<'a> {
    /// Sets the primary sequence (required)
    #[must_use]
    pub fn s_seq(mut self, s_seq: &'a [u8]) -> Self {
        self.s_seq = Some(s_seq);
        self
    }

    /// Sets the primary quality scores
    #[must_use]
    pub fn s_qual(mut self, s_qual: &'a [u8]) -> Self {
        self.s_qual = Some(s_qual);
        self
    }

    /// Sets the primary quality scores from an Option
    #[must_use]
    pub fn opt_s_qual(mut self, s_qual: Option<&'a [u8]>) -> Self {
        self.s_qual = s_qual;
        self
    }

    /// Sets the primary header
    #[must_use]
    pub fn s_header(mut self, s_header: &'a [u8]) -> Self {
        self.s_header = Some(s_header);
        self
    }

    /// Sets the primary header from an Option
    #[must_use]
    pub fn opt_s_header(mut self, s_header: Option<&'a [u8]>) -> Self {
        self.s_header = s_header;
        self
    }

    /// Sets the extended/paired sequence
    #[must_use]
    pub fn x_seq(mut self, x_seq: &'a [u8]) -> Self {
        self.x_seq = Some(x_seq);
        self
    }

    /// Sets the extended/paired sequence from an Option
    #[must_use]
    pub fn opt_x_seq(mut self, x_seq: Option<&'a [u8]>) -> Self {
        self.x_seq = x_seq;
        self
    }

    /// Sets the extended quality scores
    #[must_use]
    pub fn x_qual(mut self, x_qual: &'a [u8]) -> Self {
        self.x_qual = Some(x_qual);
        self
    }

    /// Sets the extended quality scores from an Option
    #[must_use]
    pub fn opt_x_qual(mut self, x_qual: Option<&'a [u8]>) -> Self {
        self.x_qual = x_qual;
        self
    }

    /// Sets the extended header
    #[must_use]
    pub fn x_header(mut self, x_header: &'a [u8]) -> Self {
        self.x_header = Some(x_header);
        self
    }

    /// Sets the extended header from an Option
    #[must_use]
    pub fn opt_x_header(mut self, x_header: Option<&'a [u8]>) -> Self {
        self.x_header = x_header;
        self
    }

    /// Sets the flag value
    #[must_use]
    pub fn flag(mut self, flag: u64) -> Self {
        self.flag = Some(flag);
        self
    }

    /// Sets the flag value from an Option
    #[must_use]
    pub fn opt_flag(mut self, flag: Option<u64>) -> Self {
        self.flag = flag;
        self
    }

    /// Builds the `SequencingRecord`; errors if `s_seq` is not set
    pub fn build(self) -> Result<SequencingRecord<'a>> {
        let Some(s_seq) = self.s_seq else {
            return Err(WriteError::MissingSequence.into());
        };
        Ok(SequencingRecord {
            s_seq,
            s_qual: self.s_qual,
            s_header: self.s_header,
            x_seq: self.x_seq,
            x_qual: self.x_qual,
            x_header: self.x_header,
            flag: self.flag,
        })
    }
}

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

    // ==================== SequencingRecord::new() and accessors ====================

    #[test]
    fn test_new_constructor() {
        let record = SequencingRecord::new(
            b"ACGT",
            Some(b"IIII"),
            Some(b"s_hdr"),
            Some(b"TGCA"),
            Some(b"FFFF"),
            Some(b"x_hdr"),
            Some(7),
        );
        assert_eq!(record.s_seq, b"ACGT");
        assert_eq!(record.s_qual, Some(b"IIII".as_slice()));
        assert_eq!(record.s_header, Some(b"s_hdr".as_slice()));
        assert_eq!(record.x_seq, Some(b"TGCA".as_slice()));
        assert_eq!(record.x_qual, Some(b"FFFF".as_slice()));
        assert_eq!(record.x_header, Some(b"x_hdr".as_slice()));
        assert_eq!(record.flag, Some(7));
    }

    #[test]
    fn test_new_constructor_minimal() {
        let record = SequencingRecord::new(b"ACGT", None, None, None, None, None, None);
        assert_eq!(record.s_seq, b"ACGT");
        assert_eq!(record.s_qual, None);
        assert_eq!(record.s_header, None);
        assert_eq!(record.x_seq, None);
        assert_eq!(record.x_qual, None);
        assert_eq!(record.x_header, None);
        assert_eq!(record.flag, None);
        assert!(!record.is_paired());
        assert!(!record.has_flags());
        assert!(!record.has_headers());
        assert!(!record.has_qualities());
    }

    // ==================== SequencingRecordBuilder opt_* setters ====================

    #[test]
    fn test_builder_opt_setters() {
        let record = SequencingRecordBuilder::default()
            .s_seq(b"ACGT")
            .opt_s_qual(Some(b"FFFF"))
            .opt_s_header(Some(b"s_hdr"))
            .opt_x_seq(Some(b"TGCA"))
            .opt_x_qual(None)
            .opt_x_header(None)
            .opt_flag(Some(42))
            .build()
            .unwrap();
        // field access and getters are equivalent
        assert_eq!(record.s_qual, Some(b"FFFF".as_slice()));
        assert_eq!(record.s_header, Some(b"s_hdr".as_slice()));
        assert_eq!(record.x_seq, Some(b"TGCA".as_slice()));
        assert_eq!(record.x_qual, None);
        assert_eq!(record.x_header, None);
        assert_eq!(record.flag, Some(42));
    }

    #[test]
    fn test_builder_missing_sequence() {
        let result = SequencingRecordBuilder::default().build();
        assert!(result.is_err());
    }
}