ferro-hgvs 1.0.0

//! Interval types for different coordinate systems
//!
//! Intervals represent ranges of positions for multi-position variants
//! like deletions, duplications, and insertions.

use super::location::{CdsPos, GenomePos, ProtPos, RnaPos, TxPos};
use super::uncertainty::Mu;
use serde::{Deserialize, Serialize};
use std::fmt;

/// Represents a boundary position that may be a single position or a range
///
/// In HGVS notation, interval boundaries can be:
/// - A single position: `100` (certain) or `(100)` (uncertain) or `?` (unknown)
/// - A range: `(100_200)` meaning the boundary is somewhere between 100 and 200
///
/// This is used for complex uncertain intervals like:
/// - `c.(4185+1_4186-1)_(4357+1_4358-1)del` - exon deletion with uncertain intronic breakpoints
/// - `g.(?_43044294)_(43125364_?)del` - large deletion with uncertain outer boundaries
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum UncertainBoundary<T> {
    /// A single position (may be certain, uncertain, or unknown)
    Single(Mu<T>),
    /// A range indicating the boundary is somewhere within this range
    /// The parentheses wrap the entire range: (start_end)
    Range {
        /// Start of the range (may be unknown)
        start: Mu<T>,
        /// End of the range (may be unknown)
        end: Mu<T>,
    },
}

impl<T> UncertainBoundary<T> {
    /// Create a certain single boundary
    pub fn certain(pos: T) -> Self {
        Self::Single(Mu::Certain(pos))
    }

    /// Create an uncertain single boundary (position in parentheses)
    pub fn uncertain(pos: T) -> Self {
        Self::Single(Mu::Uncertain(pos))
    }

    /// Create an unknown boundary (?)
    pub fn unknown() -> Self {
        Self::Single(Mu::Unknown)
    }

    /// Create a range boundary (start_end)
    pub fn range(start: Mu<T>, end: Mu<T>) -> Self {
        Self::Range { start, end }
    }

    /// Check if this is a single position boundary
    pub fn is_single(&self) -> bool {
        matches!(self, Self::Single(_))
    }

    /// Check if this is a range boundary
    pub fn is_range(&self) -> bool {
        matches!(self, Self::Range { .. })
    }

    /// Get the inner Mu<T> if this is a single position
    pub fn as_single(&self) -> Option<&Mu<T>> {
        match self {
            Self::Single(mu) => Some(mu),
            Self::Range { .. } => None,
        }
    }

    /// Get the inner position value if this is a single certain or uncertain position
    /// Returns None for unknown positions or range boundaries
    pub fn inner(&self) -> Option<&T> {
        match self {
            Self::Single(mu) => mu.inner(),
            Self::Range { .. } => None,
        }
    }
}

impl<T: Clone> UncertainBoundary<T> {
    /// Convert from a simple Mu<T> to UncertainBoundary
    pub fn from_mu(mu: Mu<T>) -> Self {
        Self::Single(mu)
    }
}

impl<T> UncertainBoundary<T> {
    /// Map over the inner position(s) by reference, preserving the
    /// Single/Range shape and each `Mu`'s certainty. Used to lift a
    /// `UncertainBoundary<ProtPos>` into a styled boundary for rendering.
    pub fn map_ref<U, F: Fn(&T) -> U>(&self, f: F) -> UncertainBoundary<U> {
        match self {
            Self::Single(mu) => UncertainBoundary::Single(mu.map_ref(&f)),
            Self::Range { start, end } => UncertainBoundary::Range {
                start: start.map_ref(&f),
                end: end.map_ref(&f),
            },
        }
    }
}

impl<T: fmt::Display> fmt::Display for UncertainBoundary<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Single(mu) => write!(f, "{}", mu),
            Self::Range { start, end } => {
                // Range boundaries are always wrapped in parentheses
                write!(f, "({}_{}", start, end)?;
                write!(f, ")")
            }
        }
    }
}

/// An interval with complex uncertain boundaries
///
/// This extends the basic Interval type to support complex HGVS patterns
/// where boundaries can be ranges rather than single positions.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ComplexInterval<T> {
    pub start: UncertainBoundary<T>,
    pub end: UncertainBoundary<T>,
}

impl<T> ComplexInterval<T> {
    pub fn new(start: UncertainBoundary<T>, end: UncertainBoundary<T>) -> Self {
        Self { start, end }
    }
}

impl<T: fmt::Display> fmt::Display for ComplexInterval<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}_{}", self.start, self.end)
    }
}

/// Type aliases for complex intervals
pub type ComplexCdsInterval = ComplexInterval<CdsPos>;
pub type ComplexGenomeInterval = ComplexInterval<GenomePos>;

/// Generic interval with start and end positions
///
/// Supports both simple intervals (single positions) and complex intervals
/// (range boundaries like `(100+1_101-1)_(200+1_201-1)`).
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Interval<T> {
    pub start: UncertainBoundary<T>,
    pub end: UncertainBoundary<T>,
}

impl<T> Interval<T> {
    pub fn new(start: T, end: T) -> Self {
        Self {
            start: UncertainBoundary::certain(start),
            end: UncertainBoundary::certain(end),
        }
    }

    pub fn point(pos: T) -> Self
    where
        T: Clone,
    {
        Self {
            start: UncertainBoundary::certain(pos.clone()),
            end: UncertainBoundary::certain(pos),
        }
    }

    /// Create an interval with simple uncertainty (Mu<T> for each position)
    pub fn with_uncertainty(start: Mu<T>, end: Mu<T>) -> Self {
        Self {
            start: UncertainBoundary::Single(start),
            end: UncertainBoundary::Single(end),
        }
    }

