Enhance StrSubtstitutor with StringBuffer methods and replaceIn() methods

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@430176 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/lang/text/StrSubstitutor.java

@@ -248,8 +248,51 @@ public class StrSubstitutor {
 
     //-----------------------------------------------------------------------
     /**
-     * Replaces all the occurrences of variables in the given source array with
+     * Replaces all the occurrences of variables with their matching values
-     * their matching values from the resolver.
+     * from the resolver using the given source string as a template.
+     *
+     * @param source  the string to replace in, null returns null
+     * @return the result of the replace operation
+     */
+    public String replace(String source) {
+        if (source == null) {
+            return null;
+        }
+        StrBuilder buf = new StrBuilder(source);
+        if (substitute(buf, 0, source.length()) == false) {
+            return source;
+        }
+        return buf.toString();
+    }
+
+    /**
+     * Replaces all the occurrences of variables with their matching values
+     * from the resolver using the given source string as a template.
+     * <p>
+     * Only the specified portion of the string will be processed.
+     * The rest of the string is not processed, and is not returned.
+     *
+     * @param source  the string to replace in, null returns null
+     * @param offset  the start offset within the array, must be valid
+     * @param length  the length within the array to be processed, must be valid
+     * @return the result of the replace operation
+     */
+    public String replace(String source, int offset, int length) {
+        if (source == null) {
+            return null;
+        }
+        StrBuilder buf = new StrBuilder(length).append(source, offset, length);
+        if (substitute(buf, 0, length) == false) {
+            return source.substring(offset, offset + length);
+        }
+        return buf.toString();
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Replaces all the occurrences of variables with their matching values
+     * from the resolver using the given source array as a template.
+     * The array is not altered by this method.
      *
      * @param source  the character array to replace in, not altered, null returns null
      * @return the result of the replace operation
@@ -264,9 +307,12 @@ public class StrSubstitutor {
     }
 
     /**
-     * Replaces all the occurrences of variables in the given source array by with
+     * Replaces all the occurrences of variables with their matching values
-     * their matching values from the resolver.
+     * from the resolver using the given source array as a template.
+     * The array is not altered by this method.
+     * <p>
      * Only the specified portion of the array will be processed.
+     * The rest of the array is not processed, and is not returned.
      *
      * @param source  the character array to replace in, not altered, null returns null
      * @param offset  the start offset within the array, must be valid
@@ -284,41 +330,81 @@ public class StrSubstitutor {
 
     //-----------------------------------------------------------------------
     /**
-     * Replaces all the occurrences of variables in the given source string with
+     * Replaces all the occurrences of variables with their matching values
-     * their matching values from the resolver.
+     * from the resolver using the given source buffer as a template.
+     * The buffer is not altered by this method.
      *
-     * @param source  the string to replace in, null returns null
+     * @param source  the buffer to use as a template, not changed, null returns null
      * @return the result of the replace operation
      */
-    public String replace(String source) {
+    public String replace(StringBuffer source) {
         if (source == null) {
             return null;
         }
-        StrBuilder buf = new StrBuilder(source);
+        StrBuilder buf = new StrBuilder(source.length()).append(source);
-        if (substitute(buf, 0, source.length()) == false) {
+        substitute(buf, 0, buf.length());
-            return source;
-        }
         return buf.toString();
     }
 
     /**
-     * Replaces all the occurrences of variables in the given source string by with
+     * Replaces all the occurrences of variables with their matching values
-     * their matching values from the resolver.
+     * from the resolver using the given source buffer as a template.
-     * Only the specified portion of the string will be processed.
+     * The buffer is not altered by this method.
+     * <p>
+     * Only the specified portion of the buffer will be processed.
+     * The rest of the buffer is not processed, and is not returned.
      *
-     * @param source  the string to replace in, null returns null
+     * @param source  the buffer to use as a template, not changed, null returns null
      * @param offset  the start offset within the array, must be valid
      * @param length  the length within the array to be processed, must be valid
      * @return the result of the replace operation
      */
-    public String replace(String source, int offset, int length) {
+    public String replace(StringBuffer source, int offset, int length) {
         if (source == null) {
             return null;
         }
         StrBuilder buf = new StrBuilder(length).append(source, offset, length);
-        if (substitute(buf, 0, length) == false) {
+        substitute(buf, 0, length);
-            return source.substring(offset, offset + length);
+        return buf.toString();
     }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Replaces all the occurrences of variables with their matching values
+     * from the resolver using the given source builder as a template.
+     * The builder is not altered by this method.
+     *
+     * @param source  the builder to use as a template, not changed, null returns null
+     * @return the result of the replace operation
+     */
+    public String replace(StrBuilder source) {
+        if (source == null) {
+            return null;
+        }
+        StrBuilder buf = new StrBuilder(source.length()).append(source);
+        substitute(buf, 0, buf.length());
+        return buf.toString();
+    }
+
+    /**
+     * Replaces all the occurrences of variables with their matching values
+     * from the resolver using the given source builder as a template.
+     * The builder is not altered by this method.
+     * <p>
+     * Only the specified portion of the builder will be processed.
+     * The rest of the builder is not processed, and is not returned.
+     *
+     * @param source  the builder to use as a template, not changed, null returns null
+     * @param offset  the start offset within the array, must be valid
+     * @param length  the length within the array to be processed, must be valid
+     * @return the result of the replace operation
+     */
+    public String replace(StrBuilder source, int offset, int length) {
+        if (source == null) {
+            return null;
+        }
+        StrBuilder buf = new StrBuilder(length).append(source, offset, length);
+        substitute(buf, 0, length);
         return buf.toString();
     }
 
@@ -340,6 +426,47 @@ public class StrSubstitutor {
         return buf.toString();
     }
 
+    //-----------------------------------------------------------------------
+    /**
+     * Replaces all the occurrences of variables within the given source buffer
+     * with their matching values from the resolver.
+     * The buffer is updated with the result.
+     *
+     * @param source  the buffer to replace in, updated, null returns zero
+     * @return true if altered
+     */
+    public boolean replaceIn(StringBuffer source) {
+        if (source == null) {
+            return false;
+        }
+        return replaceIn(source, 0, source.length());
+    }
+
+    /**
+     * Replaces all the occurrences of variables within the given source buffer
+     * with their matching values from the resolver.
+     * The buffer is updated with the result.
+     * <p>
+     * Only the specified portion of the buffer will be processed.
+     * The rest of the buffer is not processed, but it is not deleted.
+     *
+     * @param source  the buffer to replace in, updated, null returns zero
+     * @param offset  the start offset within the array, must be valid
+     * @param length  the length within the buffer to be processed, must be valid
+     * @return true if altered
+     */
+    public boolean replaceIn(StringBuffer source, int offset, int length) {
+        if (source == null) {
+            return false;
+        }
+        StrBuilder buf = new StrBuilder(length).append(source, offset, length);
+        if (substitute(buf, 0, length) == false) {
+            return false;
+        }
+        source.replace(offset, offset + length, buf.toString());
+        return true;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Replaces all the occurrences of variables within the given source
@@ -348,7 +475,7 @@ public class StrSubstitutor {
      * @param source  the builder to replace in, updated, null returns zero
      * @return true if altered
      */
-    public boolean replace(StrBuilder source) {
+    public boolean replaceIn(StrBuilder source) {
         if (source == null) {
             return false;
         }
@@ -358,15 +485,16 @@ public class StrSubstitutor {
     /**
      * Replaces all the occurrences of variables within the given source
      * builder with their matching values from the resolver.
-     * Only the specified portion of the builder will be processed, with
+     * <p>
-     * the remainder left untouched.
+     * Only the specified portion of the builder will be processed.
+     * The rest of the builder is not processed, but it is not deleted.
      *
      * @param source  the builder to replace in, null returns zero
      * @param offset  the start offset within the array, must be valid
-     * @param length  the length within the array to be processed, must be valid
+     * @param length  the length within the builder to be processed, must be valid
      * @return true if altered
      */
-    public boolean replace(StrBuilder source, int offset, int length) {
+    public boolean replaceIn(StrBuilder source, int offset, int length) {
         if (source == null) {
             return false;
         }

src/test/org/apache/commons/lang/text/StrSubstitutorTest.java

@@ -19,6 +19,8 @@ package org.apache.commons.lang.text;
 import java.util.HashMap;
 import java.util.Map;
 
+import org.apache.commons.lang.mutable.MutableObject;
+
 import junit.framework.Test;
 import junit.framework.TestCase;
 import junit.framework.TestSuite;
@@ -289,7 +291,7 @@ public class StrSubstitutorTest extends TestCase {
                 return "jakarta";
             }
         };
-        sub.replace(builder);
+        sub.replaceIn(builder);
         assertEquals("Hi jakarta!", builder.toString());
     }
 
@@ -432,47 +434,81 @@ public class StrSubstitutorTest extends TestCase {
     //-----------------------------------------------------------------------
     private void doTestReplace(String expectedResult, String replaceTemplate, boolean substring) {
         String expectedShortResult = expectedResult.substring(1, expectedResult.length() - 1);
-        
         StrSubstitutor sub = new StrSubstitutor(values);
+        
+        // replace using String
         assertEquals(expectedResult, sub.replace(replaceTemplate));
         if (substring) {
             assertEquals(expectedShortResult, sub.replace(replaceTemplate, 1, replaceTemplate.length() - 2));
         }
         
+        // replace using char[]
         char[] chars = replaceTemplate.toCharArray();
         assertEquals(expectedResult, sub.replace(chars));
         if (substring) {
             assertEquals(expectedShortResult, sub.replace(chars, 1, chars.length - 2));
         }
         
+        // replace using StringBuffer
         StringBuffer buf = new StringBuffer(replaceTemplate);
         assertEquals(expectedResult, sub.replace(buf));
+        if (substring) {
+            assertEquals(expectedShortResult, sub.replace(buf, 1, buf.length() - 2));
+        }
         
+        // replace using StrBuilder
         StrBuilder bld = new StrBuilder(replaceTemplate);
-        assertEquals(true, sub.replace(bld));
+        assertEquals(expectedResult, sub.replace(bld));
-        assertEquals(expectedResult, bld.toString());
+        if (substring) {
+            assertEquals(expectedShortResult, sub.replace(bld, 1, bld.length() - 2));
+        }
         
+        // replace using object
+        MutableObject obj = new MutableObject(replaceTemplate);  // toString returns template
+        assertEquals(expectedResult, sub.replace(obj));
+        
+        // replace in StringBuffer
+        buf = new StringBuffer(replaceTemplate);
+        assertEquals(true, sub.replaceIn(buf));
+        assertEquals(expectedResult, buf.toString());
+        if (substring) {
+            buf = new StringBuffer(replaceTemplate);
+            assertEquals(true, sub.replaceIn(buf, 1, buf.length() - 2));
+            assertEquals(expectedResult, buf.toString());  // expect full result as remainder is untouched
+        }
+        
+        // replace in StrBuilder
+        bld = new StrBuilder(replaceTemplate);
+        assertEquals(true, sub.replaceIn(bld));
+        assertEquals(expectedResult, bld.toString());
         if (substring) {
             bld = new StrBuilder(replaceTemplate);
-            assertEquals(true, sub.replace(bld, 1, bld.length() - 2));
+            assertEquals(true, sub.replaceIn(bld, 1, bld.length() - 2));
             assertEquals(expectedResult, bld.toString());  // expect full result as remainder is untouched
         }
     }
 
     private void doTestNoReplace(String replaceTemplate) {
         StrSubstitutor sub = new StrSubstitutor(values);
-        assertEquals(replaceTemplate, sub.replace(replaceTemplate));
         
         if (replaceTemplate == null) {
+            assertEquals(null, sub.replace((String) null));
             assertEquals(null, sub.replace((String) null, 0, 100));
             assertEquals(null, sub.replace((char[]) null));
             assertEquals(null, sub.replace((char[]) null, 0, 100));
+            assertEquals(null, sub.replace((StringBuffer) null));
+            assertEquals(null, sub.replace((StringBuffer) null, 0, 100));
+            assertEquals(null, sub.replace((StrBuilder) null));
+            assertEquals(null, sub.replace((StrBuilder) null, 0, 100));
             assertEquals(null, sub.replace((Object) null));
-            assertEquals(false, sub.replace((StrBuilder) null));
+            assertEquals(false, sub.replaceIn((StringBuffer) null));
-            assertEquals(false, sub.replace((StrBuilder) null, 0, 100));
+            assertEquals(false, sub.replaceIn((StringBuffer) null, 0, 100));
+            assertEquals(false, sub.replaceIn((StrBuilder) null));
+            assertEquals(false, sub.replaceIn((StrBuilder) null, 0, 100));
         } else {
+            assertEquals(replaceTemplate, sub.replace(replaceTemplate));
             StrBuilder bld = new StrBuilder(replaceTemplate);
-            assertEquals(false, sub.replace(bld));
+            assertEquals(false, sub.replaceIn(bld));
             assertEquals(replaceTemplate, bld.toString());
         }
     }