From 1ea34cbbba3c622446dd736fa42b4671cca7c02d Mon Sep 17 00:00:00 2001
From: Stephen Colebourne <scolebourne@apache.org>
Date: Sun, 20 Jul 2003 15:29:44 +0000
Subject: [PATCH] Add more javadoc example code Ensure empty string behaviour
 documented in example code

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137473 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/commons/lang/StringUtils.java  | 229 ++++++++++++++----
 .../lang/StringUtilsSubstringTest.java        |  14 +-
 2 files changed, 186 insertions(+), 57 deletions(-)

diff --git a/src/java/org/apache/commons/lang/StringUtils.java b/src/java/org/apache/commons/lang/StringUtils.java
index 2ab52c096..3482a457a 100644
--- a/src/java/org/apache/commons/lang/StringUtils.java
+++ b/src/java/org/apache/commons/lang/StringUtils.java
@@ -142,7 +142,7 @@
  * @author Arun Mammen Thomas
  * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
  * @since 1.0
- * @version $Id: StringUtils.java,v 1.72 2003/07/20 14:47:29 scolebourne Exp $
+ * @version $Id: StringUtils.java,v 1.73 2003/07/20 15:29:44 scolebourne Exp $
  */
 public class StringUtils {
     // Performance testing notes (JDK 1.4, Jul03, scolebourne)
@@ -297,10 +297,10 @@ public static boolean isNotBlank(String str) {
      * 
      * <pre>
      * StringUtils.clean(null)          = ""
+     * StringUtils.clean("")            = ""
      * StringUtils.clean("abc")         = "abc"
      * StringUtils.clean("    abc    ") = "abc"
      * StringUtils.clean("     ")       = ""
-     * StringUtils.clean("")            = ""
      * </pre>
      *
      * @see java.lang.String#trim()
@@ -327,10 +327,10 @@ public static String clean(String str) {
      * 
      * <pre>
      * StringUtils.trim(null)          = null
+     * StringUtils.trim("")            = ""
+     * StringUtils.trim("     ")       = ""
      * StringUtils.trim("abc")         = "abc"
      * StringUtils.trim("    abc    ") = "abc"
-     * StringUtils.trim("     ")       = ""
-     * StringUtils.trim("")            = ""
      * </pre>
      *
      * @param str  the String to be trimmed, may be null
@@ -351,10 +351,10 @@ public static String trim(String str) {
      * 
      * <pre>
      * StringUtils.trimToNull(null)          = null
+     * StringUtils.trimToNull("")            = null
+     * StringUtils.trimToNull("     ")       = null
      * StringUtils.trimToNull("abc")         = "abc"
      * StringUtils.trimToNull("    abc    ") = "abc"
-     * StringUtils.trimToNull("     ")       = null
-     * StringUtils.trimToNull("")            = null
      * </pre>
      *  
      * @param str  the String to be trimmed, may be null
@@ -377,10 +377,10 @@ public static String trimToNull(String str) {
      * 
      * <pre>
      * StringUtils.trimToEmpty(null)          = ""
+     * StringUtils.trimToEmpty("")            = ""
+     * StringUtils.trimToEmpty("     ")       = ""
      * StringUtils.trimToEmpty("abc")         = "abc"
      * StringUtils.trimToEmpty("    abc    ") = "abc"
-     * StringUtils.trimToEmpty("     ")       = ""
-     * StringUtils.trimToEmpty("")            = ""
      * </pre>
      *  
      * @param str  the String to be trimmed, may be null
@@ -487,6 +487,7 @@ public static String stripToEmpty(String str) {
      * 
      * <pre>
      * StringUtils.strip(null, null)       = null
+     * StringUtils.strip("", null)         = ""
      * StringUtils.strip("abc", null)      = "abc"
      * StringUtils.strip("  abc", null)    = "abc"
      * StringUtils.strip("abc  ", null)    = "abc"
@@ -515,12 +516,14 @@ public static String strip(String str, String stripChars) {
      * stripped as defined by {@link Character#isWhitespace(char)}.</p>
      * 
      * <pre>
-     * StringUtils.strip(null, null)       = null
-     * StringUtils.strip("abc", null)      = "abc"
-     * StringUtils.strip("  abc", null)    = "abc"
-     * StringUtils.strip("abc  ", null)    = "abc  "
-     * StringUtils.strip(" abc ", null)    = "abc "
-     * StringUtils.strip("yxabc  ", "xyz") = "abc  "
+     * StringUtils.stripStart(null, null)       = null
+     * StringUtils.stripStart("", null)         = ""
+     * StringUtils.stripStart("abc", "")        = "abc"
+     * StringUtils.stripStart("abc", null)      = "abc"
+     * StringUtils.stripStart("  abc", null)    = "abc"
+     * StringUtils.stripStart("abc  ", null)    = "abc  "
+     * StringUtils.stripStart(" abc ", null)    = "abc "
+     * StringUtils.stripStart("yxabc  ", "xyz") = "abc  "
      * </pre>
      * 
      * @param str  the String to remove characters from, may be null
@@ -537,6 +540,8 @@ public static String stripStart(String str, String stripChars) {
             while ((start != strLen) && Character.isWhitespace(str.charAt(start))) {
                 start++;
             }
+        } else if (stripChars.length() == 0) {
+            return str;
         } else {
             while ((start != strLen) && (stripChars.indexOf(str.charAt(start)) != -1)) {
                 start++;
@@ -554,12 +559,14 @@ public static String stripStart(String str, String stripChars) {
      * stripped as defined by {@link Character#isWhitespace(char)}.</p>
      * 
      * <pre>
-     * StringUtils.strip(null, null)       = null
-     * StringUtils.strip("abc", null)      = "abc"
-     * StringUtils.strip("  abc", null)    = "  abc"
-     * StringUtils.strip("abc  ", null)    = "abc"
-     * StringUtils.strip(" abc ", null)    = " abc"
-     * StringUtils.strip("  abcyx", "xyz") = "  abc"
+     * StringUtils.stripEnd(null, null)       = null
+     * StringUtils.stripEnd("", null)         = ""
+     * StringUtils.stripEnd("abc", "")        = "abc"
+     * StringUtils.stripEnd("abc", null)      = "abc"
+     * StringUtils.stripEnd("  abc", null)    = "  abc"
+     * StringUtils.stripEnd("abc  ", null)    = "abc"
+     * StringUtils.stripEnd(" abc ", null)    = " abc"
+     * StringUtils.stripEnd("  abcyx", "xyz") = "  abc"
      * </pre>
      * 
      * @param str  the String to remove characters from, may be null
@@ -576,6 +583,8 @@ public static String stripEnd(String str, String stripChars) {
             while ((end != 0) && Character.isWhitespace(str.charAt(end - 1))) {
                 end--;
             }
+        } else if (stripChars.length() == 0) {
+            return str;
         } else {
             while ((end != 0) && (stripChars.indexOf(str.charAt(end - 1)) != -1)) {
                 end--;
@@ -1016,6 +1025,8 @@ public static boolean contains(String str, String searchStr) {
      * <pre>
      * StringUtils.indexOfAny(null, null)                = -1
      * StringUtils.indexOfAny(null, ["ab","cd"])         = -1
+     * StringUtils.indexOfAny("", null)                  = -1
+     * StringUtils.indexOfAny("", ["ab","cd"])           = -1
      * StringUtils.indexOfAny("zzabyycdxx", null)        = -1
      * StringUtils.indexOfAny("zzabyycdxx", [])          = -1
      * StringUtils.indexOfAny("zzabyycdxx", ["ab","cd"]) = 2
@@ -1065,6 +1076,8 @@ public static int indexOfAny(String str, String[] searchStrs) {
      * <pre>
      * StringUtils.lastIndexOfAny(null, null)                = -1
      * StringUtils.lastIndexOfAny(null, ["ab","cd"])         = -1
+     * StringUtils.lastIndexOfAny("", null)                  = -1
+     * StringUtils.lastIndexOfAny("", ["ab","cd"])           = -1
      * StringUtils.lastIndexOfAny("zzabyycdxx", null)        = -1
      * StringUtils.lastIndexOfAny("zzabyycdxx", [])          = -1
      * StringUtils.lastIndexOfAny("zzabyycdxx", ["ab","cd"]) = 6
@@ -1270,6 +1283,7 @@ public static boolean containsNone(String str, String invalidChars) {
      * 
      * <pre>
      * StringUtils.substring(null, 0)   = null
+     * StringUtils.substring("", 0)     = ""
      * StringUtils.substring("abc", 0)  = "abc"
      * StringUtils.substring("abc", 2)  = "c"
      * StringUtils.substring("abc", 4)  = ""
@@ -1310,6 +1324,7 @@ public static String substring(String str, int start) {
      * 
      * <pre>
      * StringUtils.substring(null, 0, 2)    = null
+     * StringUtils.substring("", 0, 2)      = ""
      * StringUtils.substring("abc", 0, 2)   = "ab"
      * StringUtils.substring("abc", 2, 0)   = ""
      * StringUtils.substring("abc", 2, 4)   = "c"
@@ -1341,7 +1356,6 @@ public static String substring(String str, int start, int end) {
 
         // check length next
         if (end > str.length()) {
-            // check this works.
             end = str.length();
         }
 
@@ -1372,6 +1386,7 @@ public static String substring(String str, int start, int end) {
      *
      * <pre>
      * StringUtils.left(null, 0)    = null
+     * StringUtils.left("", 2)      = ""
      * StringUtils.left("abc", 0)   = ""
      * StringUtils.left("abc", 2)   = "ab"
      * StringUtils.left("abc", 4)   = "abc"
@@ -1403,6 +1418,7 @@ public static String left(String str, int len) {
      *
      * <pre>
      * StringUtils.right(null, 0)    = null
+     * StringUtils.right("", 2)      = ""
      * StringUtils.right("abc", 0)   = ""
      * StringUtils.right("abc", 2)   = "bc"
      * StringUtils.right("abc", 4)   = "abc"
@@ -1434,6 +1450,7 @@ public static String right(String str, int len) {
      *
      * <pre>
      * StringUtils.mid(null, 0, 0)    = null
+     * StringUtils.mid("", 0, 4)      = ""
      * StringUtils.mid("abc", 0, 2)   = "ab"
      * StringUtils.mid("abc", 0, 4)   = "abc"
      * StringUtils.mid("abc", 2, 4)   = "c"
@@ -1829,6 +1846,7 @@ public static String join(Iterator iterator, String separator) {
      *
      * <pre>
      * StringUtils.deleteSpaces(null)           = null
+     * StringUtils.deleteSpaces("")             = ""
      * StringUtils.deleteSpaces("abc")          = "abc"
      * StringUtils.deleteSpaces(" \t  abc \n ") = "abc"
      * StringUtils.deleteSpaces("ab  c")        = "abc"
@@ -1855,9 +1873,10 @@ public static String deleteSpaces(String str) {
      * {@link Character#isWhitespace(char)}.</p>
      *
      * <pre>
-     * StringUtils.deleteWhitespace(null)        = null
-     * StringUtils.deleteWhitespace("abc")       = "abc"
-     * StringUtils.deleteWhitespace("   abc  ")  = "abc"
+     * StringUtils.deleteWhitespace(null)         = null
+     * StringUtils.deleteWhitespace("")           = ""
+     * StringUtils.deleteWhitespace("abc")        = "abc"
+     * StringUtils.deleteWhitespace("   ab  c  ") = "abc"
      * </pre>
      *  
      * @param str  the String to delete whitespace from, may be null
@@ -1887,6 +1906,7 @@ public static String deleteWhitespace(String str) {
      * 
      * <pre>
      * StringUtils.replaceOnce(null, null, null)  = null
+     * StringUtils.replaceOnce("", null, null)    = ""
      * StringUtils.replaceOnce("aba", null, null) = "aba"
      * StringUtils.replaceOnce("aba", null, null) = "aba"
      * StringUtils.replaceOnce("aba", "a", null)  = "aba"
@@ -1912,6 +1932,7 @@ public static String replaceOnce(String text, String repl, String with) {
      * 
      * <pre>
      * StringUtils.replace(null, null, null)  = null
+     * StringUtils.replace("", null, null)    = ""
      * StringUtils.replace("aba", null, null) = "aba"
      * StringUtils.replace("aba", null, null) = "aba"
      * StringUtils.replace("aba", "a", null)  = "aba"
@@ -1938,6 +1959,7 @@ public static String replace(String text, String repl, String with) {
      *
      * <pre>
      * StringUtils.replace(null, null, null, 1)   = null
+     * StringUtils.replace("", null, null, 1)     = ""
      * StringUtils.replace("abaa", null, null, 1) = "abaa"
      * StringUtils.replace("abaa", null, null, 1) = "abaa"
      * StringUtils.replace("abaa", "a", null, 1)  = "abaa"
@@ -1979,6 +2001,7 @@ public static String replace(String text, String repl, String with, int max) {
      *
      * <pre>
      * StringUtils.overlayString(null, null, 2, 4)        = null
+     * StringUtils.overlayString("", "abc", 0, 0)         = "abc"
      * StringUtils.overlayString("abcdef", null, 2, 4)    = "abef"
      * StringUtils.overlayString("abcdef", "", 2, 4)      = "abef"
      * StringUtils.overlayString("abcdef", "zzzz", 2, 4)  = "abzzzzef"
@@ -2465,6 +2488,7 @@ private static String padding(int repeat, char padChar) {
      * 
      * <pre>
      * StringUtils.rightPad(null, 1)   = null
+     * StringUtils.rightPad("", 3)     = "   "
      * StringUtils.rightPad("bat", 3)  = "bat"
      * StringUtils.rightPad("bat", 5)  = "bat  "
      * StringUtils.rightPad("bat", 1)  = "bat"
@@ -2487,6 +2511,7 @@ public static String rightPad(String str, int size) {
      *
      * <pre>
      * StringUtils.rightPad(null, 1, 'z')   = null
+     * StringUtils.rightPad("", 3, 'z')     = "zzz"
      * StringUtils.rightPad("bat", 3, 'z')  = "bat"
      * StringUtils.rightPad("bat", 5, 'z')  = "batzz"
      * StringUtils.rightPad("bat", 1, 'z')  = "bat"
@@ -2520,6 +2545,7 @@ public static String rightPad(String str, int size, char padChar) {
      *
      * <pre>
      * StringUtils.rightPad(null, 1, "yz")   = null
+     * StringUtils.rightPad("", 3, "z")      = "zzz"
      * StringUtils.rightPad("bat", 3, "yz")  = "bat"
      * StringUtils.rightPad("bat", 5, "yz")  = "batyz"
      * StringUtils.rightPad("bat", 8, "yz")  = "batyzyzy"
@@ -2575,6 +2601,7 @@ public static String rightPad(String str, int size, String padStr) {
      *
      * <pre>
      * StringUtils.leftPad(null, 1)   = null
+     * StringUtils.leftPad("", 3)     = "   "
      * StringUtils.leftPad("bat", 3)  = "bat"
      * StringUtils.leftPad("bat", 5)  = "  bat"
      * StringUtils.leftPad("bat", 1)  = "bat"
@@ -2597,6 +2624,7 @@ public static String leftPad(String str, int size) {
      *
      * <pre>
      * StringUtils.leftPad(null, 1, 'z')   = null
+     * StringUtils.leftPad("", 3, 'z')     = "zzz"
      * StringUtils.leftPad("bat", 3, 'z')  = "bat"
      * StringUtils.leftPad("bat", 5, 'z')  = "zzbat"
      * StringUtils.leftPad("bat", 1, 'z')  = "bat"
@@ -2630,6 +2658,7 @@ public static String leftPad(String str, int size, char padChar) {
      *
      * <pre>
      * StringUtils.leftPad(null, 1, "yz")   = null
+     * StringUtils.leftPad("", 3, "z")      = "zzz"
      * StringUtils.leftPad("bat", 3, "yz")  = "bat"
      * StringUtils.leftPad("bat", 5, "yz")  = "yzbat"
      * StringUtils.leftPad("bat", 8, "yz")  = "yzyzybat"
@@ -2694,8 +2723,8 @@ public static String leftPad(String str, int size, String padStr) {
      * <pre>
      * StringUtils.center(null, -1)  = null
      * StringUtils.center(null, 4)   = null
-     * StringUtils.center("ab", -1)  = "ab"
      * StringUtils.center("", 4)     = "    "
+     * StringUtils.center("ab", -1)  = "ab"
      * StringUtils.center("ab", 4)   = " ab "
      * StringUtils.center("abcd", 2) = "abcd"
      * StringUtils.center("a", 4)    = " a  "
@@ -2719,9 +2748,9 @@ public static String center(String str, int size) {
      *
      * <pre>
      * StringUtils.center(null, -1, ' ')  = null
-     * StringUtils.center("ab", -1, ' ')  = "ab"
      * StringUtils.center(null, 4, ' ')   = null
      * StringUtils.center("", 4, ' ')     = "    "
+     * StringUtils.center("ab", -1, ' ')  = "ab"
      * StringUtils.center("ab", 4, ' ')   = " ab"
      * StringUtils.center("abcd", 2, ' ') = "abcd"
      * StringUtils.center("a", 4, ' ')    = " a  "
@@ -2757,9 +2786,9 @@ public static String center(String str, int size, char padChar) {
      *
      * <pre>
      * StringUtils.center(null, -1, " ")  = null
-     * StringUtils.center("ab", -1, " ")  = "ab"
      * StringUtils.center(null, 4, " ")   = null
      * StringUtils.center("", 4, " ")     = "    "
+     * StringUtils.center("ab", -1, " ")  = "ab"
      * StringUtils.center("ab", 4, " ")   = " ab"
      * StringUtils.center("abcd", 2, " ") = "abcd"
      * StringUtils.center("a", 4, " ")    = " a  "
@@ -2802,6 +2831,7 @@ public static String center(String str, int size, String padStr) {
      * 
      * <pre>
      * StringUtils.upperCase(null)  = null
+     * StringUtils.upperCase("")    = ""
      * StringUtils.upperCase("aBc") = "ABC"
      * </pre>
      * 
@@ -2822,6 +2852,7 @@ public static String upperCase(String str) {
      * 
      * <pre>
      * StringUtils.lowerCase(null)  = null
+     * StringUtils.lowerCase("")    = ""
      * StringUtils.lowerCase("aBc") = "abc"
      * </pre>
      * 
@@ -2843,6 +2874,7 @@ public static String lowerCase(String str) {
      * 
      * <pre>
      * StringUtils.capitalise(null)  = null
+     * StringUtils.capitalise("")    = ""
      * StringUtils.capitalise("cat") = "Cat"
      * StringUtils.capitalise("cAt") = "CAt"
      * </pre>
@@ -2869,6 +2901,7 @@ public static String capitalise(String str) {
      * 
      * <pre>
      * StringUtils.uncapitalise(null)  = null
+     * StringUtils.uncapitalise("")    = ""
      * StringUtils.uncapitalise("Cat") = "cat"
      * StringUtils.uncapitalise("CAT") = "cAT"
      * </pre>
@@ -2902,6 +2935,7 @@ public static String uncapitalise(String str) {
      * 
      * <pre>
      * StringUtils.swapCase(null)                 = null
+     * StringUtils.swapCase("")                   = ""
      * StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"
      * </pre>
      * 
@@ -3028,6 +3062,8 @@ public static String uncapitaliseAllWords(String str) {
      * 
      * <pre>
      * StringUtils.getNestedString(null, "tag")        = null
+     * StringUtils.getNestedString("", "")             = ""
+     * StringUtils.getNestedString("", "tag")          = null
      * StringUtils.getNestedString("tagabctag", null)  = null
      * StringUtils.getNestedString("tagabctag", "")    = ""
      * StringUtils.getNestedString("tagabctag", "tag") = "abc"
@@ -3051,6 +3087,9 @@ public static String getNestedString(String str, String tag) {
      *
      * <pre>
      * StringUtils.getNestedString(null, "y", "z")      = null
+     * StringUtils.getNestedString("", "", "")          = ""
+     * StringUtils.getNestedString("", "", "tag")       = null
+     * StringUtils.getNestedString("", "tag", "tag")    = null
      * StringUtils.getNestedString("yabcz", null, null) = null
      * StringUtils.getNestedString("yabcz", "", "")     = ""
      * StringUtils.getNestedString("yabcz", "y", "z")   = "abc"
@@ -3082,8 +3121,22 @@ public static String getNestedString(String str, String open, String close) {
     /**
      * <p>How many times is the substring in the larger String.</p>
      *
-     * <p><code>null</code> returns <code>0</code>.</p>
+     * <p>A <code>null</code> String input returns <code>0</code>.</p>
      * 
+     * <pre>
+     * StringUtils.countMatches(null, null)    = 0
+     * StringUtils.countMatches(null, "")      = 0
+     * StringUtils.countMatches(null, "a")     = 0
+     * StringUtils.countMatches("", null)      = 0
+     * StringUtils.countMatches("", "")        = 0
+     * StringUtils.countMatches("", "a")       = 0
+     * StringUtils.countMatches("abba", null)  = 0
+     * StringUtils.countMatches("abba", "")    = 0
+     * StringUtils.countMatches("abba", "a")   = 2
+     * StringUtils.countMatches("abba", "ab")  = 1
+     * StringUtils.countMatches("abba", "xxx") = 0
+     * </pre>
+     *
      * @param str  the String to check, may be null
      * @param sub  the substring to count, may be null
      * @return the number of occurances, 0 if either String is <code>null</code>
@@ -3110,6 +3163,15 @@ public static int countMatches(String str, String sub) {
      * <p><code>null</code> will return <code>false</code>.
      * An empty String ("") will return <code>true</code>.</p>
      * 
+     * <pre>
+     * StringUtils.isAlpha(null)   = false
+     * StringUtils.isAlpha("")     = true
+     * StringUtils.isAlpha("  ")   = false
+     * StringUtils.isAlpha("abc")  = true
+     * StringUtils.isAlpha("ab2c") = false
+     * StringUtils.isAlpha("ab-c") = false
+     * </pre>
+     *
      * @param str  the String to check, may be null
      * @return <code>true</code> if only contains letters, and is non-null
      */
@@ -3126,28 +3188,6 @@ public static boolean isAlpha(String str) {
         return true;
     }
 
-    /**
-     * <p>Checks if the String contains only whitespace.</p>
-     *
-     * <p><code>null</code> will return <code>false</code>.
-     * An empty String ("") will return <code>true</code>.</p>
-     * 
-     * @param str  the String to check, may be null
-     * @return <code>true</code> if only contains whitespace, and is non-null
-     */
-    public static boolean isWhitespace(String str) {
-        if (str == null) {
-            return false;
-        }
-        int sz = str.length();
-        for (int i = 0; i < sz; i++) {
-            if ((Character.isWhitespace(str.charAt(i)) == false) ) {
-                return false;
-            }
-        }
-        return true;
-    }
-
     /**
      * <p>Checks if the String contains only unicode letters and
      * space (' ').</p>
@@ -3155,6 +3195,16 @@ public static boolean isWhitespace(String str) {
      * <p><code>null</code> will return <code>false</code>
      * An empty String ("") will return <code>true</code>.</p>
      * 
+     * <pre>
+     * StringUtils.isAlphaSpace(null)   = false
+     * StringUtils.isAlphaSpace("")     = true
+     * StringUtils.isAlphaSpace("  ")   = true
+     * StringUtils.isAlphaSpace("abc")  = true
+     * StringUtils.isAlphaSpace("ab c") = true
+     * StringUtils.isAlphaSpace("ab2c") = false
+     * StringUtils.isAlphaSpace("ab-c") = false
+     * </pre>
+     *
      * @param str  the String to check, may be null
      * @return <code>true</code> if only contains letters and space,
      *  and is non-null
@@ -3179,6 +3229,16 @@ public static boolean isAlphaSpace(String str) {
      * <p><code>null</code> will return <code>false</code>.
      * An empty String ("") will return <code>true</code>.</p>
      * 
+     * <pre>
+     * StringUtils.isAlphanumeric(null)   = false
+     * StringUtils.isAlphanumeric("")     = true
+     * StringUtils.isAlphanumeric("  ")   = false
+     * StringUtils.isAlphanumeric("abc")  = true
+     * StringUtils.isAlphanumeric("ab c") = false
+     * StringUtils.isAlphanumeric("ab2c") = true
+     * StringUtils.isAlphanumeric("ab-c") = false
+     * </pre>
+     *
      * @param str  the String to check, may be null
      * @return <code>true</code> if only contains letters or digits,
      *  and is non-null
@@ -3203,6 +3263,16 @@ public static boolean isAlphanumeric(String str) {
      * <p><code>null</code> will return <code>false</code>.
      * An empty String ("") will return <code>true</code>.</p>
      * 
+     * <pre>
+     * StringUtils.isAlphanumeric(null)   = false
+     * StringUtils.isAlphanumeric("")     = true
+     * StringUtils.isAlphanumeric("  ")   = true
+     * StringUtils.isAlphanumeric("abc")  = true
+     * StringUtils.isAlphanumeric("ab c") = true
+     * StringUtils.isAlphanumeric("ab2c") = true
+     * StringUtils.isAlphanumeric("ab-c") = false
+     * </pre>
+     *
      * @param str  the String to check, may be null
      * @return <code>true</code> if only contains letters, digits or space,
      *  and is non-null
@@ -3222,11 +3292,23 @@ public static boolean isAlphanumericSpace(String str) {
     }
 
     /**
-     * <p>Checks if the String contains only unicode digits.</p>
+     * <p>Checks if the String contains only unicode digits.
+     * A decimal point is not a unicode digit and returns false.</p>
      *
      * <p><code>null</code> will return <code>false</code>.
      * An empty String ("") will return <code>true</code>.</p>
      * 
+     * <pre>
+     * StringUtils.isNumeric(null)   = false
+     * StringUtils.isNumeric("")     = true
+     * StringUtils.isNumeric("  ")   = false
+     * StringUtils.isNumeric("123")  = true
+     * StringUtils.isNumeric("12 3") = false
+     * StringUtils.isNumeric("ab2c") = false
+     * StringUtils.isNumeric("12-3") = false
+     * StringUtils.isNumeric("12.3") = false
+     * </pre>
+     *
      * @param str  the String to check, may be null
      * @return <code>true</code> if only contains digits, and is non-null
      */
@@ -3245,11 +3327,23 @@ public static boolean isNumeric(String str) {
 
     /**
      * <p>Checks if the String contains only unicode digits or space
-     * (<code>' '</code>).</p>
+     * (<code>' '</code>).
+     * A decimal point is not a unicode digit and returns false.</p>
      *
      * <p><code>null</code> will return <code>false</code>.
      * An empty String ("") will return <code>true</code>.</p>
      * 
+     * <pre>
+     * StringUtils.isNumeric(null)   = false
+     * StringUtils.isNumeric("")     = true
+     * StringUtils.isNumeric("  ")   = true
+     * StringUtils.isNumeric("123")  = true
+     * StringUtils.isNumeric("12 3") = true
+     * StringUtils.isNumeric("ab2c") = false
+     * StringUtils.isNumeric("12-3") = false
+     * StringUtils.isNumeric("12.3") = false
+     * </pre>
+     *
      * @param str  the String to check, may be null
      * @return <code>true</code> if only contains digits or space,
      *  and is non-null
@@ -3268,6 +3362,37 @@ public static boolean isNumericSpace(String str) {
         return true;
     }
 
+    /**
+     * <p>Checks if the String contains only whitespace.</p>
+     *
+     * <p><code>null</code> will return <code>false</code>.
+     * An empty String ("") will return <code>true</code>.</p>
+     * 
+     * <pre>
+     * StringUtils.isWhitespace(null)   = false
+     * StringUtils.isWhitespace("")     = true
+     * StringUtils.isWhitespace("  ")   = true
+     * StringUtils.isWhitespace("abc")  = false
+     * StringUtils.isWhitespace("ab2c") = false
+     * StringUtils.isWhitespace("ab-c") = false
+     * </pre>
+     *
+     * @param str  the String to check, may be null
+     * @return <code>true</code> if only contains whitespace, and is non-null
+     */
+    public static boolean isWhitespace(String str) {
+        if (str == null) {
+            return false;
+        }
+        int sz = str.length();
+        for (int i = 0; i < sz; i++) {
+            if ((Character.isWhitespace(str.charAt(i)) == false) ) {
+                return false;
+            }
+        }
+        return true;
+    }
+
     // Defaults
     //-----------------------------------------------------------------------
     
diff --git a/src/test/org/apache/commons/lang/StringUtilsSubstringTest.java b/src/test/org/apache/commons/lang/StringUtilsSubstringTest.java
index 6e9638d15..95001d240 100644
--- a/src/test/org/apache/commons/lang/StringUtilsSubstringTest.java
+++ b/src/test/org/apache/commons/lang/StringUtilsSubstringTest.java
@@ -63,7 +63,7 @@
  *
  * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
  * @author <a href="mailto:ridesmet@users.sourceforge.net">Ringo De Smet</a>
- * @version $Id: StringUtilsSubstringTest.java,v 1.5 2003/07/18 02:06:23 scolebourne Exp $
+ * @version $Id: StringUtilsSubstringTest.java,v 1.6 2003/07/20 15:29:44 scolebourne Exp $
  */
 public class StringUtilsSubstringTest extends TestCase {
     private static final String FOO = "foo";
@@ -207,17 +207,21 @@ public void testCountMatches() {
              StringUtils.countMatches("oooooooooooo", "ooo"));
     }
 
-    public void testGetNestedString() {
+    public void testGetNestedString_StringString() {
         assertEquals(null, StringUtils.getNestedString(null, "tag"));
+        assertEquals("", StringUtils.getNestedString("", ""));
+        assertEquals(null, StringUtils.getNestedString("", "abc"));
+        assertEquals("", StringUtils.getNestedString("    ", " "));
         assertEquals(null, StringUtils.getNestedString("abc", null));
         assertEquals("", StringUtils.getNestedString("abc", ""));
         assertEquals(null, StringUtils.getNestedString("abc", "a"));
         assertEquals("bc", StringUtils.getNestedString("abca", "a"));
         assertEquals("bc", StringUtils.getNestedString("abcabca", "a"));
-        assertEquals("", StringUtils.getNestedString("", ""));
-        assertEquals("", StringUtils.getNestedString("    ", " "));
         assertEquals("bar", StringUtils.getNestedString("\nbar\n", "\n"));
-        
+    }
+            
+    public void testGetNestedString_StringStringString() {
+        assertEquals(null, StringUtils.getNestedString(null, "", ""));
         assertEquals("", StringUtils.getNestedString("", "", ""));
         assertEquals("", StringUtils.getNestedString("    ", " ", "  "));
         assertEquals("bar", StringUtils.getNestedString("<foo>bar</foo>", "<foo>", "</foo>") );