Make sure all unsafe blocks are documented.

Author: crlf0710

library/core/src/needle/ext.rs

@@ -215,6 +215,8 @@ where
         let end = hay.end_index();
         start..end
     };
+    // SAFETY: the start and end indices of `range` are returned from `trim_start` and `end_index`,
+    // and both are valid indices.
     unsafe { haystack.slice_unchecked(range) }
 }
 
@@ -232,6 +234,8 @@ where
         let end = needle.into_consumer().trim_end(hay);
         start..end
     };
+    // SAFETY: the start and end indices of `range` are returned from `start_index` and `trim_end`,
+    // and both are valid indices.
     unsafe { haystack.slice_unchecked(range) }
 }
 
@@ -248,10 +252,14 @@ where
     let range = {
         let hay = &*haystack;
         let end = checker.trim_end(hay);
+        // SAFETY: the start and end indices are returned from `start_index` and `trim_end`,
+        // and both are valid indices.
         let hay = unsafe { Hay::slice_unchecked(hay, hay.start_index()..end) };
         let start = checker.trim_start(hay);
         start..end
     };
+    // SAFETY: the start and end indices of `range` are returned from `trim_start` and `trim_end`,
+    // and both are valid indices.
     unsafe { haystack.slice_unchecked(range) }
 }
 
