Add support for capture groups and substring replacement

This adds a new regex function `capture`, which captures matching
substrings, using a new type `Captures`.

It also adds new functions `replace` and `replace_all`, allowing
substring replacement.

Author: henrikhorluck

src/bytes.rs

@@ -1,4 +1,5 @@
 use crate::ffi::CodeUnitWidth8;
+pub use crate::regex_impl::Captures as CapturesImpl;
 pub use crate::regex_impl::Match as MatchImpl;
 
 #[doc(inline)]
@@ -21,6 +22,19 @@ pub type RegexBuilder = RegexBuilderImpl<CodeUnitWidth8>;
 /// of the subject string.
 pub type Match<'s> = MatchImpl<'s, CodeUnitWidth8>;
 
+/// `Captures` represents a group of captured byte strings for a single match.
+///
+/// The 0th capture always corresponds to the entire match. Each subsequent
+/// index corresponds to the next capture group in the regex. If a capture
+/// group is named, then the matched byte string is *also* available via the
+/// `name` method. (Note that the 0th capture is always unnamed and so must be
+/// accessed with the `get` method.)
+///
+/// Positions returned from a capture group are always byte indices.
+///
+/// `'s` is the lifetime of the matched subject string.
+pub type Captures<'s> = CapturesImpl<'s, CodeUnitWidth8>;
+
 #[cfg(test)]
 mod tests {
     use super::{CodeUnitWidth8, Regex, RegexBuilder};

src/ffi.rs

@@ -88,7 +88,7 @@ pub trait CodeUnitWidth: std::fmt::Debug + 'static {
     type pcre2_match_context;
     type pcre2_match_data;
     type pcre2_jit_stack;
-    type PCRE2_CHAR;
+    type PCRE2_CHAR: Default + Copy + TryInto<Self::SubjectChar>;
     type PCRE2_SPTR;
     type name_table_entry: NameTableEntry;
     type SubjectChar: Copy;
@@ -169,6 +169,20 @@ pub trait CodeUnitWidth: std::fmt::Debug + 'static {
     unsafe fn pcre2_get_ovector_count(
         arg1: *mut Self::pcre2_match_data,
     ) -> u32;
+
+    unsafe fn pcre2_substitute(
+        code: *const Self::pcre2_code,
+        subject: Self::PCRE2_SPTR,
+        length: usize,
+        startoffset: usize,
+        options: u32,
+        match_data: *mut Self::pcre2_match_data,
+        mcontext: *mut Self::pcre2_match_context,
+        replacement: Self::PCRE2_SPTR,
+        rlength: usize,
+        outputbuffer: *mut Self::PCRE2_CHAR,
+        outputlengthptr: *mut usize,
+    ) -> ::libc::c_int;
 }
 
 #[derive(Debug)]
@@ -313,6 +327,33 @@ impl CodeUnitWidth for CodeUnitWidth8 {
     ) -> u32 {
         pcre2_get_ovector_count_8(arg1)
     }
+    unsafe fn pcre2_substitute(
+        code: *const Self::pcre2_code,
+        subject: Self::PCRE2_SPTR,
+        length: usize,
+        startoffset: usize,
+        options: u32,
+        match_data: *mut Self::pcre2_match_data,
+        mcontext: *mut Self::pcre2_match_context,
+        replacement: Self::PCRE2_SPTR,
+        rlength: usize,
+        outputbuffer: *mut Self::PCRE2_CHAR,
+        outputlengthptr: *mut usize,
+    ) -> ::libc::c_int {
+        pcre2_substitute_8(
+            code,
+            subject,
+            length,
+            startoffset,
+            options,
+            match_data,
+            mcontext,
+            replacement,
+            rlength,
+            outputbuffer,
+            outputlengthptr,
+        )
+    }
 }
 
 #[derive(Debug)]
@@ -461,6 +502,34 @@ impl CodeUnitWidth for CodeUnitWidth32 {
     ) -> u32 {
         pcre2_get_ovector_count_32(arg1)
     }
