Return-Path: Delivered-To: apmail-jakarta-commons-dev-archive@apache.org Received: (qmail 72978 invoked from network); 15 Jul 2003 23:41:57 -0000 Received: from exchange.sun.com (192.18.33.10) by daedalus.apache.org with SMTP; 15 Jul 2003 23:41:57 -0000 Received: (qmail 21980 invoked by uid 97); 15 Jul 2003 23:44:33 -0000 Delivered-To: qmlist-jakarta-archive-commons-dev@nagoya.betaversion.org Received: (qmail 21973 invoked from network); 15 Jul 2003 23:44:32 -0000 Received: from daedalus.apache.org (HELO apache.org) (208.185.179.12) by nagoya.betaversion.org with SMTP; 15 Jul 2003 23:44:32 -0000 Received: (qmail 72751 invoked by uid 500); 15 Jul 2003 23:41:55 -0000 Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Jakarta Commons Developers List" Reply-To: "Jakarta Commons Developers List" Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 72740 invoked by uid 500); 15 Jul 2003 23:41:55 -0000 Received: (qmail 72737 invoked from network); 15 Jul 2003 23:41:55 -0000 Received: from icarus.apache.org (208.185.179.13) by daedalus.apache.org with SMTP; 15 Jul 2003 23:41:55 -0000 Received: (qmail 85821 invoked by uid 1529); 15 Jul 2003 23:41:54 -0000 Date: 15 Jul 2003 23:41:54 -0000 Message-ID: <20030715234154.85820.qmail@icarus.apache.org> From: scolebourne@apache.org To: jakarta-commons-cvs@apache.org Subject: cvs commit: jakarta-commons/lang/src/java/org/apache/commons/lang StringUtils.java X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N scolebourne 2003/07/15 16:41:54 Modified: lang/src/test/org/apache/commons/lang StringUtilsTest.java lang/src/java/org/apache/commons/lang StringUtils.java Log: Update Javadoc defining empty, space and whitespace Improve performance of repeat Add defaultString(String) back in for performance Revision Changes Path 1.22 +26 -3 jakarta-commons/lang/src/test/org/apache/commons/lang/StringUtilsTest.java Index: StringUtilsTest.java =================================================================== RCS file: /home/cvs/jakarta-commons/lang/src/test/org/apache/commons/lang/StringUtilsTest.java,v retrieving revision 1.21 retrieving revision 1.22 diff -u -r1.21 -r1.22 --- StringUtilsTest.java 23 Jun 2003 03:51:13 -0000 1.21 +++ StringUtilsTest.java 15 Jul 2003 23:41:54 -0000 1.22 @@ -259,8 +259,16 @@ } public void testRepeat() { - assertEquals("repeat(String, int) failed", - FOO + FOO + FOO, StringUtils.repeat(FOO, 3) ); + assertEquals("", StringUtils.repeat("ab", 0)); + assertEquals("", StringUtils.repeat("", 3)); + assertEquals("aaa", StringUtils.repeat("a", 3)); + assertEquals("ababab", StringUtils.repeat("ab", 3)); + assertEquals("abcabcabc", StringUtils.repeat("abc", 3)); + try { + StringUtils.repeat(null, 0); + fail(); + } catch (NullPointerException ex) { + } } public void testCenter() { @@ -436,6 +444,21 @@ FOO, StringUtils.defaultString(FOO, BAR) ); assertEquals("defaultString(null,String) failed", BAR, StringUtils.defaultString(null, BAR) ); + + assertEquals("defaultString((Object) empty-string) failed", + "", StringUtils.defaultString((Object) "") ); + assertEquals("defaultString((Object) String) failed", + FOO, StringUtils.defaultString((Object) FOO) ); + assertEquals("defaultString((Object) null) failed", + "", StringUtils.defaultString((Object) null) ); + assertEquals("defaultString((Object) empty-string,String) failed", + "", StringUtils.defaultString((Object) "", BAR) ); + assertEquals("defaultString((Object) String,String) failed", + FOO, StringUtils.defaultString((Object) FOO, BAR) ); + assertEquals("defaultString((Object) null,String) failed", + BAR, StringUtils.defaultString((Object) null, BAR) ); + assertEquals("defaultString(Boolean.TRUE,String) failed", + Boolean.TRUE.toString(), StringUtils.defaultString(Boolean.TRUE, BAR) ); } public void testEscapeFunctions() { 1.56 +316 -143 jakarta-commons/lang/src/java/org/apache/commons/lang/StringUtils.java Index: StringUtils.java =================================================================== RCS file: /home/cvs/jakarta-commons/lang/src/java/org/apache/commons/lang/StringUtils.java,v retrieving revision 1.55 retrieving revision 1.56 diff -u -r1.55 -r1.56 --- StringUtils.java 14 Jul 2003 23:02:08 -0000 1.55 +++ StringUtils.java 15 Jul 2003 23:41:54 -0000 1.56 @@ -61,10 +61,21 @@ /** *