@@ -279,6 +287,8 @@ where
     fn next_spanned(&mut self) -> Option<Span<H>> {
         let rest = self.rest.take();
         let range = self.searcher.search(rest.borrow())?;
+        // SAFETY: the start and end indices of `range` are returned from `search`,
+        // and both are valid indices.
         let [_, middle, right] = unsafe { rest.split_around(range) };
         self.rest = right;
         Some(middle)
@@ -300,6 +310,8 @@ where
     fn next_back_spanned(&mut self) -> Option<Span<H>> {
         let rest = self.rest.take();
         let range = self.searcher.rsearch(rest.borrow())?;
+        // SAFETY: the start and end indices of `range` are returned from `rsearch`,
+        // and both are valid indices.
         let [left, middle, _] = unsafe { rest.split_around(range) };
         self.rest = left;
         Some(middle)
@@ -608,6 +620,8 @@ where
         let mut rest = self.rest.take();
         match self.searcher.search(rest.borrow()) {
             Some(subrange) => {
+                // SAFETY: the start and end indices of `subrange` are returned from `search`,
+                // and both are valid indices.
                 let [left, _, right] = unsafe { rest.split_around(subrange) };
                 self.rest = right;
                 rest = left;
@@ -638,6 +652,8 @@ where
         let rest = self.rest.take();
         let after = match self.searcher.rsearch(rest.borrow()) {
             Some(range) => {
+                // SAFETY: the start and end indices of `subrange` are returned from `rsearch`,
+                // and both are valid indices.
                 let [left, _, right] = unsafe { rest.split_around(range) };
                 self.rest = left;
                 right
@@ -792,6 +808,8 @@ where
             }
             n => match self.searcher.search(rest.borrow()) {
                 Some(range) => {
+                    // SAFETY: the start and end indices of `range` are returned from `search`,
+                    // and both are valid indices.
                     let [left, _, right] = unsafe { rest.split_around(range) };
                     self.n = n - 1;
                     self.rest = right;
@@ -824,6 +842,8 @@ where
             }
             n => match self.searcher.rsearch(rest.borrow()) {
                 Some(range) => {
+                    // SAFETY: the start and end indices of `range` are returned from `rsearch`,
+                    // and both are valid indices.
                     let [left, _, right] = unsafe { rest.split_around(range) };
                     self.n = n - 1;
                     self.rest = left;
@@ -896,6 +916,8 @@ where
     let mut searcher = from.into_searcher();
     let mut src = Span::from(src);
     while let Some(range) = searcher.search(src.borrow()) {
+        // SAFETY: the start and end indices of `range` are returned from `search`,
+        // and both are valid indices.
         let [left, middle, right] = unsafe { src.split_around(range) };
         writer(Span::into(left));
         writer(replacer(Span::into(middle)));
@@ -921,6 +943,8 @@ where
         }
         n -= 1;
         if let Some(range) = searcher.search(src.borrow()) {
+            // SAFETY: the start and end indices of `range` are returned from `search`,
+            // and both are valid indices.
             let [left, middle, right] = unsafe { src.split_around(range) };
             writer(Span::into(left));
             writer(replacer(Span::into(middle)));

library/core/src/needle/haystack.rs

@@ -175,6 +175,7 @@ where
     /// The starts and end indices of `range` must be valid indices for the
     /// haystack `self` with `range.start <= range.end`.
     unsafe fn slice_unchecked(self, range: Range<<Self::Target as Hay>::Index>) -> Self {
+        // SAFETY: the caller must guarantee that starts and end indices of `range` are valid indices.
         let [_, middle, _] = unsafe { self.split_around(range) };
         middle
     }
@@ -307,6 +308,7 @@ where
         self,
         subrange: Range<<Self::Target as Hay>::Index>,
     ) -> [Self; 3] {
+        // SAFETY: the caller must guarantee that starts and end indices of `subrange` are valid indices.
         unsafe { self.split_around(subrange) }
     }
 
@@ -315,6 +317,7 @@ where
         self,
         subrange: Range<<Self::Target as Hay>::Index>,
     ) -> Self {
+        // SAFETY: the caller must guarantee that starts and end indices of `subrange` are valid indices.
         unsafe { self.slice_unchecked(subrange) }
     }
 }
@@ -330,6 +333,7 @@ where
 
     #[inline]
     fn from_span(span: Span<Self>) -> Self {
+        // SAFETY: span's range is guaranteed to be valid for the haystack.
         unsafe { span.haystack.slice_unchecked(span.range) }
     }
 
@@ -469,6 +473,7 @@ where
     pub unsafe fn split_around(self, subrange: Range<<H::Target as Hay>::Index>) -> [Self; 3] {
         let self_range = self.haystack.borrow_range(self.range.clone());
         let [left, middle, right] =
+            // SAFETY: the caller must guarantee that starts and end indices of `subrange` are valid indices.
             unsafe { self.haystack.split_around_for_span(subrange.clone()) };
 
         let left_range =
@@ -490,6 +495,7 @@ where
     /// `subrange` must be a valid range relative to `self.borrow()`.
     #[inline]
     pub unsafe fn slice_unchecked(self, subrange: Range<<H::Target as Hay>::Index>) -> Self {
+        // SAFETY: the caller must guarantee that starts and end indices of `subrange` are valid indices.
         let haystack = unsafe { self.haystack.slice_unchecked_for_span(subrange.clone()) };
         let range = haystack.do_restore_range(self.range, subrange);
         Self { haystack, range }
@@ -504,6 +510,7 @@ unsafe impl<'a, A: Hay + ?Sized + 'a> Haystack for &'a A {
 
     #[inline]
     unsafe fn split_around(self, range: Range<A::Index>) -> [Self; 3] {
+        // SAFETY: the caller must guarantee that starts and end indices of `range` are valid indices.
         unsafe {
             [
                 self.slice_unchecked(self.start_index()..range.start),
@@ -515,6 +522,7 @@ unsafe impl<'a, A: Hay + ?Sized + 'a> Haystack for &'a A {
 
     #[inline]
     unsafe fn slice_unchecked(self, range: Range<A::Index>) -> Self {
+        // SAFETY: the caller must guarantee that starts and end indices of `range` are valid indices.
         unsafe { A::slice_unchecked(self, range) }
     }
 
@@ -546,16 +554,19 @@ unsafe impl Hay for str {
 
     #[inline]
     unsafe fn slice_unchecked(&self, range: Range<usize>) -> &Self {
+        // SAFETY: the caller must guarantee that starts and end indices of `range` are valid indices.
         unsafe { self.get_unchecked(range) }
     }
 
     #[inline]
     unsafe fn next_index(&self, index: Self::Index) -> Self::Index {
+        // SAFETY: the caller must guarantee that `index` is a valid index.
         index + unsafe { self.get_unchecked(index..).chars().next().unwrap().len_utf8() }
     }
 
     #[inline]
     unsafe fn prev_index(&self, index: Self::Index) -> Self::Index {
+        // SAFETY: the caller must guarantee that `index` is a valid index.
         index - unsafe { self.get_unchecked(..index).chars().next_back().unwrap().len_utf8() }
     }
 }
@@ -568,6 +579,7 @@ unsafe impl<'h> Haystack for &'h mut str {
 
     #[inline]
     unsafe fn slice_unchecked(self, range: Range<usize>) -> Self {
+        // SAFETY: the caller must guarantee that starts and end indices of `range` are valid indices.
         unsafe { self.get_unchecked_mut(range) }
     }
 
@@ -604,6 +616,7 @@ unsafe impl<T> Hay for [T] {
 
     #[inline]
     unsafe fn slice_unchecked(&self, range: Range<usize>) -> &Self {
+        // SAFETY: the caller must guarantee that starts and end indices of `range` are valid indices.
         unsafe { self.get_unchecked(range) }
     }
 
@@ -626,6 +639,7 @@ unsafe impl<'h, T: 'h> Haystack for &'h mut [T] {
 
     #[inline]
     unsafe fn slice_unchecked(self, range: Range<usize>) -> Self {
+        // SAFETY: the caller must guarantee that starts and end indices of `range` are valid indices.
         unsafe { self.get_unchecked_mut(range) }
     }
 

library/core/src/needle/needle.rs

@@ -167,6 +167,7 @@ pub unsafe trait Consumer<A: Hay + ?Sized> {
             if pos == range.start {
                 break;
             }
+            // SAFETY: span's range is guaranteed to be valid for the haystack.
             span = unsafe { Span::from_parts(hay, pos..range.end) };
         }
         offset
@@ -250,6 +251,7 @@ pub unsafe trait ReverseConsumer<A: Hay + ?Sized>: Consumer<A> {
             if pos == range.end {
                 break;
             }
+            // SAFETY: span's range is guaranteed to be valid for the haystack.
             span = unsafe { Span::from_parts(hay, range.start..pos) };
         }
         offset
@@ -342,6 +344,7 @@ unsafe impl<A: Hay + ?Sized> Searcher<A> for EmptySearcher {
         } else if range.start == range.end {
             return None;
         } else {
+            // SAFETY: span's range is guaranteed to be valid for the haystack.
             unsafe { hay.next_index(range.start) }
         };
         Some(start..start)
@@ -371,6 +374,7 @@ unsafe impl<A: Hay + ?Sized> ReverseSearcher<A> for EmptySearcher {
         } else if range.start == range.end {
             return None;
         } else {
+            // SAFETY: span's range is guaranteed to be valid for the haystack.
             unsafe { hay.prev_index(range.end) }
         };
         Some(end..end)