From 6b81f9e6cf42eae235c7ab505d967f60a42d7d66 Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@gmail.com>
Date: Thu, 9 Jan 2025 09:26:58 -0500
Subject: [PATCH] Add RegExUtils.replacePattern(CharSequence, String, String)
 and deprecate RegExUtils.replacePattern(String, String, String)

---
 src/changes/changes.xml                       |  1 +
 .../org/apache/commons/lang3/RegExUtils.java  | 51 ++++++++++++++++++-
 .../apache/commons/lang3/RegExUtilsTest.java  | 25 +++++++--
 3 files changed, 72 insertions(+), 5 deletions(-)

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index ba5729756..0ce434521 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -91,6 +91,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add ArrayUtils.startsWith.</action>
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add Predicates.</action>
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add RegExUtils.dotAllMatcher(String, CharSequence) and deprecate RegExUtils.dotAllMatcher(String, String).</action>
+    <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add RegExUtils.replacePattern(CharSequence, String, String) and deprecate RegExUtils.replacePattern(String, String, String).</action>
     <!-- UPDATE -->
     <action                   type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 73 to 78 #1267, #1277, #1283, #1288, #1302.</action>
     <action                   type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[site] Bump org.codehaus.mojo:taglist-maven-plugin from 3.1.0 to 3.2.1 #1300.</action>
