span_lang/
pos.rs

1//! Byte positions — the atom every [`Span`](crate::Span) is built from.
2
3use core::fmt;
4
5/// A zero-based byte offset into a single source buffer.
6///
7/// `BytePos` is a `Copy` newtype over a `u32`, so it is eight-times cheaper to
8/// move than a `usize` pair and fits two-to-a-cache-line inside a
9/// [`Span`](crate::Span). The 32-bit width bounds a single source to 4 GiB, which
10/// is the addressing envelope language front-ends use; a larger source belongs in
11/// a multi-file mapping above this crate, not in a wider offset here.
12///
13/// The offset is a *byte* index, not a character index — it may only legally fall
14/// on a UTF-8 character boundary. Resolving an offset that lands inside a
15/// multi-byte sequence is defined (it rounds down) rather than undefined; see
16/// [`LineIndex::line_col`](crate::LineIndex::line_col).
17///
18/// # Examples
19///
20/// ```
21/// use span_lang::BytePos;
22///
23/// let p = BytePos::new(42);
24/// assert_eq!(p.to_u32(), 42);
25/// assert_eq!(p.to_usize(), 42);
26///
27/// // Ordered, so positions sort and compare naturally.
28/// assert!(BytePos::new(1) < BytePos::new(2));
29/// ```
30#[repr(transparent)]
31#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
32pub struct BytePos(u32);
33
34impl BytePos {
35    /// Constructs a position from a raw byte offset.
36    ///
37    /// # Examples
38    ///
39    /// ```
40    /// use span_lang::BytePos;
41    ///
42    /// const START: BytePos = BytePos::new(0);
43    /// assert_eq!(START.to_u32(), 0);
44    /// ```
45    #[inline]
46    #[must_use]
47    pub const fn new(offset: u32) -> Self {
48        Self(offset)
49    }
50
51    /// Returns the raw byte offset.
52    ///
53    /// # Examples
54    ///
55    /// ```
56    /// use span_lang::BytePos;
57    ///
58    /// assert_eq!(BytePos::new(7).to_u32(), 7);
59    /// ```
60    #[inline]
61    #[must_use]
62    pub const fn to_u32(self) -> u32 {
63        self.0
64    }
65
66    /// Returns the offset widened to a `usize`, ready to index a byte slice.
67    ///
68    /// # Examples
69    ///
70    /// ```
71    /// use span_lang::BytePos;
72    ///
73    /// let src = b"hello";
74    /// let at = BytePos::new(1);
75    /// assert_eq!(src[at.to_usize()], b'e');
76    /// ```
77    #[inline]
78    #[must_use]
79    pub const fn to_usize(self) -> usize {
80        self.0 as usize
81    }
82}
83
84impl From<u32> for BytePos {
85    #[inline]
86    fn from(offset: u32) -> Self {
87        Self(offset)
88    }
89}
90
91impl From<BytePos> for u32 {
92    #[inline]
93    fn from(pos: BytePos) -> Self {
94        pos.0
95    }
96}
97
98impl fmt::Display for BytePos {
99    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
100        fmt::Display::fmt(&self.0, f)
101    }
102}
103
104#[cfg(test)]
105mod tests {
106    use super::*;
107
108    #[test]
109    fn test_byte_pos_round_trips_through_u32() {
110        let p = BytePos::new(123);
111        assert_eq!(u32::from(p), 123);
112        assert_eq!(BytePos::from(123u32), p);
113    }
114
115    #[test]
116    fn test_byte_pos_default_is_zero() {
117        assert_eq!(BytePos::default(), BytePos::new(0));
118    }
119
120    #[test]
121    fn test_byte_pos_ordering_matches_offset() {
122        assert!(BytePos::new(3) < BytePos::new(4));
123        assert!(BytePos::new(9) > BytePos::new(8));
124    }
125
126    #[test]
127    fn test_byte_pos_display_is_the_number() {
128        extern crate alloc;
129        use alloc::string::ToString;
130        assert_eq!(BytePos::new(256).to_string(), "256");
131    }
132}
span_lang/pos.rs

span_lang/
pos.rs
