Skip to main content

wright/source_tracking/
immutable_string.rs

1//! Structure and implementation relating to the representation of source files (as immutable strings) throughout
2//! the Wright compiler and tooling.
3
4use std::sync::Arc;
5
6#[cfg(feature = "file_memmap")]
7use fs4::fs_std::FileExt;
8
9#[cfg(feature = "file_memmap")]
10use memmap2::Mmap;
11
12#[cfg(feature = "file_memmap")]
13use std::{fs::File, io};
14
15/// An immutable string that either
16/// - References a source string in memory using a `'static` reference,
17/// - Owns a source string in memory.
18/// - Owns a locked and memory mapped file from the disk.
19///
20/// This uses an [Arc] internally to make cloning cheap.
21#[derive(Debug, Clone)]
22pub struct ImmutableString {
23    /// Wrap the internal enum representation. This is to avoid exposing the API for a user to construct an
24    /// [ImmutableStringInner] without satisfying certain invariants.
25    inner: Arc<ImmutableStringInner>,
26}
27
28impl ImmutableString {
29    /// Wrap the inner representation in this type.
30    #[inline]
31    fn from_inner(inner: ImmutableStringInner) -> Self {
32        ImmutableString {
33            inner: Arc::new(inner),
34        }
35    }
36
37    /// Create a new [ImmutableString] holding the given [File] (assumed to be locked with [fs4])
38    /// and the [Mmap] mapping that file to memory.
39    ///
40    /// This function requires that the memory mapped by the given
41    /// [Mmap] is valid UTF-8 using [std::str::from_utf8].
42    #[cfg(feature = "file_memmap")]
43    pub(super) fn new_locked_file(file: File, mem_map: Mmap) -> Self {
44        Self::from_inner(ImmutableStringInner::LockedFile {
45            locked_file: file,
46            mem_map,
47        })
48    }
49
50    /// Create a new [ImmutableString] that owns a string allocated on the heap.
51    pub(super) fn new_owned(boxed_str: Box<str>) -> Self {
52        Self::from_inner(ImmutableStringInner::Owned(boxed_str))
53    }
54
55    /// Create a new [ImmutableString] referencing a string directly.
56    pub(super) fn new_static(str_ref: &'static str) -> Self {
57        Self::from_inner(ImmutableStringInner::Static(str_ref))
58    }
59
60    /// Get a list of byte indices into this [ImmutableString] of the start of every line.
61    ///
62    /// There is always at least one line (starting at index 0), even in an empty string, and a string ending with a
63    /// newline has an empty last line starting at the end of the string. This matches the convention used by
64    /// [codespan_reporting], so diagnostics can point at the end of any source.
65    pub fn line_starts(&self) -> impl Iterator<Item = usize> + use<'_> {
66        std::iter::once(0).chain(
67            self.as_str()
68                .bytes()
69                .enumerate()
70                .filter(|(_, byte)| *byte == b'\n')
71                .map(|(index, _)| index + 1),
72        )
73    }
74
75    /// Get this [ImmutableString] as a [str] reference.
76    /// This just calls [AsRef::as_ref].
77    pub fn as_str(&self) -> &str {
78        self.as_ref()
79    }
80
81    /// Get the length of this [ImmutableString] in bytes.
82    /// See [str::len].
83    pub fn len(&self) -> usize {
84        self.as_str().len()
85    }
86
87    /// Check if this [ImmutableString] is empty.
88    #[inline]
89    pub fn is_empty(&self) -> bool {
90        self.len() == 0
91    }
92}
93
94impl AsRef<str> for ImmutableString {
95    fn as_ref(&self) -> &str {
96        (*self.inner).as_ref()
97    }
98}
99
100/// The internal enum representation of the immutable string.
101#[derive(Debug)]
102enum ImmutableStringInner {
103    /// An immutable reference to an existing static string.
104    Static(&'static str),
105
106    /// An owned immutable string.
107    Owned(Box<str>),
108
109    /// A locked, memory mapped file from the disk.
110    #[cfg(feature = "file_memmap")]
111    LockedFile {
112        /// The locked file that gets unlocked when this struct is dropped.
113        locked_file: File,
114
115        /// The memory mapped file.
116        ///
117        /// # Safety
118        /// - Undefined  behavior occurs if the file on disk is modified while memory mapped. Always lock the
119        ///   file (in this crate's case, using [fs4]) before creating this [Mmap] for it.
120        ///   See [Mmap] for more details.
121        /// - This struct assumes that any memory-mapped files have their UTF-8 validity checked by the caller.
122        ///   Specificically the [ImmutableString::as_ref] method relies on [std::str::from_utf8_unchecked],
123        ///   so if you do not ensure the [Mmap] is valid UTF-8, you will run into undefined behavior.
124        mem_map: Mmap,
125    },
126}
127
128/// Implement [Drop] to make sure that the files from disk get unlocked as they go out of scope/use.
129#[cfg(feature = "file_memmap")]
130impl Drop for ImmutableStringInner {
131    fn drop(&mut self) {
132        match self {
133            // Unlock locked files.
134            ImmutableStringInner::LockedFile { locked_file, .. } => {
135                FileExt::unlock(locked_file)
136                    // Log the error if there is one,
137                    .map_err(|io_err: io::Error| eprintln!("{io_err}"))
138                    // Discard value of result
139                    .ok();
140            }
141
142            // All other types drop trivially.
143            ImmutableStringInner::Owned(_) | ImmutableStringInner::Static(_) => {}
144        }
145    }
146}
147
148impl AsRef<str> for ImmutableStringInner {
149    fn as_ref(&self) -> &str {
150        match self {
151            ImmutableStringInner::Static(str) => str,
152            ImmutableStringInner::Owned(str) => str,
153
154            #[cfg(feature = "file_memmap")]
155            ImmutableStringInner::LockedFile { mem_map, .. } => {
156                // Get a direct reference to the data that is in the memory map.
157                let raw_data: &[u8] = mem_map.as_ref();
158                // SAFETY: UTF-8 validity is checked when the file is added to the file map, or by the API consumer.
159                unsafe { std::str::from_utf8_unchecked(raw_data) }
160            }
161        }
162    }
163}
164
165#[cfg(test)]
166mod tests {
167    use super::ImmutableString;
168
169    #[test]
170    fn test_line_starts() {
171        let v: Vec<usize> = ImmutableString::new_static("a\n\nb\nc")
172            .line_starts()
173            .collect();
174
175        assert_eq!(v.as_slice(), &[0, 2, 3, 5]);
176    }
177
178    #[test]
179    fn test_line_starts_edge_cases() {
180        let lines = |s: &'static str| {
181            ImmutableString::new_static(s)
182                .line_starts()
183                .collect::<Vec<_>>()
184        };
185
186        assert_eq!(lines(""), [0]);
187        assert_eq!(lines("a"), [0]);
188        assert_eq!(lines("a\n"), [0, 2]);
189        assert_eq!(lines("\n\n"), [0, 1, 2]);
190        assert_eq!(lines("☃\n☃"), [0, 4]);
191    }
192}