sipha_core/

span.rs

//! Default span implementations for common use cases.

use std::ops::Range;

/// Span type that tracks a byte range.
///
/// # Example
///
/// ```rust
/// use sipha_core::span::Span;
///
/// let span = Span::new(10, 20);
/// assert_eq!(span.start(), 10);
/// assert_eq!(span.end(), 20);
/// ```
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct Span {
    /// Start byte offset (inclusive).
    pub start: usize,
    /// End byte offset (exclusive).
    pub end: usize,
}

impl Default for Span {
    #[inline]
    fn default() -> Self {
        Self { start: 0, end: 0 }
    }
}

impl Span {
    /// Create a new span with start/end positions.
    ///
    /// # Panics
    ///
    /// Panics if `end < start` in debug mode.
    #[inline]
    pub fn new(start: usize, end: usize) -> Self {
        debug_assert!(end >= start, "span end must be >= start");
        Self { start, end }
    }

    /// Create a span from a range.
    #[inline]
    pub fn from_range(range: Range<usize>) -> Self {
        Self::new(range.start, range.end)
    }

    /// Create an empty span at the given position.
    #[inline]
    pub fn empty(pos: usize) -> Self {
        Self {
            start: pos,
            end: pos,
        }
    }

    /// Get the range of this span.
    #[inline]
    pub fn range(&self) -> Range<usize> {
        self.start..self.end
    }

    /// Get the start byte offset.
    #[inline]
    pub fn start(&self) -> usize {
        self.start
    }

    /// Get the end byte offset.
    #[inline]
    pub fn end(&self) -> usize {
        self.end
    }

    /// Get the length of the span in bytes.
    #[inline]
    pub fn len(&self) -> usize {
        self.end - self.start
    }

    /// Check if the span is empty (start == end).
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.start == self.end
    }

    /// Check if this span contains the given position.
    ///
    /// A position is contained if it's >= start and < end.
    #[inline]
    pub fn contains(&self, pos: usize) -> bool {
        self.start <= pos && pos < self.end
    }

    /// Check if this span contains another span entirely.
    #[inline]
    pub fn contains_span(&self, other: &Self) -> bool {
        self.start <= other.start && self.end >= other.end
    }

    /// Check if this span overlaps with another span.
    #[inline]
    pub fn overlaps(&self, other: &Self) -> bool {
        self.start < other.end && other.start < self.end
    }

    /// Check if this span is adjacent to another span (touching but not overlapping).
    #[inline]
    pub fn is_adjacent_to(&self, other: &Self) -> bool {
        self.end == other.start || other.end == self.start
    }

    /// Join two adjacent or overlapping spans into one.
    ///
    /// Returns `None` if the spans are not adjacent/overlapping.
    #[inline]
    pub fn join(self, other: Self) -> Option<Self> {
        if self.overlaps(&other) || self.is_adjacent_to(&other) {
            Some(Self::new(
                self.start.min(other.start),
                self.end.max(other.end),
            ))
        } else {
            None
        }
    }

    /// Merge two spans into one, creating the smallest span that contains both.
    #[inline]
    pub fn merge(self, other: Self) -> Self {
        Self::new(self.start.min(other.start), self.end.max(other.end))
    }

    /// Get the intersection of two spans, if they overlap.
    ///
    /// Returns `None` if the spans don't overlap.
    #[inline]
    pub fn intersection(self, other: Self) -> Option<Self> {
        let start = self.start.max(other.start);
        let end = self.end.min(other.end);
        if start < end {
            Some(Self::new(start, end))
        } else {
            None
        }
    }

    /// Get the span that comes before this span, from `start_pos` to this span's start.
    ///
    /// Returns `None` if `start_pos >= self.start()`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use sipha_core::span::Span;
    ///
    /// let span = Span::new(10, 20);
    /// let before = span.before(5);
    /// assert_eq!(before, Some(Span::new(5, 10)));
    /// ```
    #[inline]
    pub fn before(&self, start_pos: usize) -> Option<Self> {
        if start_pos < self.start {
            Some(Self::new(start_pos, self.start))
        } else {
            None
        }
    }

    /// Get the span that comes after this span, from this span's end to `end_pos`.
    ///
    /// Returns `None` if `end_pos <= self.end()`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use sipha_core::span::Span;
    ///
    /// let span = Span::new(10, 20);
    /// let after = span.after(25);
    /// assert_eq!(after, Some(Span::new(20, 25)));
    /// ```
    #[inline]
    pub fn after(&self, end_pos: usize) -> Option<Self> {
        if end_pos > self.end {
            Some(Self::new(self.end, end_pos))
        } else {
            None
        }
    }

    /// Expand this span to include another span.
    ///
    /// This is equivalent to `self.merge(other)` but modifies `self` in place.
    ///
    /// # Example
    ///
    /// ```rust
    /// use sipha_core::span::Span;
    ///
    /// let mut span = Span::new(10, 20);
    /// span.expand_to_include(&Span::new(25, 30));
    /// assert_eq!(span, Span::new(10, 30));
    /// ```
    #[inline]
    pub fn expand_to_include(&mut self, other: &Self) {
        self.start = self.start.min(other.start);
        self.end = self.end.max(other.end);
    }

    /// Split this span at the given position, returning two spans.
    ///
    /// Returns `(before, after)` where:
    /// - `before` is the span from `self.start()` to `pos` (exclusive)
    /// - `after` is the span from `pos` to `self.end()`
    ///
    /// Returns `None` if `pos` is not within this span.
    ///
    /// # Example
    ///
    /// ```rust
    /// use sipha_core::span::Span;
    ///
    /// let span = Span::new(10, 20);
    /// let (before, after) = span.split_at(15).unwrap();
    /// assert_eq!(before, Span::new(10, 15));
    /// assert_eq!(after, Span::new(15, 20));
    /// ```
    #[inline]
    pub fn split_at(&self, pos: usize) -> Option<(Self, Self)> {
        if self.contains(pos) || pos == self.end {
            Some((Self::new(self.start, pos), Self::new(pos, self.end)))
        } else {
            None
        }
    }
}

impl From<Range<usize>> for Span {
    #[inline]
    fn from(range: Range<usize>) -> Self {
        Self::from_range(range)
    }
}

impl From<Span> for Range<usize> {
    #[inline]
    fn from(span: Span) -> Self {
        span.start..span.end
    }
}