Common String manipulation routines.

* - *

Originally from - * Turbine and the - * GenerationJavaCore library.

+ *

The StringUtils class defines certain words related to + * String handling.

+ * + *
    + *
  • null - null + *
  • empty - a zero-length string ("") + *
  • space - the space character (' ')(32) + *
  • whitespace - the characters defined by {@link Character#isWhitespace(char)} + *
+ * + *

The StringUtils class varies in its handling of + * null. Each method should be consulted individually.

* + * @author Apache Jakarta Turbine + * @author GenerationJavaCore * @author Jon S. Stevens * @author Daniel Rall * @author Greg Coladonato @@ -89,16 +100,16 @@ private static int PAD_LIMIT = 8192; /** - *

A String containing all blank characters.

+ *

A String containing all space characters (' ').

* - *

Used for efficient blank padding. The length of the string expands as needed.

+ *

Used for efficient space padding. The length of the string expands as needed.

*/ - private static String blanks = new String(" "); + private static String spaces = new String(" "); /** *

An array of Strings used for padding.

* - *

Used for efficient blank padding. The length of each string expands as needed.

+ *

Used for efficient space padding. The length of each string expands as needed.

*/ private final static String[] padding = new String[Character.MAX_VALUE]; // String.concat about twice as fast as StringBuffer.append @@ -120,7 +131,7 @@ /** *

Removes control characters, including whitespace, from both * ends of this String, handling null by returning - * an empty String.

+ * an empty String ("").

* * 
        * StringUtils.clean("abc")         = "abc"
  @@ -167,7 +178,7 @@
       /** 
        * 
Removes control characters, including whitespace, from both  
        * ends of this string returning null if the string is 
  -     * empty after the trim or if it is null.
  +     * empty ("") after the trim or if it is null.
        * 
        * 
The string is trimmed using {@link String#trim()}.

        * 
  @@ -192,7 +203,7 @@
       /** 
        * 
Removes control characters, including whitespace, from both 
        * ends of this string returning an empty string ("") if the string
  -     * is empty after the trim or if it is null.
  +     * is empty ("") after the trim or if it is null.
        * 
        * 
The string is trimmed using {@link String#trim()}.

        * 
  @@ -213,10 +224,11 @@
       }
   
       /**
  -     * 
Deletes all 'space' characters from a String.

  +     * 
Deletes all 'space' characters from a String as defined by
  +     * {@link Character#isSpace(char)}.

        *
        * 
Spaces are defined as {' ', '\t', '\r', '\n', '\b'}
  -     * in line with the deprecated {@link Character#isSpace(char)}.

  +     * in line with the deprecated isSpace method.

        *
        * @param str  the String to delete spaces from, may be null
        * @return the String without spaces, null if null string input
  @@ -229,9 +241,7 @@
       }
   
       /**
  -     * 
Deletes all whitespaces from a String.

  -     *
  -     * 
Whitespace is defined by
  +     * 
Deletes all whitespaces from a String as defined by
        * {@link Character#isWhitespace(char)}.

        *
        * @param str  the String to delete whitespace from, may be null
  @@ -776,8 +786,8 @@
        * 
Joins the elements of the provided array into a single String
        * containing the provided list of elements.

        *
  -     * 
No delimiter is added before or after the list. A
  -     * null separator is the same as a blank String.

  +     * 
No delimiter is added before or after the list.
  +     * A null separator is the same as an empty String ("").

        *
        * @param array the array of values to join together
        * @param separator the separator character to use
  @@ -833,8 +843,8 @@
        * 
Joins the elements of the provided Iterator into
        * a single String containing the provided elements.

        *
  -     * 
No delimiter is added before or after the list. A
  -     * null separator is the same as a blank String.

  +     * 
No delimiter is added before or after the list.
  +     * A null separator is the same as an empty String ("").

        *
        * @param iterator the Iterator of values to join together
        * @param separator  the separator character to use
  @@ -960,40 +970,47 @@
       //--------------------------------------------------------------------------
       
       /**
  -     * 
Center a String in a larger String of size n.

  +     * 
Center a String in a larger String of size size
  +     * using the space character (' ').

        *
  -     * 
Uses spaces as the value to buffer the String with.
  -     * Equivalent to center(str, size, " ").

  +     * 
Equivalent to center(str, size, " ").

        *
  -     * @param str String to center
  -     * @param size int size of new String
  +     * @param str  the String to center, must not be null
  +     * @param size  the int size of new String
        * @return String containing centered String
        * @throws NullPointerException if str is null
        */
       public static String center(String str, int size) {
  -        return center(str, size, " ");
  +        int sz = str.length();
  +        int p = size - sz;
  +        if (p < 1) {
  +            return str;
  +        }
  +        str = leftPad(str, sz + p / 2, ' ');
  +        str = rightPad(str, size, ' ');
  +        return str;
       }
   
       /**
  -     * 
Center a String in a larger String of size n.

  +     * 
Center a String in a larger String of size size.

        *
  -     * 
Uses a supplied String as the value to buffer the String with.

  +     * 
Uses a supplied String as the value to pad the String with.

        *
  -     * @param str String to center
  -     * @param size int size of new String
  -     * @param delim String to buffer the new String with
  +     * @param str  the String to center, must not be null
  +     * @param size  the int size of new String
  +     * @param padStr  the String to pad the new String with, must not be null
        * @return String containing centered String
  -     * @throws NullPointerException if str or delim is null
  -     * @throws ArithmeticException if delim is the empty String
  +     * @throws NullPointerException if str or padStr is null
  +     * @throws ArithmeticException if padStr is the empty String
        */
  -    public static String center(String str, int size, String delim) {
  +    public static String center(String str, int size, String padStr) {
           int sz = str.length();
           int p = size - sz;
           if (p < 1) {
               return str;
           }
  -        str = leftPad(str, sz + p / 2, delim);
  -        str = rightPad(str, size, delim);
  +        str = leftPad(str, sz + p / 2, padStr);
  +        str = rightPad(str, size, padStr);
           return str;
       }
   
  @@ -1367,69 +1384,120 @@
       //--------------------------------------------------------------------------
       
       /**
  -     * 
Repeat a String n times to form a
  +     * 
Repeat a String repeat times to form a
        * new string.

        *
  -     * @param str String to repeat
  -     * @param repeat number of times to repeat str
  -     * @return String with repeated String
  -     * @throws NegativeArraySizeException if repeat < 0
  +     * 
  +     * StringUtils.repeat("", 0)   = ""
  +     * StringUtils.repeat("", 2)   = ""
  +     * StringUtils.repeat("a", 3)  = "aaa"
  +     * StringUtils.repeat("ab", 2) = "abab"
  +     * StringUtils.repeat(null, 2) = NullPointerException
  +     * StringUtils.repeat("a", -2) = NegativeArraySizeException
  +     * 

  +     *
  +     * @param str  the String to repeat, must not be null
  +     * @param repeat  number of times to repeat str
  +     * @return a new String consisting of the original String repeated
  +     * @throws NegativeArraySizeException if repeat < 0
        * @throws NullPointerException if str is null
        */
       public static String repeat(String str, int repeat) {
  -        if (str.length() == 1 && repeat <= PAD_LIMIT) {
  +        int inputLength = str.length();
  +        if (repeat == 0) {
  +            return "";
  +        }
  +        if (inputLength == 1 && repeat <= PAD_LIMIT) {
              return padding(repeat, str.charAt(0));
           }
   
  -        StringBuffer buffer = new StringBuffer(repeat * str.length());
  -        for (int i = 0; i < repeat; i++) {
  -            buffer.append(str);
  +        char[] input = str.toCharArray();
  +        char[] output = new char[repeat * inputLength];
  +        switch (inputLength) {
  +            case 1:
  +                char ch = input[0];
  +                for (int i = repeat - 1; i >= 0; i--) {
  +                    output[i] = ch;
  +                }
  +                break;
  +            case 2:
  +                char ch0 = input[0];
  +                char ch1 = input[1];
  +                for (int i = repeat * 2 - 2; i >= 0; i--,i--) {
  +                    output[i] = ch0;
  +                    output[i + 1] = ch1;
  +                }
  +                break;
  +            default:
  +                for (int i = repeat - 1; i >= 0; i--) {
  +                    System.arraycopy(input, 0, output, i * inputLength, inputLength);
  +                }
  +                break;            
           }
  -        return buffer.toString();
  +        return new String(output);
       }
   
       /**
  -     * 
Returns blank padding with a given length.

  +     * 
Returns a string containing the requested number of 
  +     * space characters (' ').

  +     * 
  +     * 
  +     * StringUtils.padding(0)  = ""
  +     * StringUtils.padding(3)  = "   "
  +     * StringUtils.padding(-2) = IndexOutOfBoundsException
  +     * 

        *
  -     * @param repeat number of times to repeat a blank
  -     * @return String with repeated character
  -     * @throws IndexOutOfBoundsException if repeat < 0
  +     * @param repeat  number of times to repeat space
  +     * @return a String with repeat spaces
  +     * @throws IndexOutOfBoundsException if repeat < 0
        */
       private static String padding(int repeat) {
  -        while (blanks.length() < repeat)  {
  -            blanks = blanks.concat(blanks);
  +        while (spaces.length() < repeat)  {
  +            spaces = spaces.concat(spaces);
           }
  -        return blanks.substring(0, repeat);
  +        return spaces.substring(0, repeat);
       }
   
       /**
        * 
Returns padding using the specified delimiter repeated
        * to a given length.

        *
  -     * @param repeat number of times to repeat delim
  -     * @param delim character to repeat
  +     * 
  +     * StringUtils.padding(0, 'e')  = ""
  +     * StringUtils.padding(3, 'e')  = "eee"
  +     * StringUtils.padding(-2, 'e') = IndexOutOfBoundsException
  +     * 

  +     *
  +     * @param repeat  number of times to repeat delim
  +     * @param padChar  character to repeat
        * @return String with repeated character
  -     * @throws NullPointerException if delim is null
  -     * @throws IndexOutOfBoundsException if repeat < 0
  +     * @throws IndexOutOfBoundsException if repeat < 0
        */
  -
  -    private static String padding(int repeat, char delim) {
  -        if (padding[delim] == null) {
  -            padding[delim] = String.valueOf(delim);
  +    private static String padding(int repeat, char padChar) {
  +        if (padding[padChar] == null) {
  +            padding[padChar] = String.valueOf(padChar);
           }
  -        while (padding[delim].length() < repeat) {
  -            padding[delim] = padding[delim].concat(padding[delim]);
  +        while (padding[padChar].length() < repeat) {
  +            padding[padChar] = padding[padChar].concat(padding[padChar]);
           }
  -        return padding[delim].substring(0, repeat);
  +        return padding[padChar].substring(0, repeat);
       }
   
       /**
  -     * 
Right pad a String with spaces.

  +     * 
Right pad a String with spaces (' ').

        *
  -     * 
The String is padded to the size of n.

  +     * 
The String is padded to the size of size.

        * 
  -     * @param str String to pad out
  -     * @param size number of times to repeat str
  +     * 
  +     * StringUtils.rightPad("bat", 3)  = "bat"
  +     * StringUtils.rightPad("bat", 5)  = "bat  "
  +     * StringUtils.rightPad("bat", 1)  = "bat"
  +     * StringUtils.rightPad("bat", -1) = "bat"
  +     * StringUtils.rightPad(null, 1)   = NullPointerException
  +     * 

  +     *
  +     * @param str  the String to pad out, must not be null
  +     * @param size  the size of the returned string, padded on the right
        * @return right padded String or original String if no padding is necessary
        * @throws NullPointerException if str is null
        */
  @@ -1441,64 +1509,91 @@
           if (pads > PAD_LIMIT) {
               return rightPad(str, size, ' ');
           }
  -        return str + padding(pads);
  +        return str.concat(padding(pads));
       }
   
       /**
        * 
Right pad a String with a specified character.

        *
  -     * 
The String is padded to the size of n.

  +     * 
The String is padded to the size of size.

  +     *
  +     * 
  +     * StringUtils.rightPad("bat", 3, 'z')  = "bat"
  +     * StringUtils.rightPad("bat", 5, 'z')  = "batzz"
  +     * StringUtils.rightPad("bat", 1, 'z')  = "bat"
  +     * StringUtils.rightPad("bat", -1, 'z') = "bat"
  +     * StringUtils.rightPad(null, 1, 'z')   = NullPointerException
  +     * 

        *
  -     * @param str String to pad out
  -     * @param size size to pad to
  -     * @param delim character to pad with
  +     * @param str  the String to pad out, must not be null
  +     * @param size  the size to pad to
  +     * @param padChar  the character to pad with
        * @return right padded String or original String if no padding is necessary
  -     * @throws NullPointerException if str or delim is null
  +     * @throws NullPointerException if str is null
        */
  -    public static String rightPad(String str, int size, char delim) {
  +    public static String rightPad(String str, int size, char padChar) {
           int pads = size - str.length();
           if (pads <= 0) {
               return str; // returns original string when possible
           }
           if (pads > PAD_LIMIT) {
  -            return rightPad(str, size, String.valueOf(delim));
  +            return rightPad(str, size, String.valueOf(padChar));
           }
  -        return str + padding(pads, delim);
  +        return str.concat(padding(pads, padChar));
       }
   
       /**
        * 
Right pad a String with a specified string.

        *
  -     * 
The String is padded to the size of n.

  +     * 
The String is padded to the size of size.

        *
  -     * @param str String to pad out
  -     * @param size size to pad to
  -     * @param delim String to pad with
  +     * 
  +     * StringUtils.rightPad("bat", 3, "yz")  = "bat"
  +     * StringUtils.rightPad("bat", 5, "yz")  = "batyz"
  +     * StringUtils.rightPad("bat", 8, "yz")  = "batyzyzy"
  +     * StringUtils.rightPad("bat", 1, "yz")  = "bat"
  +     * StringUtils.rightPad("bat", -1, "yz") = "bat"
  +     * StringUtils.rightPad(null, 1, "yz")   = NullPointerException
  +     * StringUtils.rightPad("bat", 1, null)  = NullPointerException
  +     * StringUtils.rightPad("bat", 1, "")    = ArithmeticException
  +     * 

  +     *
  +     * @param str  the String to pad out, must not be null
  +     * @param size  the size to pad to
  +     * @param padStr  the String to pad with, must not be null
        * @return right padded String or original String if no padding is necessary
  -     * @throws NullPointerException if str or delim is null
  -     * @throws ArithmeticException if delim is the empty String
  +     * @throws NullPointerException if str or padStr is null
  +     * @throws ArithmeticException if padStr is the empty String
        */
  -    public static String rightPad(String str, int size, String delim) {
  -        if (delim.length() == 1 && size - str.length() <= PAD_LIMIT) {
  -           return rightPad(str, size, delim.charAt(0));
  +    public static String rightPad(String str, int size, String padStr) {
  +        if (padStr.length() == 1 && size - str.length() <= PAD_LIMIT) {
  +           return rightPad(str, size, padStr.charAt(0));
           }
   
  -        size = (size - str.length()) / delim.length();
  +        size = (size - str.length()) / padStr.length();
           if (size > 0) {
  -            str += repeat(delim, size);
  +            str += repeat(padStr, size);
           }
           return str;
       }
   
       /**
  -     * 
Left pad a String with spaces.

  +     * 
Left pad a String with spaces (' ').

        *
  -     * 
The String is padded to the size of n.

  +     * 
The String is padded to the size of size.

  +     *
  +     * 
  +     * StringUtils.leftPad("bat", 3)  = "bat"
  +     * StringUtils.leftPad("bat", 5)  = "  bat"
  +     * StringUtils.leftPad("bat", 1)  = "bat"
  +     * StringUtils.leftPad("bat", -1) = "bat"
  +     * StringUtils.leftPad(null, 1)   = NullPointerException
  +     * 

        *
  -     * @param str String to pad out
  -     * @param size size to pad to
  +     * @param str  the String to pad out, must not be null
  +     * @param size  the size to pad to
        * @return left padded String or original String if no padding is necessary
  -     * @throws NullPointerException if str or delim is null
  +     * @throws NullPointerException if str is null
        */
       public static String leftPad(String str, int size) {
           int pads = size - str.length();
  @@ -1514,15 +1609,23 @@
       /**
        * 
Left pad a String with a specified character.

        *
  -     * 
Pad to a size of n.

  +     * 
Pad to a size of size.

        *
  -     * @param str String to pad out
  -     * @param size size to pad to
  -     * @param delim character to pad with
  +     * 
  +     * StringUtils.leftPad("bat", 3, 'z')  = "bat"
  +     * StringUtils.leftPad("bat", 5, 'z')  = "zzbat"
  +     * StringUtils.leftPad("bat", 1, 'z')  = "bat"
  +     * StringUtils.leftPad("bat", -1, 'z') = "bat"
  +     * StringUtils.leftPad(null, 1, 'z')   = NullPointerException
  +     * 

  +     *
  +     * @param str  the String to pad out, must not be null
  +     * @param size  the size to pad to
  +     * @param padChar  the character to pad with
        * @return left padded String or original String if no padding is necessary
        * @throws NullPointerException if str or delim is null
        */
  -    public static String leftPad(String str, int size, char delim) {
  +    public static String leftPad(String str, int size, char padChar) {
           int pads = size - str.length();
           if (pads <= 0) {
               return str; // returns original string when possible
  @@ -1530,27 +1633,38 @@
           if (pads > PAD_LIMIT) {
               return leftPad(str, size, ' ');
           }
  -        return padding(pads, delim).concat(str);
  +        return padding(pads, padChar).concat(str);
       }
   
       /**
        * 
Left pad a String with a specified string.

        *
  -     * 
Pad to a size of n.

  +     * 
Pad to a size of size.

  +     *
  +     * 
  +     * StringUtils.leftPad("bat", 3, "yz")  = "bat"
  +     * StringUtils.leftPad("bat", 5, "yz")  = "yzbat"
  +     * StringUtils.leftPad("bat", 8, "yz")  = "yzyzybat"
  +     * StringUtils.leftPad("bat", 1, "yz")  = "bat"
  +     * StringUtils.leftPad("bat", -1, "yz") = "bat"
  +     * StringUtils.leftPad(null, 1, "yz")   = NullPointerException
  +     * StringUtils.leftPad("bat", 1, null)  = NullPointerException
  +     * StringUtils.leftPad("bat", 1, "")    = ArithmeticException
  +     * 

        *
  -     * @param str String to pad out
  -     * @param size size to pad to
  -     * @param delim String to pad with
  +     * @param str  the String to pad out, must not be null
  +     * @param size  the size to pad to
  +     * @param padStr  the String to pad with
        * @return left padded String or original String if no padding is necessary
        * @throws NullPointerException if str or delim is null
        * @throws ArithmeticException if delim is the empty string
        */
  -    public static String leftPad(String str, int size, String delim) {
  -        if (delim.length() == 1 && size - str.length() <= PAD_LIMIT)
  -           return leftPad(str, size, delim.charAt(0));
  -        size = (size - str.length()) / delim.length();
  +    public static String leftPad(String str, int size, String padStr) {
  +        if (padStr.length() == 1 && size - str.length() <= PAD_LIMIT)
  +           return leftPad(str, size, padStr.charAt(0));
  +        size = (size - str.length()) / padStr.length();
           if (size > 0) {
  -            str = repeat(delim, size) + str;
  +            str = repeat(padStr, size) + str;
           }
           return str;
       }
  @@ -1937,7 +2051,7 @@
        * 
Checks if the String contains only unicode letters.

        *
        * 
null will return false.
  -     * An empty String will return true.

  +     * An empty String ("") will return true.

        * 
        * @param str the String to check
        * @return true if only contains letters, and is non-null
  @@ -1958,8 +2072,8 @@
       /**
        * 
Checks if the String contains only whitespace.

        *
  -     * 
null will return false. An
  -     * empty String will return true.

  +     * 
null will return false.
  +     * An empty String ("") will return true.

        * 
        * @param str the String to check
        * @return true if only contains whitespace, and is non-null
  @@ -1979,10 +2093,10 @@
   
       /**
        * 
Checks if the String contains only unicode letters and
  -     * space (' ').

  +     * space (' ').

        *
  -     * 
null will return false. An
  -     * empty String will return true.

  +     * 
null will return false
  +     * An empty String ("") will return true.

        * 
        * @param str the String to check
        * @return true if only contains letters and space,
  @@ -2005,8 +2119,8 @@
       /**
        * 
Checks if the String contains only unicode letters or digits.

        *
  -     * 
null will return false. An empty
  -     * String will return true.

  +     * 
null will return false.
  +     * An empty String ("") will return true.

        * 
        * @param str the String to check
        * @return true if only contains letters or digits,
  @@ -2029,8 +2143,8 @@
        * 
Checks if the String contains only unicode letters, digits
        * or space (' ').

        *
  -     * 
null will return false. An empty
  -     * String will return true.

  +     * 
null will return false.
  +     * An empty String ("") will return true.

        * 
        * @param str the String to check
        * @return true if only contains letters, digits or space,
  @@ -2054,7 +2168,7 @@
        * 
Checks if the String contains only unicode digits.

        *
        * 
null will return false.
  -     * An empty String will return true.

  +     * An empty String ("") will return true.

        * 
        * @param str the String to check
        * @return true if only contains digits, and is non-null
  @@ -2076,8 +2190,8 @@
        * 
Checks if the String contains only unicode digits or space
        * (' ').

        *
  -     * 
null will return false. An empty
  -     * String will return true.

  +     * 
null will return false.
  +     * An empty String ("") will return true.

        * 
        * @param str the String to check
        * @return true if only contains digits or space,
  @@ -2244,16 +2358,60 @@
       //--------------------------------------------------------------------------
       
       /**
  +     * 
Returns either the passed in String, 
  +     * or if the String is null, an empty String ("").

  +     * 
  +     * 
  +     * StringUtils.defaultString(null)  = ""
  +     * StringUtils.defaultString("")    = ""
  +     * StringUtils.defaultString("bat") = "bat"
  +     * 

  +     * 
  +     * @param str  the String to check, may be null
  +     * @return the passed in String, or the empty string if it
  +     *  was null
  +     */
  +    public static String defaultString(String str) {
  +        return (str == null ? "" : str);
  +    }
  +
  +    /**
        * 
Returns either the passed in Object as a String,
  -     * or, if the Object is null, an empty
  -     * String.

  +     * or, if the Object is null,
  +     * an empty String ("").

        * 
  -     * @param obj the Object to check
  -     * @return the passed in Object's toString, or blank if it was
  -     *  null
  +     * 
  +     * StringUtils.defaultString(null)         = "null"
  +     * StringUtils.defaultString("")           = ""
  +     * StringUtils.defaultString("bat")        = "bat"
  +     * StringUtils.defaultString(Boolean.TRUE) = "true"
  +     * 

  +     * 
  +     * @param obj  the Object to check, using toString(), may be null
  +     * @return the passed in Object's toString, or the empty string if it
  +     *  was null
        */
       public static String defaultString(Object obj) {
  -        return defaultString(obj, "");
  +        return (obj == null ? "" : obj.toString());
  +    }
  +
  +    /**
  +     * 
Returns either the passed in String, 
  +     * or if the String is null, an empty String ("").

  +     * 
  +     * 
  +     * StringUtils.defaultString(null, "null")  = "null"
  +     * StringUtils.defaultString("", "null")    = ""
  +     * StringUtils.defaultString("bat", "null") = "bat"
  +     * 

  +     * 
  +     * @param str  the String to check, may be null
  +     * @param defaultStr  the default String to return 
  +     *  if the input is null, may be null
  +     * @return the passed in String, or the default if it was null
  +     */
  +    public static String defaultString(String str, String defaultStr) {
  +        return (str == null ? defaultStr : str);
       }
   
       /**
  @@ -2261,14 +2419,20 @@
        * or, if the Object is null, a passed
        * in default String.

        * 
  -     * @param obj the Object to check
  -     * @param defaultString  the default String to return if str is
  -     *  null
  -     * @return the passed in string, or the default if it was
  -     *  null
  +     * 
  +     * StringUtils.defaultString(null, "null")         = "null"
  +     * StringUtils.defaultString("", "null")           = ""
  +     * StringUtils.defaultString("bat", "null")        = "bat"
  +     * StringUtils.defaultString(Boolean.TRUE, "null") = "true"
  +     * 

  +     * 
  +     * @param obj  the Object to check, using toString(), may be null
  +     * @param defaultStr  the default String to return 
  +     *  if the input is null, may be null
  +     * @return the passed in Object's toString, or the default if it was null
        */
  -    public static String defaultString(Object obj, String defaultString) {
  -        return (obj == null) ? defaultString : obj.toString();
  +    public static String defaultString(Object obj, String defaultStr) {
  +        return (obj == null ? defaultStr : obj.toString());
       }
   
       // Reversing
  @@ -2279,8 +2443,14 @@
        *
        * 
null String returns null.

        * 
  -     * @param str the String to reverse
  -     * @return the reversed String
  +     * 
  +     * StringUtils.reverse(null)  = null
  +     * StringUtils.reverse("")    = ""
  +     * StringUtils.reverse("bat") = "tab"
  +     * 

  +     * 
  +     * @param str  the String to reverse, may be null
  +     * @return the reversed String, null if null string input
        */
       public static String reverse(String str) {
           if (str == null) {
  @@ -2296,8 +2466,8 @@
        * Thus java.lang.String becomes String.lang.java (if the delimiter
        * is '.').

        * 
  -     * @param str the String to reverse
  -     * @param delimiter the delimiter to use
  +     * @param str  the String to reverse
  +     * @param delimiter  the delimiter to use
        * @return the reversed String
        */
       public static String reverseDelimitedString(String str, String delimiter) {
  @@ -2372,10 +2542,11 @@
        * (More precisely, return the remainder of the second string,
        * starting from where it's different from the first.)

        *
  -     * 

  -     * For example, difference("i am a machine", "i am a robot") -> "robot"
  +     * 
For example,
  +     * difference("i am a machine", "i am a robot") -> "robot".

        *
  -     * @return the portion of s2 where it differs from s1; returns the empty string ("") if they are equal
  +     * @return the portion of s2 where it differs from s1; returns the 
  +     * empty string if they are equal
        */
       public static String difference(String s1, String s2) {
           int at = differenceAt(s1, s2);
  @@ -2386,9 +2557,11 @@
       }
   
       /**
  -     * 
Compare two strings, and return the index at which the strings begin to differ.

  +     * 
Compare two strings, and return the index at which the
  +     * strings begin to differ.

        * 
  -     * 
For example, differenceAt("i am a machine", "i am a robot") -> 7

  +     * 
For example, 
  +     * differenceAt("i am a machine", "i am a robot") -> 7

        *
        * @return the index where s2 and s1 begin to differ; -1 if they are equal
        */
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org