+
+    unsafe fn pcre2_substitute(
+        code: *const Self::pcre2_code,
+        subject: Self::PCRE2_SPTR,
+        length: usize,
+        startoffset: usize,
+        options: u32,
+        match_data: *mut Self::pcre2_match_data,
+        mcontext: *mut Self::pcre2_match_context,
+        replacement: Self::PCRE2_SPTR,
+        rlength: usize,
+        outputbuffer: *mut Self::PCRE2_CHAR,
+        outputlengthptr: *mut usize,
+    ) -> ::libc::c_int {
+        pcre2_substitute_32(
+            code,
+            subject,
+            length,
+            startoffset,
+            options,
+            match_data,
+            mcontext,
+            replacement,
+            rlength,
+            outputbuffer,
+            outputlengthptr,
+        )
+    }
 }
 
 /// Returns true if and only if PCRE2 believes that JIT is available.
@@ -692,6 +761,53 @@ impl<W: CodeUnitWidth> Code<W> {
             Ok(1 + count as usize)
         }
     }
+
+    pub unsafe fn substitute(
+        &self,
+        mut subject: &[W::SubjectChar],
+        mut replacement: &[W::SubjectChar],
+        start: usize,
+        options: u32,
+        output: &mut [W::PCRE2_CHAR],
+        output_len: &mut usize,
+    ) -> Result<usize, Error> {
+        // When the subject is empty, we use an empty slice
+        // with a known valid pointer. Otherwise, slices derived
+        // from, e.g., an empty `Vec<u8>` may not have a valid
+        // pointer, since creating an empty `Vec` is guaranteed
+        // to not allocate.
+        if subject.is_empty() {
+            subject = &[];
+        }
+        if replacement.is_empty() {
+            replacement = &[];
+        }
+        let (subj_ptr, subj_len) = W::subject_to_sptr_len(subject);
+        let (repl_ptr, repl_len) = W::subject_to_sptr_len(replacement);
+
+        // safety: we allow arbitrary options, security contract is on the caller
+        let rc = unsafe {
+            W::pcre2_substitute(
+                self.code,
+                subj_ptr,
+                subj_len,
+                start,
+                options,
+                ptr::null_mut(),
+                // should probably not be null for performance reasons?
+                ptr::null_mut(),
+                repl_ptr,
+                repl_len,
+                output.as_mut_ptr() as *mut W::PCRE2_CHAR,
+                output_len as *mut usize,
+            )
+        };
+        if rc >= 0 {
+            return Ok(rc as usize);
+        }
+        // this might warrant a new error type
+        Err(Error::info(rc))
+    }
 }
 
 /// A low level representation of PCRE2's compilation context.

src/regex_impl.rs

