Add static Substitute overloads

README.md

@@ -29,9 +29,12 @@ This is a friendly API that is very similar to .NET's `System.Text.RegularExpres
   - `Matches`
   - `Match`
   - `IsMatch`
-- Matched string replacement: `Replace`
-  - Callbacks: `Func<PcreMatch, string>`
-  - Replacement strings with placeholders: ``$n ${name} $& $_ $` $' $+``
+- Matched string replacement:
+  - Using `Replace`, the PCRE.NET API:
+    - Callbacks: `Func<PcreMatch, string>`
+    - Replacement strings with placeholders: ``$n ${name} $& $_ $` $' $+``
+  - Using `Substitute`, the PCRE2 API:
+      - Replacement strings with placeholders: ``$n ${n} $$ $*MARK ${*MARK}``
 - String splitting on matches: `Split`
 
 ### The Span API
@@ -90,13 +93,20 @@ var matches = PcreRegex.Matches("(foo) bar (baz) 42", @"\(\w+\)(*SKIP)(*FAIL)|\w
 // result: "bar", "42"
 ```
 
-- Enclose a series of punctuation characters within angle brackets:
+- Enclose a series of punctuation characters within angle brackets using `Replace` (the PCRE.NET API):
 
 ```C#
 var result = PcreRegex.Replace("hello, world!!!", @"\p{P}+", "<$&>");
 // result: "hello<,> world<!!!>"
 ```
 
+- Enclose a series of punctuation characters within angle brackets using `Substitute` (the PCRE2 API):
+
+```C#
+var result = PcreRegex.Substitute("hello, world!!!", @"\p{P}+", "<$0>", PcreOptions.None, PcreSubstituteOptions.SubstituteGlobal);
+Assert.That(result, Is.EqualTo("hello<,> world<!!!>"));
+```
+
 - Partial matching:
 
 ```C#

src/PCRE.NET.Tests/PcreNet/SubstituteTests.cs

@@ -138,4 +138,11 @@ public void should_handle_offset_limit()
         Assert.That(re.Substitute("foobar", "abc", 0, PcreSubstituteOptions.None, new PcreMatchSettings { OffsetLimit = 3 }), Is.EqualTo("fooabc"));
         Assert.That(re.Substitute("foobar", "abc", 0, PcreSubstituteOptions.None, new PcreMatchSettings { OffsetLimit = 2 }), Is.EqualTo("foobar"));
     }
+
+    [Test]
+    public void readme_replace_example()
+    {
+        var result = PcreRegex.Substitute("hello, world!!!", @"\p{P}+", "<$0>", PcreOptions.None, PcreSubstituteOptions.SubstituteGlobal);
+        Assert.That(result, Is.EqualTo("hello<,> world<!!!>"));
+    }
 }

src/PCRE.NET/PcreRegex.Substitute.cs

@@ -111,4 +111,24 @@ public string Substitute(ReadOnlySpan<char> subject, ReadOnlySpan<char> replacem
 
         return InternalRegex.Substitute(subject, null, replacement, settings, startIndex, options.ToSubstituteOptions());
     }
+
+    /// <include file='PcreRegex.xml' path='/doc/method[@name="Substitute"]/*'/>
+    /// <include file='PcreRegex.xml' path='/doc/param[@name="subject" or @name="pattern" or @name="replacement"]'/>
+    /// <remarks>
+    /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static" or @name="replacementStringPcre2"]/*'/>
+    /// </remarks>
+    /// <seealso cref="Replace(string,string)"/>
+    [Pure]
+    public static string Substitute(string subject, string pattern, string replacement)
+        => Substitute(subject, pattern, replacement, PcreOptions.None, PcreSubstituteOptions.None);
+
+    /// <include file='PcreRegex.xml' path='/doc/method[@name="Substitute"]/*'/>
+    /// <include file='PcreRegex.xml' path='/doc/param[@name="subject" or @name="pattern" or @name="replacement" or @name="patternOptions" or @name="substituteOptions"]'/>
+    /// <remarks>
+    /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static" or @name="replacementStringPcre2"]/*'/>
+    /// </remarks>
+    /// <seealso cref="Replace(string,string)"/>
+    [Pure]
+    public static string Substitute(string subject, string pattern, string replacement, PcreOptions patternOptions, PcreSubstituteOptions substituteOptions)
+        => new PcreRegex(pattern, patternOptions).Substitute(subject, replacement, substituteOptions);
 }

src/PCRE.NET/PcreRegex.xml

@@ -61,6 +61,8 @@
   <param name="count">The maximum number of matches to attempt.</param>
   <param name="startIndex">The index at which the match should be attempted.</param>
   <param name="options">Additional options.</param>
+  <param name="patternOptions">Additional options for the pattern.</param>
+  <param name="substituteOptions">Additional options for the substitution.</param>
   <param name="splitOptions">Additional options for the split.</param>
   <param name="onCallout">A function to be called when a callout point is reached during the match.</param>
   <param name="settings">Additional advanced settings.</param>