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}