terl 0.0.4

a general parser
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

use crate::*;

/// An `Span` represents a range of items in the source code.
///
/// It contains two data: the start of the span, and the end of the span.
///
/// # Examples
///
/// ```no_run
/// use terl::Span;
///
/// let span = Span::new(3, 7);
/// assert_eq!(span.len(), 4);
/// assert_eq!(span.is_empty(), false);
/// assert_eq!(format!("{:?}", span), "@3..7");
/// ```
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct Span {
    /// The start of the span.
    pub start: usize,
    /// The end of the span.
    pub end: usize,
}

impl Span {
    /// Creates a new `Span` with the given start and end positions.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use terl::Span;
    ///
    /// let span = Span::new(3, 7);
    /// assert_eq!(span.len(), 4);
    /// assert_eq!(span.is_empty(), false);
    /// assert_eq!(format!("{:?}", span), "@3..7");
    /// ```
    ///
    /// # Panic
    ///
    /// panic if the start of the span is after the end of the span
    pub const fn new(start: usize, end: usize) -> Self {
        assert!(start <= end);
        Self { start, end }
    }

    /// Merges this span with another span, returning a new span that includes all items from both spans.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use terl::Span;
    ///
    /// let span1 = Span::new(1, 5);
    /// let span2 = Span::new(3, 7);
    /// assert_eq!(span1.merge(span2), Span::new(1, 7));
    /// ```
    pub fn merge(self, rhs: Span) -> Self {
        let start = self.start.min(rhs.start);
        let end = self.end.max(rhs.end);

        Span::new(start, end)
    }

    /// Returns a new span that includes only the items from this span that are also in the given span.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use terl::Span;
    ///
    /// let span1 = Span::new(1, 5);
    /// let span2 = Span::new(3, 7);
    /// assert_eq!(span1.subset(span2), Span::new(3, 5));
    /// ```
    pub fn subset(self, rhs: Span) -> Self {
        let start = self.start.max(rhs.start);
        let end = self.end.min(rhs.end);
        assert!(start < end, "those two span have no subset");

        Span::new(start, end)
    }

    /// Returns the length of this span, which is the difference between the end and start positions.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use terl::Span;
    ///
    /// let span = Span::new(3, 7);
    /// assert_eq!(span.len(), 4);
    /// ```
    pub const fn len(&self) -> usize {
        self.end - self.start
    }

    /// Returns `true` if this span is empty, i.e., if its start and end positions are the same.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use terl::Span;
    ///
    /// let span = Span::new(3, 3);
    /// assert_eq!(span.is_empty(), true);
    /// ```
    pub const fn is_empty(&self) -> bool {
        self.len() == 0
    }
}

/// alias for [`Span::merge`]
impl std::ops::Add for Span {
    type Output = Self;

    fn add(self, rhs: Self) -> Self::Output {
        self.merge(rhs)
    }
}

/// alias for [`Span::subset`]
impl std::ops::Mul for Span {
    type Output = Self;

    fn mul(self, rhs: Self) -> Self::Output {
        self.subset(rhs)
    }
}

impl std::fmt::Debug for Span {
    /// Formats a `Span` as a string in the format "@start..end".
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use terl::Span;
    ///
    /// let span = Span::new(3, 7);
    /// assert_eq!(format!("{:?}", span), "@3..7");
    /// ```
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "@{}..{}", self.start, self.end)
    }
}

impl WithSpan for Span {
    fn get_span(&self) -> Span {
        *self
    }
}