LANG-306 - StrBuilder appendln/appendAll/appendSeparator

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

RELEASE-NOTES.txt

@@ -56,9 +56,9 @@ as int not long. The replacements are MILLIS_PER_*.
 
 BUG FIXES IN 2.3:
 
-    * [LANG-69 ] - [lang] ToStringBuilder throws StackOverflowError when an Object cycle exists
+    * [LANG-69 ] - ToStringBuilder throws StackOverflowError when an Object cycle exists
-    * [LANG-102] - [lang] Refactor Entities methods
+    * [LANG-102] - Refactor Entities methods
-    * [LANG-153] - [lang] Can't XMLDecode an Enum
+    * [LANG-153] - Can't XMLDecode an Enum
     * [LANG-262] - Use of enum prevents a classloader from being garbage collected resuling in out of memory exceptions.
     * [LANG-279] - HashCodeBuilder throws java.lang.StackOverflowError when an object contains a cycle.
     * [LANG-281] - DurationFormatUtils returns wrong result
@@ -73,7 +73,6 @@ BUG FIXES IN 2.3:
 
 IMPROVEMENTS IN 2.3:
 
-    * [LANG-238] - [lang] Add equals(type[]) to NumberUtils
     * [LANG-258] - Enum JavaDoc
     * [LANG-268] - StringUtils.join should allow you to pass a range for it (so it only joins a part of the array)
     * [LANG-287] - Optimize StringEscapeUtils.unescapeXml(String)
@@ -82,4 +81,5 @@ IMPROVEMENTS IN 2.3:
     * [LANG-282] - Create more tests to test out the +=31 replacement code in DurationFormatUtils.
     * [LANG-266] - Wish for StringUtils.join(Collection, *)
     * [LANG-310] - BooleanUtils isNotTrue/isNotFalse
+    * [LANG-306] - StrBuilder appendln/appendAll/appendSeparator
 

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

@@ -731,6 +731,227 @@ public StrBuilder append(double value) {
         return append(String.valueOf(value));
     }
 
