1use std::ops::Range;
2
3use serde::{Deserialize, Serialize};
4
5#[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#[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 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 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 pub fn contains_offset(&self, offset: usize) -> bool {
92 (self.start..self.end).contains(&offset)
93 }
94
95 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}