Skip to main content

vvv_core/text/
span.rs

1use std::ops::Range;
2
3use serde::{Deserialize, Serialize};
4
5/// Half-open byte range `[start, end)` inside a single file.
6#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
7#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
8#[serde(try_from = "SpanBounds")]
9pub struct Span {
10    pub start: usize,
11    pub end: usize,
12}
13
14#[derive(Deserialize)]
15#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
16struct SpanBounds {
17    start: usize,
18    end: usize,
19}
20
21/// A byte range that cannot address the supplied source.
22#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
23pub enum SpanError {
24    #[error("reversed byte range {span:?}")]
25    Reversed { span: Span },
26    #[error("byte range {span:?} exceeds source length {len}")]
27    OutOfBounds { span: Span, len: usize },
28    #[error("byte range {span:?} splits a UTF-8 character")]
29    CharBoundary { span: Span },
30}
31
32impl TryFrom<SpanBounds> for Span {
33    type Error = SpanError;
34
35    fn try_from(bounds: SpanBounds) -> Result<Self, Self::Error> {
36        let span = Self {
37            start: bounds.start,
38            end: bounds.end,
39        };
40        span.validate()?;
41        Ok(span)
42    }
43}
44
45impl Span {
46    pub fn new(start: usize, end: usize) -> Self {
47        assert!(start <= end, "span start {start} > end {end}");
48        Self { start, end }
49    }
50
51    pub fn validate(&self) -> Result<(), SpanError> {
52        if self.start > self.end {
53            return Err(SpanError::Reversed { span: *self });
54        }
55        Ok(())
56    }
57
58    /// Validate ordering, bounds, and character boundaries before slicing.
59    pub fn validate_in(&self, source: &str) -> Result<(), SpanError> {
60        self.validate()?;
61        if self.end > source.len() {
62            return Err(SpanError::OutOfBounds {
63                span: *self,
64                len: source.len(),
65            });
66        }
67        if !source.is_char_boundary(self.start) || !source.is_char_boundary(self.end) {
68            return Err(SpanError::CharBoundary { span: *self });
69        }
70        Ok(())
71    }
72
73    pub fn len(&self) -> usize {
74        self.end - self.start
75    }
76
77    pub fn is_empty(&self) -> bool {
78        self.start == self.end
79    }
80
81    /// Two spans overlap when they share at least one byte. Touching spans do not.
82    pub fn overlaps(&self, other: &Span) -> bool {
83        self.start < other.end && other.start < self.end
84    }
85
86    pub fn contains(&self, other: &Span) -> bool {
87        self.start <= other.start && other.end <= self.end
88    }
89
90    /// Whether the byte at `offset` lies inside the span.
91    pub fn contains_offset(&self, offset: usize) -> bool {
92        (self.start..self.end).contains(&offset)
93    }
94
95    /// Smallest span covering both.
96    pub fn union(&self, other: &Span) -> Span {
97        Span::new(self.start.min(other.start), self.end.max(other.end))
98    }
99}
100
101impl From<Range<usize>> for Span {
102    fn from(range: Range<usize>) -> Self {
103        Span::new(range.start, range.end)
104    }
105}
106
107impl From<Span> for Range<usize> {
108    fn from(span: Span) -> Self {
109        span.start..span.end
110    }
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116
117    #[test]
118    fn deserialization_rejects_reversed_ranges() {
119        assert!(serde_json::from_str::<Span>(r#"{"start":2,"end":1}"#).is_err());
120        assert_eq!(
121            serde_json::from_str::<Span>(r#"{"start":2,"end":2}"#).unwrap(),
122            Span::new(2, 2)
123        );
124    }
125
126    #[test]
127    fn overlap_is_strict() {
128        let a = Span::new(0, 5);
129        assert!(a.overlaps(&Span::new(4, 8)));
130        assert!(!a.overlaps(&Span::new(5, 8)));
131        assert!(!Span::new(5, 8).overlaps(&a));
132    }
133
134    #[test]
135    fn empty_span_conflicts_inside_a_range_but_not_at_its_edges() {
136        let a = Span::new(0, 5);
137        assert!(a.overlaps(&Span::new(2, 2)));
138        assert!(!a.overlaps(&Span::new(0, 0)));
139        assert!(!a.overlaps(&Span::new(5, 5)));
140        assert!(!Span::new(3, 3).overlaps(&Span::new(3, 3)));
141    }
142}