diff --git a/src/java/org/apache/commons/lang/StringUtils.java b/src/java/org/apache/commons/lang/StringUtils.java index 80dc73a2a..40eef46ee 100644 --- a/src/java/org/apache/commons/lang/StringUtils.java +++ b/src/java/org/apache/commons/lang/StringUtils.java @@ -73,7 +73,7 @@ * @author Stephen Colebourne * @author null * references are considered equal. Comparison is case sensitive. * + * @see java.lang.String#equals(String) * @param str1 the first string * @param str2 the second string * @return true if the Strings are equal, case sensitive, or both null @@ -168,7 +171,7 @@ public static boolean equals(String str1, String str2) { * Compares two Strings, returning true if they are equal ignoring case. * Nulls are handled without exceptions. Two null * references are considered equal. Comparison is case insensitive. - * + * @see java.lang.String#equalsIgnoreCase(String) * @param str1 the first string * @param str2 the second string * @return true if the Strings are equal, case insensitive, or both null @@ -184,6 +187,7 @@ public static boolean equalsIgnoreCase(String str1, String str2) { * @param str the string to check * @param searchStrs the strings to search for * @return the earliest index of any of the strings + * @throws NullPointerException if any of searchStrs[i] is null */ public static int indexOfAny(String str, String[] searchStrs) { if ((str == null) || (searchStrs == null)) { @@ -216,6 +220,7 @@ public static int indexOfAny(String str, String[] searchStrs) { * @param str the string to check * @param searchStrs the strings to search for * @return the last index of any of the strings + * @throws NullPointerException if any of searchStrs[i] is null */ public static int lastIndexOfAny(String str, String[] searchStrs) { if ((str == null) || (searchStrs == null)) { @@ -569,6 +574,7 @@ public static String replace(String text, String repl, String with) { * @param max maximum number of values to replace, or * -1 if no maximum * @return the text with any replacements processed + * @throws NullPointerException if repl is null */ public static String replace(String text, String repl, String with, int max) { @@ -598,6 +604,7 @@ public static String replace(String text, String repl, String with, * @param start int to start overlaying at * @param end int to stop overlaying before * @return String with overlayed text + * @throws NullPointerException if text or overlay is null */ public static String overlayString(String text, String overlay, int start, int end) { return new StringBuffer(start + overlay.length() + text.length() - end + 1) @@ -612,11 +619,13 @@ public static String overlayString(String text, String overlay, int start, int e /** * Center a string in a larger string of size n. - * Uses spaces as the value to buffer the string with.. + * Uses spaces as the value to buffer the string with. + * Equivalent to center(str, size, "") * * @param str String to center * @param size 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, " "); @@ -630,6 +639,8 @@ public static String center(String str, int size) { * @param size int size of new String * @param delim String to buffer the new String with * @return String containing centered String + * @throws NullPointerException if str or delim is null + * @throws ArithmeticException if delim is the empty string */ public static String center(String str, int size, String delim) { int sz = str.length(); @@ -650,6 +661,7 @@ public static String center(String str, int size, String delim) { * * @param str String to chomp the newline from * @return String without chomped newline + * @throws NullPointerException if str is null */ public static String chomp(String str) { return chomp(str, "\n"); @@ -662,6 +674,7 @@ public static String chomp(String str) { * @param str String to chomp from * @param sep String to chomp * @return String without chomped ending + * @throws NullPointerException if str or sep is null */ public static String chomp(String str, String sep) { int idx = str.lastIndexOf(sep); @@ -678,6 +691,7 @@ public static String chomp(String str, String sep) { * * @param str String to chomp from * @return String without chomped ending + * @throws NullPointerException if str is null */ public static String chompLast(String str) { return chompLast(str, "\n"); @@ -689,6 +703,7 @@ public static String chompLast(String str) { * @param str String to chomp from * @param sep String to chomp * @return String without chomped ending + * @throws NullPointerException if str or sep is null */ public static String chompLast(String str, String sep) { if (str.length() == 0) { @@ -709,6 +724,7 @@ public static String chompLast(String str, String sep) { * @param str String to chomp from * @param sep String to chomp * @return String chomped + * @throws NullPointerException if str or sep is null */ public static String getChomp(String str, String sep) { int idx = str.lastIndexOf(sep); @@ -728,6 +744,7 @@ public static String getChomp(String str, String sep) { * @param str String to chomp from * @param sep String to chomp * @return String without chomped beginning + * @throws NullPointerException if str or sep is null */ public static String prechomp(String str, String sep) { int idx = str.indexOf(sep); @@ -745,6 +762,7 @@ public static String prechomp(String str, String sep) { * @param str String to chomp from * @param sep String to chomp * @return String prechomped + * @throws NullPointerException if str or sep is null */ public static String getPrechomp(String str, String sep) { int idx = str.indexOf(sep); @@ -764,6 +782,7 @@ public static String getPrechomp(String str, String sep) { * * @param str String to chop last character from * @return String without last character + * @throws NullPointerException if str is null */ public static String chop(String str) { if ("".equals(str)) { @@ -789,6 +808,7 @@ public static String chop(String str) { * * @param str String to chop a newline from * @return String without newline + * @throws NullPointerException if str is null */ public static String chopNewline(String str) { int lastIdx = str.length() - 1; @@ -815,6 +835,7 @@ public static String chopNewline(String str) { * @param str String to escape values in * * @return String with escaped values + * @throws NullPointerException if str is null */ public static String escape(String str) { // improved with code from cybertiger@cyberiantiger.org @@ -893,6 +914,8 @@ public static String escape(String str) { * @param str String to repeat * @param repeat int number of times to repeat * @return String with repeated string + * @throws NegativeArraySizeException if repeat < 0 + * @throws NullPointerException if str is null */ public static String repeat(String str, int repeat) { StringBuffer buffer = new StringBuffer(repeat * str.length()); @@ -908,6 +931,7 @@ public static String repeat(String str, int repeat) { * @param str String to repeat * @param size int number of times to repeat * @return right padded String + * @throws NullPointerException if str is null */ public static String rightPad(String str, int size) { return rightPad(str, size, " "); @@ -920,6 +944,8 @@ public static String rightPad(String str, int size) { * @param size int size to pad to * @param delim String to pad with * @return right padded String + * @throws NullPointerException if str or delim is null + * @throws ArithmeticException if delim is the empty string */ public static String rightPad(String str, int size, String delim) { size = (size - str.length()) / delim.length(); @@ -935,6 +961,7 @@ public static String rightPad(String str, int size, String delim) { * @param str String to pad out * @param size int size to pad to * @return left padded String + * @throws NullPointerException if str or delim is null */ public static String leftPad(String str, int size) { return leftPad(str, size, " "); @@ -946,6 +973,8 @@ public static String leftPad(String str, int size) { * @param size int size to pad to * @param delim String to pad with * @return left padded String + * @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) { size = (size - str.length()) / delim.length(); @@ -1212,11 +1241,12 @@ public static String capitaliseAllWords(String str) { /** * Get the String that is nested in between two instances of the - * same String. + * same String. If str is null, will return null * * @param str the string containing nested-string * @param tag the string before and after nested-string * @return the string that was nested, or null + * @throws NullPointerException if tag is null */ public static String getNestedString(String str, String tag) { return getNestedString(str, tag, tag); @@ -1229,6 +1259,7 @@ public static String getNestedString(String str, String tag) { * @param open the string before nested-string * @param close the string after nested-string * @return the string that was nested, or null + * @throws NullPointerException if open or close is null */ public static String getNestedString(String str, String open, String close) { if (str == null) { @@ -1251,6 +1282,7 @@ public static String getNestedString(String str, String open, String close) { * @param str the string to check * @param sub the substring to count * @return the number of occurances, 0 if the string is null + * @throws NullPointerException if sub is null */ public static int countMatches(String str, String sub) { if (str == null) { @@ -1270,7 +1302,7 @@ public static int countMatches(String str, String sub) { /** * Checks if the string contains only unicode letters. - * Null will return null. + * Null will return false. The empty string will return true. * * @param str the string to check * @return true if only contains letters, and is non-null @@ -1290,7 +1322,7 @@ public static boolean isAlpha(String str) { /** * Checks if the string contains only unicode letters and space (' '). - * Null will return null. + * Null will return false. The empty string will return true. * * @param str the string to check * @return true if only contains letters and space, and is non-null @@ -1311,7 +1343,7 @@ public static boolean isAlphaSpace(String str) { /** * Checks if the string contains only unicode letters or digits. - * Null will return null. + * Null will return false. The empty string will return true. * * @param str the string to check * @return true if only contains letters or digits, and is non-null @@ -1331,7 +1363,7 @@ public static boolean isAlphanumeric(String str) { /** * Checks if the string contains only unicode letters, digits or space (' '). - * Null will return null. + * Null will return false. The empty string will return true. * * @param str the string to check * @return true if only contains letters, digits or space, and is non-null @@ -1352,7 +1384,7 @@ public static boolean isAlphanumericSpace(String str) { /** * Checks if the string contains only unicode digits. - * Null will return null. + * Null will return false. The empty string will return true. * * @param str the string to check * @return true if only contains digits, and is non-null @@ -1372,7 +1404,7 @@ public static boolean isNumeric(String str) { /** * Checks if the string contains only unicode digits or space (' '). - * Null will return null. + * Null will return false. The empty string will return true. * * @param str the string to check * @return true if only contains digits or space, and is non-null @@ -1484,6 +1516,7 @@ private static void reverseArray(Object[] array) { * @param s the first String * @param t the second String * @return int result distance + * @throws NullPointerException if s or t is null */ public static int getLevenshteinDistance(String s, String t) { int d[][]; // matrix