@@ -1,4 +1,5 @@
 use std::{
+    borrow::Cow,
     collections::HashMap,
     fmt,
     ops::Index,
@@ -8,8 +9,10 @@ use std::{
 
 use log::debug;
 use pcre2_sys::{
-    PCRE2_CASELESS, PCRE2_DOTALL, PCRE2_EXTENDED, PCRE2_MATCH_INVALID_UTF,
-    PCRE2_MULTILINE, PCRE2_NEVER_UTF, PCRE2_NEWLINE_ANYCRLF, PCRE2_UCP,
+    PCRE2_CASELESS, PCRE2_DOTALL, PCRE2_ERROR_NOMEMORY, PCRE2_EXTENDED,
+    PCRE2_MATCH_INVALID_UTF, PCRE2_MULTILINE, PCRE2_NEVER_UTF,
+    PCRE2_NEWLINE_ANYCRLF, PCRE2_SUBSTITUTE_EXTENDED, PCRE2_SUBSTITUTE_GLOBAL,
+    PCRE2_SUBSTITUTE_OVERFLOW_LENGTH, PCRE2_SUBSTITUTE_UNSET_EMPTY, PCRE2_UCP,
     PCRE2_UNSET, PCRE2_UTF,
 };
 
@@ -623,6 +626,127 @@ impl<W: CodeUnitWidth> Regex<W> {
     pub(crate) fn get_capture_names_idxs(&self) -> &HashMap<String, usize> {
         &self.capture_names_idx
     }
+
+    /// Replace the first match in the subject string with the replacement
+    /// If `extended` is true, enable PCRE2's extended replacement syntax.
+    pub fn replace<'s>(
+        &self,
+        subject: &'s [W::SubjectChar],
+        replacement: &[W::SubjectChar],
+        extended: bool,
+    ) -> Result<Cow<'s, [W::SubjectChar]>, Error>
+    where
+        [<W as CodeUnitWidth>::PCRE2_CHAR]: ToOwned,
+    {
+        self.replace_impl(subject, replacement, false, extended)
+    }
+
+    /// Replace all non-overlapping matches in the subject string with the replacement
+    /// If `extended` is true, enable PCRE2's extended replacement syntax.
+    pub fn replace_all<'s>(
+        &self,
+        subject: &'s [W::SubjectChar],
+        replacement: &[W::SubjectChar],
+        extended: bool,
+    ) -> Result<Cow<'s, [W::SubjectChar]>, Error>
+    where
+        [<W as CodeUnitWidth>::PCRE2_CHAR]: ToOwned,
+    {
+        self.replace_impl(subject, replacement, true, extended)
+    }
+
+    #[inline]
+    fn replace_impl<'s>(
+        &self,
+        subject: &'s [W::SubjectChar],
+        replacement: &[W::SubjectChar],
+        replace_all: bool,
+        extended: bool,
+    ) -> Result<Cow<'s, [W::SubjectChar]>, Error>
+    where
+        [<W as CodeUnitWidth>::PCRE2_CHAR]: ToOwned,
+    {
+        let mut options: u32 = 0;
+        options |= PCRE2_SUBSTITUTE_OVERFLOW_LENGTH;
+        // TODO: this should probably be configurable from user-side
+        options |= PCRE2_SUBSTITUTE_UNSET_EMPTY;
+        if extended {
+            options |= PCRE2_SUBSTITUTE_EXTENDED;
+        }
+        if replace_all {
+            options |= PCRE2_SUBSTITUTE_GLOBAL;
+        }
+
+        // We prefer to allocate on the stack but fall back to the heap.
+        // Note that PCRE2 has the following behavior with PCRE2_SUBSTITUTE_OVERFLOW_LENGTH:
+        //   - We supply the initial output buffer size in `capacity`. This should have sufficient
+        //     capacity for the terminating NUL character.
+        //   - If the capacity is NOT sufficient, PCRE2 returns the new required capacity, also
+        //     including the terminating NUL character.
+        //   - If the capacity IS sufficient, PCRE2 returns the number of characters written, NOT
+        //     including the terminating NUL character.
+        // Example: our initial capacity is 256. If the returned string needs to be of length 512,
+        // then PCRE2 will report NOMEMORY and set capacity to 513. After reallocating we pass in
+        // a capacity of 513; it succeeds and sets capacity to 512, which is the length of the result.
+        let mut stack_storage: [W::PCRE2_CHAR; 256] =
+            [W::PCRE2_CHAR::default(); 256];
+        let mut heap_storage = Vec::new();
+        let mut output = stack_storage.as_mut();
+        let mut capacity = output.len();
+
+        let mut rc = unsafe {
+            self.code.substitute(
+                subject,
+                replacement,
+                0,
+                options,
+                output,
+                &mut capacity,
+            )
+        };
+
+        if let Err(e) = &rc {
+            if e.code() == PCRE2_ERROR_NOMEMORY {
+                if heap_storage.try_reserve_exact(capacity).is_err() {
+                    return Err(rc.unwrap_err());
+                }
+                heap_storage.resize(capacity, W::PCRE2_CHAR::default());
+                output = &mut heap_storage;
+                capacity = output.len();
+                rc = unsafe {
+                    self.code.substitute(
+                        subject,
+                        replacement,
+                        0,
+                        options,
+                        output,
+                        &mut capacity,
+                    )
+                };
+            }
+        }
+
+        let s = match rc? {
+            0 => Cow::Borrowed(subject),
+            _ => {
+                // capacity has been updated with the length of the result (excluding nul terminator).
+                let output = &output[..capacity];
+
+                // All inputs contained valid chars, so we expect all outputs to as well.
+                let to_char = |c: W::PCRE2_CHAR| -> W::SubjectChar {
+                    c.try_into().unwrap_or_else(|_| {
+                        panic!("all output expected to be valid chars")
+                    })
+                };
+
+                // this is really just a type cast
+                let x: Vec<W::SubjectChar> =
+                    output.iter().copied().map(to_char).collect();
+                Cow::Owned(x)
+            }
+        };
+        Ok(s)
+    }
 }
 
 /// Advanced or  "lower level" search methods.
@@ -870,7 +994,7 @@ impl<W: CodeUnitWidth> CaptureLocations<W> {
     }
 }
 
-/// Captures represents a group of captured byte strings for a single match.
+/// `Captures` represents a group of captured strings for a single match.
 ///
 /// The 0th capture always corresponds to the entire match. Each subsequent
 /// index corresponds to the next capture group in the regex. If a capture