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

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

rust/hg-core/src/lib.rs

@@ -1,105 +1,105 b''
 // Copyright 2018 Georges Racinet <[e-mail]>
 //
 // This software may be used and distributed according to the terms of the
 // GNU General Public License version 2 or any later version.
 mod ancestors;
 pub mod dagops;
 pub use ancestors::{AncestorsIterator, LazyAncestors, MissingAncestors};
 mod dirstate;
 pub mod discovery;
 pub mod testing; // unconditionally built, for use from integration tests
 pub use dirstate::{
     dirs_multiset::DirsMultiset,
     parsers::{pack_dirstate, parse_dirstate},
     CopyVec, CopyVecEntry, DirsIterable, DirstateEntry, DirstateParents,
     DirstateVec,
 };
 mod filepatterns;
-mod utils;
+pub mod utils;
 
 pub use filepatterns::{
     build_single_regex, read_pattern_file, PatternSyntax, PatternTuple,
 };
 
 /// Mercurial revision numbers
 ///
 /// As noted in revlog.c, revision numbers are actually encoded in
 /// 4 bytes, and are liberally converted to ints, whence the i32
 pub type Revision = i32;
 
 /// Marker expressing the absence of a parent
 ///
 /// Independently of the actual representation, `NULL_REVISION` is guaranteed
 /// to be smaller that all existing revisions.
 pub const NULL_REVISION: Revision = -1;
 
 /// Same as `mercurial.node.wdirrev`
 ///
 /// This is also equal to `i32::max_value()`, but it's better to spell
 /// it out explicitely, same as in `mercurial.node`
 pub const WORKING_DIRECTORY_REVISION: Revision = 0x7fffffff;
 
 /// The simplest expression of what we need of Mercurial DAGs.
 pub trait Graph {
     /// Return the two parents of the given `Revision`.
     ///
     /// Each of the parents can be independently `NULL_REVISION`
     fn parents(&self, rev: Revision) -> Result<[Revision; 2], GraphError>;
 }
 
 pub type LineNumber = usize;
 
 #[derive(Clone, Debug, PartialEq)]
 pub enum GraphError {
     ParentOutOfRange(Revision),
     WorkingDirectoryUnsupported,
 }
 
 #[derive(Clone, Debug, PartialEq)]
 pub enum DirstateParseError {
     TooLittleData,
     Overflow,
     CorruptedEntry(String),
 }
 
 #[derive(Debug, PartialEq)]
 pub enum DirstatePackError {
     CorruptedEntry(String),
     CorruptedParent,
     BadSize(usize, usize),
 }
 
 #[derive(Debug, PartialEq)]
 pub enum DirstateMapError {
     PathNotFound(Vec<u8>),
     EmptyPath,
 }
 
 impl From<std::io::Error> for DirstatePackError {
     fn from(e: std::io::Error) -> Self {
         DirstatePackError::CorruptedEntry(e.to_string())
     }
 }
 
 impl From<std::io::Error> for DirstateParseError {
     fn from(e: std::io::Error) -> Self {
         DirstateParseError::CorruptedEntry(e.to_string())
     }
 }
 
 #[derive(Debug)]
 pub enum PatternError {
     UnsupportedSyntax(String),
 }
 
 #[derive(Debug)]
 pub enum PatternFileError {
     IO(std::io::Error),
     Pattern(PatternError, LineNumber),
 }
 
 impl From<std::io::Error> for PatternFileError {
     fn from(e: std::io::Error) -> Self {
         PatternFileError::IO(e)
     }
 }

rust/hg-core/src/utils.rs

@@ -1,45 +1,76 b''
 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() {
         if buf[i..].starts_with(from) {
             buf[i..(i + from.len())].clone_from_slice(to);
         }
     }
 }
 
 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 {
     !(*c as char).is_whitespace()
 }
 
 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]
         } else {
             &[]
         }
     }
+    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()
+    }
 }