rust-utils: add docstrings and doctests for utils.rs

rust-utils: add docstrings and doctests for utils.rs

Differential Revision: https://phab.mercurial-scm.org/D6635

--- a/rust/hg-core/src/lib.rs	Tue Jul 02 17:15:03 2019 +0200
+++ b/rust/hg-core/src/lib.rs	Wed Jul 10 17:41:07 2019 +0200
@@ -15,7 +15,7 @@
     DirstateVec,
 };
 mod filepatterns;
-mod utils;
+pub mod utils;
 
 pub use filepatterns::{
     build_single_regex, read_pattern_file, PatternSyntax, PatternTuple,

--- a/rust/hg-core/src/utils.rs	Tue Jul 02 17:15:03 2019 +0200
+++ b/rust/hg-core/src/utils.rs	Wed Jul 10 17:41:07 2019 +0200
@@ -1,10 +1,25 @@
 pub mod files;
 
+/// Replaces the `from` slice with the `to` slice inside the `buf` slice.
+///
+/// # Examples
+///
+/// ```
+/// use crate::hg::utils::replace_slice;
+/// let mut line = b"I hate writing tests!".to_vec();
+/// replace_slice(&mut line, b"hate", b"love");
+/// assert_eq!(
+///     line,
+///     b"I love writing tests!".to_vec()
+///);
+///
+/// ```
 pub fn replace_slice<T>(buf: &mut [T], from: &[T], to: &[T])
 where
     T: Clone + PartialEq,
 {
-    if buf.len() < from.len() || from.len() != to.len() {
+    assert_eq!(from.len(), to.len());
+    if buf.len() < from.len() {
         return;
     }
     for i in 0..=buf.len() - from.len() {
@@ -15,8 +30,9 @@
 }
 
 pub trait SliceExt {
+    fn trim_end(&self) -> &Self;
+    fn trim_start(&self) -> &Self;
     fn trim(&self) -> &Self;
-    fn trim_end(&self) -> &Self;
 }
 
 fn is_not_whitespace(c: &u8) -> bool {
@@ -24,17 +40,6 @@
 }
 
 impl SliceExt for [u8] {
-    fn trim(&self) -> &[u8] {
-        if let Some(first) = self.iter().position(is_not_whitespace) {
-            if let Some(last) = self.iter().rposition(is_not_whitespace) {
-                &self[first..last + 1]
-            } else {
-                unreachable!();
-            }
-        } else {
-            &[]
-        }
-    }
     fn trim_end(&self) -> &[u8] {
         if let Some(last) = self.iter().rposition(is_not_whitespace) {
             &self[..last + 1]
@@ -42,4 +47,30 @@
             &[]
         }
     }
+    fn trim_start(&self) -> &[u8] {
+        if let Some(first) = self.iter().position(is_not_whitespace) {
+            &self[first..]
+        } else {
+            &[]
+        }
+    }
+
+    /// ```
+    /// use hg::utils::SliceExt;
+    /// assert_eq!(
+    ///     b"  to trim  ".trim(),
+    ///     b"to trim"
+    /// );
+    /// assert_eq!(
+    ///     b"to trim  ".trim(),
+    ///     b"to trim"
+    /// );
+    /// assert_eq!(
+    ///     b"  to trim".trim(),
+    ///     b"to trim"
+    /// );
+    /// ```
+    fn trim(&self) -> &[u8] {
+        self.trim_start().trim_end()
+    }
 }