diff --git a/src/main/java/org/apache/commons/lang3/RegExUtils.java b/src/main/java/org/apache/commons/lang3/RegExUtils.java
index 824661919..2d190ee4d 100644
--- a/src/main/java/org/apache/commons/lang3/RegExUtils.java
+++ b/src/main/java/org/apache/commons/lang3/RegExUtils.java
@@ -252,7 +252,7 @@ public class RegExUtils {
      * @param regex
      *            the regular expression to which this string is to be matched
      * @return The resulting {@link String}
-     * @see #replacePattern(String, String, String)
+     * @see #replacePattern(CharSequence, String, String)
      * @see String#replaceAll(String, String)
      * @see Pattern#DOTALL
      */
@@ -315,7 +315,7 @@ public class RegExUtils {
      *
      * <p>A {@code null} reference passed to this method is a no-op.</p>
      *
-     * <p>Unlike in the {@link #replacePattern(String, String, String)} method, the {@link Pattern#DOTALL} option
+     * <p>Unlike in the {@link #replacePattern(CharSequence, String, String)} method, the {@link Pattern#DOTALL} option
      * is NOT automatically added.
      * To use the DOTALL option prepend {@code "(?s)"} to the regex.
      * DOTALL is also known as single-line mode in Perl.</p>
@@ -488,7 +488,54 @@ public class RegExUtils {
      * @see #replaceAll(String, String, String)
      * @see String#replaceAll(String, String)
      * @see Pattern#DOTALL
+     * @since 3.18.0
      */
+    public static CharSequence replacePattern(final CharSequence text, final String regex, final String replacement) {
+        if (ObjectUtils.anyNull(text, regex, replacement)) {
+            return text;
+        }
+        return dotAllMatcher(regex, text).replaceAll(replacement);
+    }
+
+    /**
+     * Replaces each substring of the source String that matches the given regular expression with the given
+     * replacement using the {@link Pattern#DOTALL} option. DOTALL is also known as single-line mode in Perl.
+     *
+     * This call is a {@code null} safe equivalent to:
+     * <ul>
+     * <li>{@code text.replaceAll(&quot;(?s)&quot; + regex, replacement)}</li>
+     * <li>{@code Pattern.compile(regex, Pattern.DOTALL).matcher(text).replaceAll(replacement)}</li>
+     * </ul>
+     *
+     * <p>A {@code null} reference passed to this method is a no-op.</p>
+     *
+     * <pre>{@code
+     * StringUtils.replacePattern(null, *, *)       = null
+     * StringUtils.replacePattern("any", (String) null, *)   = "any"
+     * StringUtils.replacePattern("any", *, null)   = "any"
+     * StringUtils.replacePattern("", "", "zzz")    = "zzz"
+     * StringUtils.replacePattern("", ".*", "zzz")  = "zzz"
+     * StringUtils.replacePattern("", ".+", "zzz")  = ""
+     * StringUtils.replacePattern("<__>\n<__>", "<.*>", "z")       = "z"
+     * StringUtils.replacePattern("ABCabc123", "[a-z]", "_")       = "ABC___123"
+     * StringUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", "_")  = "ABC_123"
+     * StringUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", "")   = "ABC123"
+     * StringUtils.replacePattern("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum_dolor_sit"
+     * }</pre>
+     *
+     * @param text
+     *            the source string
+     * @param regex
+     *            the regular expression to which this string is to be matched
+     * @param replacement
+     *            the string to be substituted for each match
+     * @return The resulting {@link String}
+     * @see #replaceAll(String, String, String)
+     * @see String#replaceAll(String, String)
+     * @see Pattern#DOTALL
+     * @deprecated Use {@link #replacePattern(CharSequence, String, String)}.
+     */
+    @Deprecated
     public static String replacePattern(final String text, final String regex, final String replacement) {
         if (ObjectUtils.anyNull(text, regex, replacement)) {
             return text;
diff --git a/src/test/java/org/apache/commons/lang3/RegExUtilsTest.java b/src/test/java/org/apache/commons/lang3/RegExUtilsTest.java
index 913bd3e70..14ba4f251 100644
--- a/src/test/java/org/apache/commons/lang3/RegExUtilsTest.java
+++ b/src/test/java/org/apache/commons/lang3/RegExUtilsTest.java
@@ -243,7 +243,27 @@ public class RegExUtilsTest extends AbstractLangTest {
     }
 
     @Test
-    public void testReplacePattern_StringStringString() {
+    public void testReplacePattern() {
+        assertNull(RegExUtils.replacePattern((CharSequence) null, "", ""));
+        assertEquals("any", RegExUtils.replacePattern((CharSequence) "any", (String) null, ""));
+        assertEquals("any", RegExUtils.replacePattern((CharSequence) "any", "", null));
+
+        assertEquals("zzz", RegExUtils.replacePattern((CharSequence) "", "", "zzz"));
+        assertEquals("zzz", RegExUtils.replacePattern((CharSequence) "", ".*", "zzz"));
+        assertEquals("", RegExUtils.replacePattern((CharSequence) "", ".+", "zzz"));
+
+        assertEquals("z", RegExUtils.replacePattern((CharSequence) "<__>\n<__>", "<.*>", "z"));
+        assertEquals("z", RegExUtils.replacePattern((CharSequence) "<__>\\n<__>", "<.*>", "z"));
+        assertEquals("X", RegExUtils.replacePattern((CharSequence) "<A>\nxy\n</A>", "<A>.*</A>", "X"));
+
+        assertEquals("ABC___123", RegExUtils.replacePattern((CharSequence) "ABCabc123", "[a-z]", "_"));
+        assertEquals("ABC_123", RegExUtils.replacePattern((CharSequence) "ABCabc123", "[^A-Z0-9]+", "_"));
+        assertEquals("ABC123", RegExUtils.replacePattern((CharSequence) "ABCabc123", "[^A-Z0-9]+", ""));
+        assertEquals("Lorem_ipsum_dolor_sit", RegExUtils.replacePattern((CharSequence) "Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2"));
+    }
+
+    @Test
+    public void testReplacePatternDeprecated() {
         assertNull(RegExUtils.replacePattern(null, "", ""));
         assertEquals("any", RegExUtils.replacePattern("any", (String) null, ""));
         assertEquals("any", RegExUtils.replacePattern("any", "", null));
@@ -259,8 +279,7 @@ public class RegExUtilsTest extends AbstractLangTest {
         assertEquals("ABC___123", RegExUtils.replacePattern("ABCabc123", "[a-z]", "_"));
         assertEquals("ABC_123", RegExUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", "_"));
         assertEquals("ABC123", RegExUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", ""));
-        assertEquals("Lorem_ipsum_dolor_sit",
-                RegExUtils.replacePattern("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2"));
+        assertEquals("Lorem_ipsum_dolor_sit", RegExUtils.replacePattern("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2"));
     }
 
 }