    /// Create an interval with complex boundaries
    pub fn with_complex_boundaries(start: UncertainBoundary<T>, end: UncertainBoundary<T>) -> Self {
        Self { start, end }
    }

    /// Check if this interval has any complex (range) boundaries
    pub fn has_complex_boundaries(&self) -> bool {
        self.start.is_range() || self.end.is_range()
    }
}

impl<T: fmt::Display + PartialEq> fmt::Display for Interval<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // For simple single-position boundaries, check if it's a point variant
        match (&self.start, &self.end) {
            (UncertainBoundary::Single(start_mu), UncertainBoundary::Single(end_mu)) => {
                // Check if both are unknown (?) - this is a point at unknown position
                if start_mu.is_unknown() && end_mu.is_unknown() {
                    return write!(f, "{}", self.start);
                }
                match (start_mu.inner(), end_mu.inner()) {
                    (Some(start), Some(end))
                        if start == end && start_mu.is_certain() && end_mu.is_certain() =>
                    {
                        // Point variant - show single position
                        write!(f, "{}", self.start)
                    }
                    _ => write!(f, "{}_{}", self.start, self.end),
                }
            }
            // Single uncertain position with bounded range: (a_b) describes one
            // position somewhere in [a,b], encoded as the same `Range` on both
            // sides of the Interval. Emit `(a_b)` once, not `(a_b)_(a_b)`.
            (UncertainBoundary::Range { .. }, UncertainBoundary::Range { .. })
                if self.start == self.end =>
            {
                write!(f, "{}", self.start)
            }
            // Complex boundaries or mixed - always show both
            _ => write!(f, "{}_{}", self.start, self.end),
        }
    }
}

/// Genomic interval (g. coordinates)
pub type GenomeInterval = Interval<GenomePos>;

/// CDS interval (c. coordinates)
pub type CdsInterval = Interval<CdsPos>;

/// Transcript interval (n. coordinates)
pub type TxInterval = Interval<TxPos>;

/// RNA interval (r. coordinates)
pub type RnaInterval = Interval<RnaPos>;

/// Protein interval (p. coordinates)
pub type ProtInterval = Interval<ProtPos>;

/// Return `true` when a [`GenomeInterval`] wraps around a circular contig,
/// i.e., the start base is numerically greater than the end base.
///
/// Returns `false` when either endpoint is `Unknown` (`?`) or a range
/// boundary — in those cases the normal conversion path surfaces whatever
/// error it would produce. Uncertain-but-numeric positions (`(123)`) are
/// resolved like any other numeric position.
pub(crate) fn interval_is_wraparound(loc: &GenomeInterval) -> bool {
    match (loc.start.inner(), loc.end.inner()) {
        (Some(start), Some(end)) => start.base > end.base,
        _ => false,
    }
}

impl GenomeInterval {
    /// Get the length of this interval (returns 0 if either position is unknown)
    pub fn len(&self) -> u64 {
        match (self.start.inner(), self.end.inner()) {
            // Use saturating_add to prevent overflow at u64::MAX
            (Some(start), Some(end)) if end.base >= start.base => {
                (end.base - start.base).saturating_add(1)
            }
            // Unknown positions or end < start result in length 0
            _ => 0,
        }
    }

    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }
}

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

    #[test]
    fn test_genome_interval_display() {
        let interval = GenomeInterval::new(GenomePos::new(100), GenomePos::new(200));
        assert_eq!(format!("{}", interval), "100_200");
    }

    #[test]
    fn test_point_interval_display() {
        let interval = GenomeInterval::point(GenomePos::new(100));
        assert_eq!(format!("{}", interval), "100");
    }

    #[test]
    fn test_cds_interval_display() {
        let interval = CdsInterval::new(CdsPos::new(100), CdsPos::with_offset(100, 5));
        assert_eq!(format!("{}", interval), "100_100+5");
    }

    #[test]
    fn test_interval_length() {
        let interval = GenomeInterval::new(GenomePos::new(100), GenomePos::new(105));
        assert_eq!(interval.len(), 6);
    }

    #[test]
    fn test_uncertain_interval() {
        let interval = GenomeInterval::with_uncertainty(
            Mu::Uncertain(GenomePos::new(100)),
            Mu::Uncertain(GenomePos::new(200)),
        );
        assert_eq!(format!("{}", interval), "(100)_(200)");
    }
}

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

    #[test]
    fn test_uncertain_boundary_map_ref() {
        let single = UncertainBoundary::certain(5u32);
        assert_eq!(single.map_ref(|n| n * 2), UncertainBoundary::certain(10u32));

        let range = UncertainBoundary::range(Mu::Certain(1u32), Mu::Unknown);
        match range.map_ref(|n| n + 100) {
            UncertainBoundary::Range { start, end } => {
                assert_eq!(start, Mu::Certain(101));
                assert_eq!(end, Mu::Unknown);
            }
            _ => panic!("expected range"),
        }

        // The `Uncertain` (parenthesized-position) variant must also survive
        // map_ref with its inner value mapped — the case above only exercised
        // `Certain`/`Unknown`.
        let uncertain_range = UncertainBoundary::range(Mu::Uncertain(7u32), Mu::Certain(9u32));
        match uncertain_range.map_ref(|n| n + 1) {
            UncertainBoundary::Range { start, end } => {
                assert_eq!(start, Mu::Uncertain(8));
                assert_eq!(end, Mu::Certain(10));
            }
            _ => panic!("expected range"),
        }

        let single_uncertain = UncertainBoundary::Single(Mu::Uncertain(3u32));
        assert_eq!(
            single_uncertain.map_ref(|n| n * 10),
            UncertainBoundary::Single(Mu::Uncertain(30)),
        );
    }
}