+    //-----------------------------------------------------------------------
+    /**
+     * Appends an object followed by a new line to this string builder.
+     * Appending null will call {@link #appendNull()}.
+     *
+     * @param obj  the object to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(Object obj) {
+        return append(obj).appendNewLine();
+    }
+
+    /**
+     * Appends a string followed by a new line to this string builder.
+     * Appending null will call {@link #appendNull()}.
+     *
+     * @param str  the string to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(String str) {
+        return append(str).appendNewLine();
+    }
+
+    /**
+     * Appends part of a string followed by a new line to this string builder.
+     * Appending null will call {@link #appendNull()}.
+     *
+     * @param str  the string to append
+     * @param startIndex  the start index, inclusive, must be valid
+     * @param length  the length to append, must be valid
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(String str, int startIndex, int length) {
+        return append(str, startIndex, length).appendNewLine();
+    }
+
+    /**
+     * Appends a string buffer followed by a new line to this string builder.
+     * Appending null will call {@link #appendNull()}.
+     *
+     * @param str  the string buffer to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(StringBuffer str) {
+        return append(str).appendNewLine();
+    }
+
+    /**
+     * Appends part of a string buffer followed by a new line to this string builder.
+     * Appending null will call {@link #appendNull()}.
+     *
+     * @param str  the string to append
+     * @param startIndex  the start index, inclusive, must be valid
+     * @param length  the length to append, must be valid
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(StringBuffer str, int startIndex, int length) {
+        return append(str, startIndex, length).appendNewLine();
+    }
+
+    /**
+     * Appends another string builder followed by a new line to this string builder.
+     * Appending null will call {@link #appendNull()}.
+     *
+     * @param str  the string builder to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(StrBuilder str) {
+        return append(str).appendNewLine();
+    }
+
+    /**
+     * Appends part of a string builder followed by a new line to this string builder.
+     * Appending null will call {@link #appendNull()}.
+     *
+     * @param str  the string to append
+     * @param startIndex  the start index, inclusive, must be valid
+     * @param length  the length to append, must be valid
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(StrBuilder str, int startIndex, int length) {
+        return append(str, startIndex, length).appendNewLine();
+    }
+
+    /**
+     * Appends a char array followed by a new line to the string builder.
+     * Appending null will call {@link #appendNull()}.
+     *
+     * @param chars  the char array to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(char[] chars) {
+        return append(chars).appendNewLine();
+    }
+
+    /**
+     * Appends a char array followed by a new line to the string builder.
+     * Appending null will call {@link #appendNull()}.
+     *
+     * @param chars  the char array to append
+     * @param startIndex  the start index, inclusive, must be valid
+     * @param length  the length to append, must be valid
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(char[] chars, int startIndex, int length) {
+        return append(chars, startIndex, length).appendNewLine();
+    }
+
+    /**
+     * Appends a boolean value followed by a new line to the string builder.
+     *
+     * @param value  the value to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(boolean value) {
+        return append(value).appendNewLine();
+    }
+
+    /**
+     * Appends a char value followed by a new line to the string builder.
+     *
+     * @param ch  the value to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(char ch) {
+        return append(ch).appendNewLine();
+    }
+
+    /**
+     * Appends an int value followed by a new line to the string builder using <code>String.valueOf</code>.
+     *
+     * @param value  the value to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(int value) {
+        return append(value).appendNewLine();
+    }
+
+    /**
+     * Appends a long value followed by a new line to the string builder using <code>String.valueOf</code>.
+     *
+     * @param value  the value to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(long value) {
+        return append(value).appendNewLine();
+    }
+
+    /**
+     * Appends a float value followed by a new line to the string builder using <code>String.valueOf</code>.
+     *
+     * @param value  the value to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(float value) {
+        return append(value).appendNewLine();
+    }
+
+    /**
+     * Appends a double value followed by a new line to the string builder using <code>String.valueOf</code>.
+     *
+     * @param value  the value to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendln(double value) {
+        return append(value).appendNewLine();
+    }
+
+    //-----------------------------------------------------------------------
+    /**
+     * Appends each item in an array to the builder without any separators.
+     * Appending a null array will have no effect.
+     * Each object is appended using {@link #append(Object)}.
+     *
+     * @param array  the array to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendAll(Object[] array) {
+        if (array != null && array.length > 0) {
+            for (int i = 0; i < array.length; i++) {
+                append(array[i]);
+            }
+        }
+        return this;
+    }
+
+    /**
+     * Appends each item in a collection to the builder without any separators.
+     * Appending a null collection will have no effect.
+     * Each object is appended using {@link #append(Object)}.
+     *
+     * @param coll  the collection to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendAll(Collection coll) {
+        if (coll != null && coll.size() > 0) {
+            Iterator it = coll.iterator();
+            while (it.hasNext()) {
+                append(it.next());
+            }
+        }
+        return this;
+    }
+
+    /**
+     * Appends each item in an iterator to the builder without any separators.
+     * Appending a null iterator will have no effect.
+     * Each object is appended using {@link #append(Object)}.
+     *
+     * @param it  the iterator to append
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendAll(Iterator it) {
+        if (it != null) {
+            while (it.hasNext()) {
+                append(it.next());
+            }
+        }
+        return this;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Appends an array placing separators between each value, but
@@ -801,6 +1022,111 @@ public StrBuilder appendWithSeparators(Iterator it, String separator) {
         return this;
     }
 
+    //-----------------------------------------------------------------------
+    /**
+     * Appends a separator if the builder is currently non-empty.
+     * Appending a null separator will have no effect.
+     * The separator is appended using {@link #append(String)}.
+     * <p>
+     * This method is useful for adding a separator each time around the
+     * loop except the first.
+     * <pre>
+     * for (Iterator it = list.iterator(); it.hasNext(); ) {
+     *   appendSeparator(",");
+     *   append(it.next());
+     * }
+     * </pre>
+     * Note that for this simple example, you should use
+     * {@link #appendWithSeparators(Collection, String)}.
+     * 
+     * @param separator  the separator to use, null means no separator
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendSeparator(String separator) {
+        if (separator != null && size() > 0) {
+            append(separator);
+        }
+        return this;
+    }
+
+    /**
+     * Appends a separator if the builder is currently non-empty.
+     * The separator is appended using {@link #append(char)}.
+     * <p>
+     * This method is useful for adding a separator each time around the
+     * loop except the first.
+     * <pre>
+     * for (Iterator it = list.iterator(); it.hasNext(); ) {
+     *   appendSeparator(',');
+     *   append(it.next());
+     * }
+     * </pre>
+     * Note that for this simple example, you should use
+     * {@link #appendWithSeparators(Collection, String)}.
+     * 
+     * @param separator  the separator to use
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendSeparator(char separator) {
+        if (size() > 0) {
+            append(separator);
+        }
+        return this;
+    }
+
+    /**
+     * Appends a separator to the builder if the loop index is greater than zero.
+     * Appending a null separator will have no effect.
+     * The separator is appended using {@link #append(String)}.
+     * <p>
+     * This method is useful for adding a separator each time around the
+     * loop except the first.
+     * <pre>
+     * for (int i = 0; i < list.size(); i++) {
+     *   appendSeparator(",", i);
+     *   append(list.get(i));
+     * }
+     * </pre>
+     * Note that for this simple example, you should use
+     * {@link #appendWithSeparators(Collection, String)}.
+     * 
+     * @param separator  the separator to use, null means no separator
+     * @param loopIndex  the loop index
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendSeparator(String separator, int loopIndex) {
+        if (separator != null && loopIndex > 0) {
+            append(separator);
+        }
+        return this;
+    }
+
+    /**
+     * Appends a separator to the builder if the loop index is greater than zero.
+     * The separator is appended using {@link #append(char)}.
+     * <p>
+     * This method is useful for adding a separator each time around the
+     * loop except the first.
+     * <pre>
+     * for (int i = 0; i < list.size(); i++) {
+     *   appendSeparator(",", i);
+     *   append(list.get(i));
+     * }
+     * </pre>
+     * Note that for this simple example, you should use
+     * {@link #appendWithSeparators(Collection, String)}.
+     * 
+     * @param separator  the separator to use
+     * @param loopIndex  the loop index
+     * @return this, to enable chaining
+     */
+    public StrBuilder appendSeparator(char separator, int loopIndex) {
+        if (loopIndex > 0) {
+            append(separator);
+        }
+        return this;
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Appends the pad character to the builder the specified number of times.

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

@@ -22,13 +22,13 @@
 import java.util.Collections;
 import java.util.Iterator;
 
-import org.apache.commons.lang.SystemUtils;
-
 import junit.framework.Test;
 import junit.framework.TestCase;
 import junit.framework.TestSuite;
 import junit.textui.TestRunner;
 
+import org.apache.commons.lang.SystemUtils;
+
 /**
  * Unit tests for {@link org.apache.commons.lang.text.StrBuilder}.
  *
@@ -36,6 +36,9 @@
  */
 public class StrBuilderAppendInsertTest extends TestCase {
 
+    /** The system line separator. */
+    private static final String SEP = SystemUtils.LINE_SEPARATOR;
+
     /** Test subclass of Object, with a toString method. */
     private static Object FOO = new Object() {
         public String toString() {
@@ -76,11 +79,11 @@ public StrBuilderAppendInsertTest(String name) {
     public void testAppendNewLine() {
         StrBuilder sb = new StrBuilder("---");
         sb.appendNewLine().append("+++");
-        assertEquals("---" + SystemUtils.LINE_SEPARATOR + "+++", sb.toString());
+        assertEquals("---" + SEP + "+++", sb.toString());
         
         sb = new StrBuilder("---");
         sb.setNewLineText("#").appendNewLine().setNewLineText(null).appendNewLine();
-        assertEquals("---#" + SystemUtils.LINE_SEPARATOR, sb.toString());
+        assertEquals("---#" + SEP, sb.toString());
     }
 
     //-----------------------------------------------------------------------
@@ -438,7 +441,7 @@ public void testAppend_CharArray_int_int() {
     }
 
     //-----------------------------------------------------------------------
-    public void testAppend_Primitive() {
+    public void testAppend_Boolean() {
         StrBuilder sb = new StrBuilder();
         sb.append(true);
         assertEquals("true", sb.toString());
@@ -466,6 +469,201 @@ public void testAppend_PrimitiveNumber() {
         assertEquals("012.34.5", sb.toString());
     }
 
+    //-----------------------------------------------------------------------
+    public void testAppendln_Object() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendln((Object) null);
+        assertEquals("" + SEP, sb.toString());
+
+        sb.appendln((Object) FOO);
+        assertEquals(SEP + "foo" + SEP, sb.toString());
+
+        sb.appendln(new Integer(6));
+        assertEquals(SEP + "foo" + SEP + "6" + SEP, sb.toString());
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_String() {
+        final int[] count = new int[2];
+        StrBuilder sb = new StrBuilder() {
+            public StrBuilder append(String str) {
+                count[0]++;
+                return super.append(str);
+            }
+            public StrBuilder appendNewLine() {
+                count[1]++;
+                return super.appendNewLine();
+            }
+        };
+        sb.appendln("foo");
+        assertEquals("foo" + SEP, sb.toString());
+        assertEquals(2, count[0]);  // appendNewLine() calls append(String)
+        assertEquals(1, count[1]);
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_String_int_int() {
+        final int[] count = new int[2];
+        StrBuilder sb = new StrBuilder() {
+            public StrBuilder append(String str, int startIndex, int length) {
+                count[0]++;
+                return super.append(str, startIndex, length);
+            }
+            public StrBuilder appendNewLine() {
+                count[1]++;
+                return super.appendNewLine();
+            }
+        };
+        sb.appendln("foo", 0, 3);
+        assertEquals("foo" + SEP, sb.toString());
+        assertEquals(1, count[0]);
+        assertEquals(1, count[1]);
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_StringBuffer() {
+        final int[] count = new int[2];
+        StrBuilder sb = new StrBuilder() {
+            public StrBuilder append(StringBuffer str) {
+                count[0]++;
+                return super.append(str);
+            }
+            public StrBuilder appendNewLine() {
+                count[1]++;
+                return super.appendNewLine();
+            }
+        };
+        sb.appendln(new StringBuffer("foo"));
+        assertEquals("foo" + SEP, sb.toString());
+        assertEquals(1, count[0]);
+        assertEquals(1, count[1]);
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_StringBuffer_int_int() {
+        final int[] count = new int[2];
+        StrBuilder sb = new StrBuilder() {
+            public StrBuilder append(StringBuffer str, int startIndex, int length) {
+                count[0]++;
+                return super.append(str, startIndex, length);
+            }
+            public StrBuilder appendNewLine() {
+                count[1]++;
+                return super.appendNewLine();
+            }
+        };
+        sb.appendln(new StringBuffer("foo"), 0, 3);
+        assertEquals("foo" + SEP, sb.toString());
+        assertEquals(1, count[0]);
+        assertEquals(1, count[1]);
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_StrBuilder() {
+        final int[] count = new int[2];
+        StrBuilder sb = new StrBuilder() {
+            public StrBuilder append(StrBuilder str) {
+                count[0]++;
+                return super.append(str);
+            }
+            public StrBuilder appendNewLine() {
+                count[1]++;
+                return super.appendNewLine();
+            }
+        };
+        sb.appendln(new StrBuilder("foo"));
+        assertEquals("foo" + SEP, sb.toString());
+        assertEquals(1, count[0]);
+        assertEquals(1, count[1]);
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_StrBuilder_int_int() {
+        final int[] count = new int[2];
+        StrBuilder sb = new StrBuilder() {
+            public StrBuilder append(StrBuilder str, int startIndex, int length) {
+                count[0]++;
+                return super.append(str, startIndex, length);
+            }
+            public StrBuilder appendNewLine() {
+                count[1]++;
+                return super.appendNewLine();
+            }
+        };
+        sb.appendln(new StrBuilder("foo"), 0, 3);
+        assertEquals("foo" + SEP, sb.toString());
+        assertEquals(1, count[0]);
+        assertEquals(1, count[1]);
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_CharArray() {
+        final int[] count = new int[2];
+        StrBuilder sb = new StrBuilder() {
+            public StrBuilder append(char[] str) {
+                count[0]++;
+                return super.append(str);
+            }
+            public StrBuilder appendNewLine() {
+                count[1]++;
+                return super.appendNewLine();
+            }
+        };
+        sb.appendln("foo".toCharArray());
+        assertEquals("foo" + SEP, sb.toString());
+        assertEquals(1, count[0]);
+        assertEquals(1, count[1]);
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_CharArray_int_int() {
+        final int[] count = new int[2];
+        StrBuilder sb = new StrBuilder() {
+            public StrBuilder append(char[] str, int startIndex, int length) {
+                count[0]++;
+                return super.append(str, startIndex, length);
+            }
+            public StrBuilder appendNewLine() {
+                count[1]++;
+                return super.appendNewLine();
+            }
+        };
+        sb.appendln("foo".toCharArray(), 0, 3);
+        assertEquals("foo" + SEP, sb.toString());
+        assertEquals(1, count[0]);
+        assertEquals(1, count[1]);
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_Boolean() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendln(true);
+        assertEquals("true" + SEP, sb.toString());
+        
+        sb.clear();
+        sb.appendln(false);
+        assertEquals("false" + SEP, sb.toString());
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendln_PrimitiveNumber() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendln(0);
+        assertEquals("0" + SEP, sb.toString());
+        
+        sb.clear();
+        sb.appendln(1L);
+        assertEquals("1" + SEP, sb.toString());
+        
+        sb.clear();
+        sb.appendln(2.3f);
+        assertEquals("2.3" + SEP, sb.toString());
+        
+        sb.clear();
+        sb.appendln(4.5d);
+        assertEquals("4.5" + SEP, sb.toString());
+    }
+
     //-----------------------------------------------------------------------
     public void testAppendPadding() {
         StrBuilder sb = new StrBuilder();
@@ -636,6 +834,51 @@ public void testAppendFixedWidthPadRight_int() {
         assertEquals("123-------", sb.toString());
     }
 
+    //-----------------------------------------------------------------------
+    public void testAppendAll_Array() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendAll((Object[]) null);
+        assertEquals("", sb.toString());
+
+        sb.clear();
+        sb.appendAll(new Object[0]);
+        assertEquals("", sb.toString());
+
+        sb.clear();
+        sb.appendAll(new Object[]{"foo", "bar", "baz"});
+        assertEquals("foobarbaz", sb.toString());
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendAll_Collection() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendAll((Collection) null);
+        assertEquals("", sb.toString());
+
+        sb.clear();
+        sb.appendAll(Collections.EMPTY_LIST);
+        assertEquals("", sb.toString());
+
+        sb.clear();
+        sb.appendAll(Arrays.asList(new Object[]{"foo", "bar", "baz"}));
+        assertEquals("foobarbaz", sb.toString());
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendAll_Iterator() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendAll((Iterator) null);
+        assertEquals("", sb.toString());
+
+        sb.clear();
+        sb.appendAll(Collections.EMPTY_LIST.iterator());
+        assertEquals("", sb.toString());
+
+        sb.clear();
+        sb.appendAll(Arrays.asList(new Object[]{"foo", "bar", "baz"}).iterator());
+        assertEquals("foobarbaz", sb.toString());
+    }
+
     //-----------------------------------------------------------------------
     public void testAppendWithSeparators_Array() {
         StrBuilder sb = new StrBuilder();
@@ -717,6 +960,56 @@ public void testAppendWithSeparatorsWithNullText() {
         assertEquals("foo,null,baz", sb.toString());
     }
 
+    //-----------------------------------------------------------------------
+    public void testAppendSeparator_String() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendSeparator(",");  // no effect
+        assertEquals("", sb.toString());
+        sb.append("foo");
+        assertEquals("foo", sb.toString());
+        sb.appendSeparator(",");
+        assertEquals("foo,", sb.toString());
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendSeparator_char() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendSeparator(',');  // no effect
+        assertEquals("", sb.toString());
+        sb.append("foo");
+        assertEquals("foo", sb.toString());
+        sb.appendSeparator(',');
+        assertEquals("foo,", sb.toString());
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendSeparator_String_int() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendSeparator(",", 0);  // no effect
+        assertEquals("", sb.toString());
+        sb.append("foo");
+        assertEquals("foo", sb.toString());
+        sb.appendSeparator(",", 1);
+        assertEquals("foo,", sb.toString());
+        
+        sb.appendSeparator(",", -1);  // no effect
+        assertEquals("foo,", sb.toString());
+    }
+
+    //-----------------------------------------------------------------------
+    public void testAppendSeparator_char_int() {
+        StrBuilder sb = new StrBuilder();
+        sb.appendSeparator(',', 0);  // no effect
+        assertEquals("", sb.toString());
+        sb.append("foo");
+        assertEquals("foo", sb.toString());
+        sb.appendSeparator(',', 1);
+        assertEquals("foo,", sb.toString());
+        
+        sb.appendSeparator(',', -1);  // no effect
+        assertEquals("foo,", sb.toString());
+    }
+
     //-----------------------------------------------------------------------
     public void testInsert() {