Useful for identifying programmer errors early and clearly at runtime. * *
For example, if the contract of a public method states it does not - * allow {@code null} arguments, Assert can be used to validate that + * allow {@code null} arguments, {@code Assert} can be used to validate that * contract. Doing this clearly indicates a contract violation when it * occurs and protects the class's invariants. * *
Typically used to validate method arguments rather than configuration - * properties, to check for cases that are usually programmer errors rather than - * configuration errors. In contrast to config initialization code, there is - * usally no point in falling back to defaults in such methods. + * properties, to check for cases that are usually programmer errors rather + * than configuration errors. In contrast to configuration initialization + * code, there is usually no point in falling back to defaults in such methods. * *
This class is similar to JUnit's assertion library. If an argument value is * deemed invalid, an {@link IllegalArgumentException} is thrown (typically). @@ -41,13 +42,15 @@ import java.util.Map; * Assert.notNull(clazz, "The class must not be null"); * Assert.isTrue(i > 0, "The value must be greater than zero"); * - * Mainly for internal use within the framework; consider Apache's Commons Lang - * >= 2.0 for a more comprehensive suite of assertion utilities. + *
Mainly for internal use within the framework; consider + * Apache's Commons Lang + * for a more comprehensive suite of {@code String} utilities. * * @author Keith Donald * @author Juergen Hoeller * @author Colin Sampaleanu * @author Rob Harrop + * @author Sam Brannen * @since 1.1.2 */ public abstract class Assert { @@ -130,6 +133,7 @@ public abstract class Assert { * @param text the String to check * @param message the exception message to use if the assertion fails * @see StringUtils#hasLength + * @throws IllegalArgumentException if the text is empty */ public static void hasLength(String text, String message) { if (!StringUtils.hasLength(text)) { @@ -143,6 +147,7 @@ public abstract class Assert { *
Assert.hasLength(name);* @param text the String to check * @see StringUtils#hasLength + * @throws IllegalArgumentException if the text is empty */ public static void hasLength(String text) { hasLength(text, @@ -156,6 +161,7 @@ public abstract class Assert { * @param text the String to check * @param message the exception message to use if the assertion fails * @see StringUtils#hasText + * @throws IllegalArgumentException if the text does not contain valid text content */ public static void hasText(String text, String message) { if (!StringUtils.hasText(text)) { @@ -169,6 +175,7 @@ public abstract class Assert { *
Assert.hasText(name, "'name' must not be empty");* @param text the String to check * @see StringUtils#hasText + * @throws IllegalArgumentException if the text does not contain valid text content */ public static void hasText(String text) { hasText(text, @@ -181,6 +188,7 @@ public abstract class Assert { * @param textToSearch the text to search * @param substring the substring to find within the text * @param message the exception message to use if the assertion fails + * @throws IllegalArgumentException if the text contains the substring */ public static void doesNotContain(String textToSearch, String substring, String message) { if (StringUtils.hasLength(textToSearch) && StringUtils.hasLength(substring) && @@ -194,13 +202,13 @@ public abstract class Assert { *
Assert.doesNotContain(name, "rod");* @param textToSearch the text to search * @param substring the substring to find within the text + * @throws IllegalArgumentException if the text contains the substring */ public static void doesNotContain(String textToSearch, String substring) { doesNotContain(textToSearch, substring, "[Assertion failed] - this String argument must not contain the substring [" + substring + "]"); } - /** * Assert that an array has elements; that is, it must not be * {@code null} and must have at least one element. @@ -306,7 +314,6 @@ public abstract class Assert { notEmpty(map, "[Assertion failed] - this map must not be empty; it must contain at least one entry"); } - /** * Assert that the provided object is an instance of the provided class. *
Assert.instanceOf(Foo.class, foo);@@ -326,8 +333,8 @@ public abstract class Assert { * @param obj the object to check * @param message a message which will be prepended to the message produced by * the function itself, and which may be used to provide context. It should - * normally end in a ": " or ". " so that the function generate message looks - * ok when prepended to it. + * normally end in ":" or "." so that the generated message looks OK when + * appended to it. * @throws IllegalArgumentException if the object is not an instance of clazz * @see Class#isInstance */ @@ -359,18 +366,18 @@ public abstract class Assert { * @param subType the sub type to check * @param message a message which will be prepended to the message produced by * the function itself, and which may be used to provide context. It should - * normally end in a ": " or ". " so that the function generate message looks - * ok when prepended to it. + * normally end in ":" or "." so that the generated message looks OK when + * appended to it. * @throws IllegalArgumentException if the classes are not assignable */ public static void isAssignable(Class superType, Class subType, String message) { notNull(superType, "Type to check against must not be null"); if (subType == null || !superType.isAssignableFrom(subType)) { - throw new IllegalArgumentException(message + subType + " is not assignable to " + superType); + throw new IllegalArgumentException((StringUtils.hasLength(message) ? message + " " : "") + + subType + " is not assignable to " + superType); } } - /** * Assert a boolean expression, throwing {@code IllegalStateException} * if the test result is {@code false}. Call isTrue if you wish to diff --git a/spring-core/src/main/java/org/springframework/util/StringUtils.java b/spring-core/src/main/java/org/springframework/util/StringUtils.java index 6663c2cf9a2..ea9c3bf2ede 100644 --- a/spring-core/src/main/java/org/springframework/util/StringUtils.java +++ b/spring-core/src/main/java/org/springframework/util/StringUtils.java @@ -35,14 +35,13 @@ import java.util.TreeSet; * Miscellaneous {@link String} utility methods. * *
Mainly for internal use within the framework; consider - * Apache's Commons Lang - * for a more comprehensive suite of String utilities. + * Apache's Commons Lang + * for a more comprehensive suite of {@code String} utilities. * - *
This class delivers some simple functionality that should really - * be provided by the core Java {@code String} and {@link StringBuilder} - * classes, such as the ability to {@link #replace} all occurrences of a given - * substring in a target string. It also provides easy-to-use methods to convert - * between delimited strings, such as CSV strings, and collections and arrays. + *
This class delivers some simple functionality that should really be + * provided by the core Java {@link String} and {@link StringBuilder} + * classes. It also provides easy-to-use methods to convert between + * delimited strings, such as CSV strings, and collections and arrays. * * @author Rod Johnson * @author Juergen Hoeller @@ -71,7 +70,7 @@ public abstract class StringUtils { //--------------------------------------------------------------------- /** - * Check whether the given String is empty. + * Check whether the given {@code String} is empty. *
This method accepts any Object as an argument, comparing it to * {@code null} and the empty String. As a consequence, this method * will never return {@code true} for a non-null non-String object. @@ -128,8 +127,8 @@ public abstract class StringUtils { * StringUtils.hasLength(" ") = true * StringUtils.hasLength("Hello") = true * - * @param str the CharSequence to check (may be {@code null}) - * @return {@code true} if the CharSequence is not null and has length + * @param str the {@code CharSequence} to check (may be {@code null}) + * @return {@code true} if the {@code CharSequence} is not {@code null} and has length * @see #hasText(String) */ public static boolean hasLength(CharSequence str) { @@ -137,20 +136,23 @@ public abstract class StringUtils { } /** - * Check that the given String is neither {@code null} nor of length 0. - * Note: Will return {@code true} for a String that purely consists of whitespace. - * @param str the String to check (may be {@code null}) - * @return {@code true} if the String is not null and has length + * Check that the given {@code String} is neither {@code null} nor of length 0. + *
Note: this method returns {@code true} for a {@code String} that + * purely consists of whitespace. + * @param str the {@code String} to check (may be {@code null}) + * @return {@code true} if the {@code String} is not {@code null} and has length * @see #hasLength(CharSequence) + * @see #hasText(String) */ public static boolean hasLength(String str) { return hasLength((CharSequence) str); } /** - * Check whether the given CharSequence has actual text. - * More specifically, returns {@code true} if the string not {@code null}, - * its length is greater than 0, and it contains at least one non-whitespace character. + * Check whether the given {@code CharSequence} contains actual text. + *
More specifically, this method returns {@code true} if the + * {@code CharSequence} is not {@code null}, its length is greater than + * 0, and it contains at least one non-whitespace character. *
* StringUtils.hasText(null) = false
* StringUtils.hasText("") = false
@@ -158,8 +160,8 @@ public abstract class StringUtils {
* StringUtils.hasText("12345") = true
* StringUtils.hasText(" 12345 ") = true
*
- * @param str the CharSequence to check (may be {@code null})
- * @return {@code true} if the CharSequence is not {@code null},
+ * @param str the {@code CharSequence} to check (may be {@code null})
+ * @return {@code true} if the {@code CharSequence} is not {@code null},
* its length is greater than 0, and it does not contain whitespace only
* @see Character#isWhitespace
*/
@@ -177,12 +179,13 @@ public abstract class StringUtils {
}
/**
- * Check whether the given String has actual text.
- * More specifically, returns {@code true} if the string not {@code null},
- * its length is greater than 0, and it contains at least one non-whitespace character.
- * @param str the String to check (may be {@code null})
- * @return {@code true} if the String is not {@code null}, its length is
- * greater than 0, and it does not contain whitespace only
+ * Check whether the given {@code String} contains actual text.
+ * More specifically, this method returns {@code true} if the + * {@code String} is not {@code null}, its length is greater than 0, + * and it contains at least one non-whitespace character. + * @param str the {@code String} to check (may be {@code null}) + * @return {@code true} if the {@code String} is not {@code null}, its + * length is greater than 0, and it does not contain whitespace only * @see #hasText(CharSequence) */ public static boolean hasText(String str) { @@ -190,9 +193,9 @@ public abstract class StringUtils { } /** - * Check whether the given CharSequence contains any whitespace characters. - * @param str the CharSequence to check (may be {@code null}) - * @return {@code true} if the CharSequence is not empty and + * Check whether the given {@code CharSequence} contains any whitespace characters. + * @param str the {@code CharSequence} to check (may be {@code null}) + * @return {@code true} if the {@code CharSequence} is not empty and * contains at least 1 whitespace character * @see Character#isWhitespace */ @@ -210,9 +213,9 @@ public abstract class StringUtils { } /** - * Check whether the given String contains any whitespace characters. - * @param str the String to check (may be {@code null}) - * @return {@code true} if the String is not empty and + * Check whether the given {@code String} contains any whitespace characters. + * @param str the {@code String} to check (may be {@code null}) + * @return {@code true} if the {@code String} is not empty and * contains at least 1 whitespace character * @see #containsWhitespace(CharSequence) */ @@ -221,9 +224,9 @@ public abstract class StringUtils { } /** - * Trim leading and trailing whitespace from the given String. - * @param str the String to check - * @return the trimmed String + * Trim leading and trailing whitespace from the given {@code String}. + * @param str the {@code String} to check + * @return the trimmed {@code String} * @see java.lang.Character#isWhitespace */ public static String trimWhitespace(String str) { @@ -241,10 +244,10 @@ public abstract class StringUtils { } /** - * Trim all whitespace from the given String: + * Trim all whitespace from the given {@code String}: * leading, trailing, and in between characters. - * @param str the String to check - * @return the trimmed String + * @param str the {@code String} to check + * @return the trimmed {@code String} * @see java.lang.Character#isWhitespace */ public static String trimAllWhitespace(String str) { @@ -263,9 +266,9 @@ public abstract class StringUtils { } /** - * Trim leading whitespace from the given String. - * @param str the String to check - * @return the trimmed String + * Trim leading whitespace from the given {@code String}. + * @param str the {@code String} to check + * @return the trimmed {@code String} * @see java.lang.Character#isWhitespace */ public static String trimLeadingWhitespace(String str) { @@ -280,9 +283,9 @@ public abstract class StringUtils { } /** - * Trim trailing whitespace from the given String. - * @param str the String to check - * @return the trimmed String + * Trim trailing whitespace from the given {@code String}. + * @param str the {@code String} to check + * @return the trimmed {@code String} * @see java.lang.Character#isWhitespace */ public static String trimTrailingWhitespace(String str) { @@ -297,10 +300,10 @@ public abstract class StringUtils { } /** - * Trim all occurrences of the supplied leading character from the given String. - * @param str the String to check + * Trim all occurrences of the supplied leading character from the given {@code String}. + * @param str the {@code String} to check * @param leadingCharacter the leading character to be trimmed - * @return the trimmed String + * @return the trimmed {@code String} */ public static String trimLeadingCharacter(String str, char leadingCharacter) { if (!hasLength(str)) { @@ -314,10 +317,10 @@ public abstract class StringUtils { } /** - * Trim all occurrences of the supplied trailing character from the given String. - * @param str the String to check + * Trim all occurrences of the supplied trailing character from the given {@code String}. + * @param str the {@code String} to check * @param trailingCharacter the trailing character to be trimmed - * @return the trimmed String + * @return the trimmed {@code String} */ public static String trimTrailingCharacter(String str, char trailingCharacter) { if (!hasLength(str)) { @@ -332,9 +335,9 @@ public abstract class StringUtils { /** - * Test if the given String starts with the specified prefix, + * Test if the given {@code String} starts with the specified prefix, * ignoring upper/lower case. - * @param str the String to check + * @param str the {@code String} to check * @param prefix the prefix to look for * @see java.lang.String#startsWith */ @@ -354,9 +357,9 @@ public abstract class StringUtils { } /** - * Test if the given String ends with the specified suffix, + * Test if the given {@code String} ends with the specified suffix, * ignoring upper/lower case. - * @param str the String to check + * @param str the {@code String} to check * @param suffix the suffix to look for * @see java.lang.String#endsWith */ @@ -394,9 +397,9 @@ public abstract class StringUtils { } /** - * Count the occurrences of the substring in string s. - * @param str string to search in. Return 0 if this is null. - * @param sub string to search for. Return 0 if this is null. + * Count the occurrences of the substring {@code sub} in string {@code str}. + * @param str string to search in. Return 0 if this is {@code null}. + * @param sub string to search for. Return 0 if this is {@code null}. */ public static int countOccurrencesOf(String str, String sub) { if (str == null || sub == null || str.length() == 0 || sub.length() == 0) { @@ -415,10 +418,10 @@ public abstract class StringUtils { /** * Replace all occurrences of a substring within a string with * another string. - * @param inString String to examine - * @param oldPattern String to replace - * @param newPattern String to insert - * @return a String with the replacements + * @param inString {@code String} to examine + * @param oldPattern {@code String} to replace + * @param newPattern {@code String} to insert + * @return a {@code String} with the replacements */ public static String replace(String inString, String oldPattern, String newPattern) { if (!hasLength(inString) || !hasLength(oldPattern) || newPattern == null) { @@ -442,20 +445,20 @@ public abstract class StringUtils { /** * Delete all occurrences of the given substring. - * @param inString the original String + * @param inString the original {@code String} * @param pattern the pattern to delete all occurrences of - * @return the resulting String + * @return the resulting {@code String} */ public static String delete(String inString, String pattern) { return replace(inString, pattern, ""); } /** - * Delete any character in a given String. - * @param inString the original String + * Delete any character in a given {@code String}. + * @param inString the original {@code String} * @param charsToDelete a set of characters to delete. * E.g. "az\n" will delete 'a's, 'z's and new lines. - * @return the resulting String + * @return the resulting {@code String} */ public static String deleteAny(String inString, String charsToDelete) { if (!hasLength(inString) || !hasLength(charsToDelete)) { @@ -477,9 +480,9 @@ public abstract class StringUtils { //--------------------------------------------------------------------- /** - * Quote the given String with single quotes. - * @param str the input String (e.g. "myString") - * @return the quoted String (e.g. "'myString'"), + * Quote the given {@code String} with single quotes. + * @param str the input {@code String} (e.g. "myString") + * @return the quoted {@code String} (e.g. "'myString'"), * or {@code null} if the input was {@code null} */ public static String quote(String str) { @@ -487,11 +490,11 @@ public abstract class StringUtils { } /** - * Turn the given Object into a String with single quotes - * if it is a String; keeping the Object as-is else. + * Turn the given Object into a {@code String} with single quotes + * if it is a {@code String}; keeping the Object as-is else. * @param obj the input Object (e.g. "myString") - * @return the quoted String (e.g. "'myString'"), - * or the input object as-is if not a String + * @return the quoted {@code String} (e.g. "'myString'"), + * or the input object as-is if not a {@code String} */ public static Object quoteIfString(Object obj) { return (obj instanceof String ? quote((String) obj) : obj); @@ -520,8 +523,9 @@ public abstract class StringUtils { * Capitalize a {@code String}, changing the first letter to * upper case as per {@link Character#toUpperCase(char)}. * No other letters are changed. - * @param str the String to capitalize, may be {@code null} - * @return the capitalized String, {@code null} if null + * @param str the {@code String} to capitalize, may be {@code null} + * @return the capitalized {@code String}, or {@code null} if the supplied + * string is {@code null} */ public static String capitalize(String str) { return changeFirstCharacterCase(str, true); @@ -531,8 +535,9 @@ public abstract class StringUtils { * Uncapitalize a {@code String}, changing the first letter to * lower case as per {@link Character#toLowerCase(char)}. * No other letters are changed. - * @param str the String to uncapitalize, may be {@code null} - * @return the uncapitalized String, {@code null} if null + * @param str the {@code String} to uncapitalize, may be {@code null} + * @return the uncapitalized {@code String}, or {@code null} if the supplied + * string is {@code null} */ public static String uncapitalize(String str) { return changeFirstCharacterCase(str, false); @@ -555,7 +560,7 @@ public abstract class StringUtils { /** * Extract the filename from the given path, - * e.g. "mypath/myfile.txt" -> "myfile.txt". + * e.g. {@code "mypath/myfile.txt" -> "myfile.txt"}. * @param path the file path (may be {@code null}) * @return the extracted filename, or {@code null} if none */ @@ -712,7 +717,7 @@ public abstract class StringUtils { /** * Parse the given {@code localeString} value into a {@link Locale}. *
This is the inverse operation of {@link Locale#toString Locale's toString}. - * @param localeString the locale String, following {@code Locale's} + * @param localeString the locale {@code String}, following {@code Locale's} * {@code toString()} format ("en", "en_UK", etc); * also accepts spaces as separators, as an alternative to underscores * @return a corresponding {@code Locale} instance @@ -752,7 +757,7 @@ public abstract class StringUtils { * Determine the RFC 3066 compliant language tag, * as used for the HTTP "Accept-Language" header. * @param locale the Locale to transform to a language tag - * @return the RFC 3066 compliant language tag as String + * @return the RFC 3066 compliant language tag as {@code String} */ public static String toLanguageTag(Locale locale) { return locale.getLanguage() + (hasText(locale.getCountry()) ? "-" + locale.getCountry() : ""); @@ -760,7 +765,7 @@ public abstract class StringUtils { /** * Parse the given {@code timeZoneString} value into a {@link TimeZone}. - * @param timeZoneString the time zone String, following {@link TimeZone#getTimeZone(String)} + * @param timeZoneString the time zone {@code String}, following {@link TimeZone#getTimeZone(String)} * but throwing {@link IllegalArgumentException} in case of an invalid time zone specification * @return a corresponding {@link TimeZone} instance * @throws IllegalArgumentException in case of an invalid time zone specification @@ -780,10 +785,11 @@ public abstract class StringUtils { //--------------------------------------------------------------------- /** - * Append the given String to the given String array, returning a new array - * consisting of the input array contents plus the given String. + * Append the given {@code String} to the given {@code String} array, + * returning a new array consisting of the input array contents plus + * the given {@code String}. * @param array the array to append to (can be {@code null}) - * @param str the String to append + * @param str the {@code String} to append * @return the new array (never {@code null}) */ public static String[] addStringToArray(String[] array, String str) { @@ -797,7 +803,7 @@ public abstract class StringUtils { } /** - * Concatenate the given String arrays into one, + * Concatenate the given {@code String} arrays into one, * with overlapping array elements included twice. *
The order of elements in the original arrays is preserved. * @param array1 the first array (can be {@code null}) @@ -818,7 +824,7 @@ public abstract class StringUtils { } /** - * Merge the given String arrays into one, with overlapping + * Merge the given {@code String} arrays into one, with overlapping * array elements only included once. *
The order of elements in the original arrays is preserved * (with the exception of overlapping elements, which are only @@ -845,7 +851,7 @@ public abstract class StringUtils { } /** - * Turn given source String array into sorted array. + * Turn given source {@code String} array into sorted array. * @param array the source array * @return the sorted array (never {@code null}) */ @@ -858,11 +864,11 @@ public abstract class StringUtils { } /** - * Copy the given Collection into a String array. - * The Collection must contain String elements only. - * @param collection the Collection to copy - * @return the String array ({@code null} if the passed-in - * Collection was {@code null}) + * Copy the given {@code Collection} into a {@code String} array. + *
The {@code Collection} must contain {@code String} elements only.
+ * @param collection the {@code Collection} to copy
+ * @return the {@code String} array ({@code null} if the supplied
+ * {@code Collection} was {@code null})
*/
public static String[] toStringArray(Collection Also sorts the array, as it uses a {@link TreeSet}.
+ * @param array the {@code String} array
* @return an array without duplicates, in natural sort order
*/
public static String[] removeDuplicateStrings(String[] array) {
@@ -922,13 +928,13 @@ public abstract class StringUtils {
}
/**
- * Split a String at the first occurrence of the delimiter.
+ * Split a {@code String} at the first occurrence of the delimiter.
* Does not include the delimiter in the result.
* @param toSplit the string to split
* @param delimiter to split the string up with
* @return a two element array with index 0 being before the delimiter, and
* index 1 being after the delimiter (neither element includes the delimiter);
- * or {@code null} if the delimiter wasn't found in the given input String
+ * or {@code null} if the delimiter wasn't found in the given input {@code String}
*/
public static String[] split(String toSplit, String delimiter) {
if (!hasLength(toSplit) || !hasLength(delimiter)) {
@@ -944,7 +950,7 @@ public abstract class StringUtils {
}
/**
- * Take an array Strings and split each element based on the given delimiter.
+ * Take an array of strings and split each element based on the given delimiter.
* A {@code Properties} instance is then generated, with the left of the
* delimiter providing the key, and the right of the delimiter providing the value.
* Will trim both the key and value before adding them to the
@@ -952,14 +958,14 @@ public abstract class StringUtils {
* @param array the array to process
* @param delimiter to split each element using (typically the equals symbol)
* @return a {@code Properties} instance representing the array contents,
- * or {@code null} if the array to process was null or empty
+ * or {@code null} if the array to process was {@code null} or empty
*/
public static Properties splitArrayElementsIntoProperties(String[] array, String delimiter) {
return splitArrayElementsIntoProperties(array, delimiter, null);
}
/**
- * Take an array Strings and split each element based on the given delimiter.
+ * Take an array of strings and split each element based on the given delimiter.
* A {@code Properties} instance is then generated, with the left of the
* delimiter providing the key, and the right of the delimiter providing the value.
* Will trim both the key and value before adding them to the
@@ -993,15 +999,16 @@ public abstract class StringUtils {
}
/**
- * Tokenize the given String into a String array via a StringTokenizer.
- * Trims tokens and omits empty tokens.
- * The given delimiters string is supposed to consist of any number of
+ * Tokenize the given {@code String} into a {@code String} array via a
+ * {@link StringTokenizer}.
+ * Trims tokens and omits empty tokens.
+ * The given {@code delimiters} string can consist of any number of
* delimiter characters. Each of those characters can be used to separate
* tokens. A delimiter is always a single character; for multi-character
- * delimiters, consider using {@code delimitedListToStringArray}
- * @param str the String to tokenize
- * @param delimiters the delimiter characters, assembled as String
- * (each of those characters is individually considered as delimiter).
+ * delimiters, consider using {@link #delimitedListToStringArray}.
+ * @param str the {@code String} to tokenize
+ * @param delimiters the delimiter characters, assembled as a {@code String}
+ * (each of the characters is individually considered as a delimiter)
* @return an array of the tokens
* @see java.util.StringTokenizer
* @see String#trim()
@@ -1012,19 +1019,20 @@ public abstract class StringUtils {
}
/**
- * Tokenize the given String into a String array via a StringTokenizer.
- * The given delimiters string is supposed to consist of any number of
+ * Tokenize the given {@code String} into a {@code String} array via a
+ * {@link StringTokenizer}.
+ * The given {@code delimiters} string can consist of any number of
* delimiter characters. Each of those characters can be used to separate
* tokens. A delimiter is always a single character; for multi-character
- * delimiters, consider using {@code delimitedListToStringArray}
- * @param str the String to tokenize
- * @param delimiters the delimiter characters, assembled as String
- * (each of those characters is individually considered as delimiter)
- * @param trimTokens trim the tokens via String's {@code trim}
+ * delimiters, consider using {@link #delimitedListToStringArray}.
+ * @param str the {@code String} to tokenize
+ * @param delimiters the delimiter characters, assembled as a {@code String}
+ * (each of the characters is individually considered as a delimiter)
+ * @param trimTokens trim the tokens via {@link String#trim()}
* @param ignoreEmptyTokens omit empty tokens from the result array
* (only applies to tokens that are empty after trimming; StringTokenizer
* will not consider subsequent delimiters as token in the first place).
- * @return an array of the tokens ({@code null} if the input String
+ * @return an array of the tokens ({@code null} if the input {@code String}
* was {@code null})
* @see java.util.StringTokenizer
* @see String#trim()
@@ -1051,11 +1059,13 @@ public abstract class StringUtils {
}
/**
- * Take a String which is a delimited list and convert it to a String array.
- * A single delimiter can consists of more than one character: It will still
- * be considered as single delimiter string, rather than as bunch of potential
- * delimiter characters - in contrast to {@code tokenizeToStringArray}.
- * @param str the input String
+ * Take a {@code String} that is a delimited list and convert it into a
+ * {@code String} array.
+ * A single {@code delimiter} may consist of more than one character,
+ * but it will still be considered as a single delimiter string, rather
+ * than as bunch of potential delimiter characters, in contrast to
+ * {@link #tokenizeToStringArray}.
+ * @param str the input {@code String}
* @param delimiter the delimiter between elements (this is a single delimiter,
* rather than a bunch individual delimiter characters)
* @return an array of the tokens in the list
@@ -1066,15 +1076,17 @@ public abstract class StringUtils {
}
/**
- * Take a String which is a delimited list and convert it to a String array.
- * A single delimiter can consists of more than one character: It will still
- * be considered as single delimiter string, rather than as bunch of potential
- * delimiter characters - in contrast to {@code tokenizeToStringArray}.
- * @param str the input String
+ * Take a {@code String} that is a delimited list and convert it into
+ * a {@code String} array.
+ * A single {@code delimiter} may consist of more than one character,
+ * but it will still be considered as a single delimiter string, rather
+ * than as bunch of potential delimiter characters, in contrast to
+ * {@link #tokenizeToStringArray}.
+ * @param str the input {@code String}
* @param delimiter the delimiter between elements (this is a single delimiter,
* rather than a bunch individual delimiter characters)
- * @param charsToDelete a set of characters to delete. Useful for deleting unwanted
- * line breaks: e.g. "\r\n\f" will delete all new lines and line feeds in a String.
+ * @param charsToDelete a set of characters to delete; useful for deleting unwanted
+ * line breaks: e.g. "\r\n\f" will delete all new lines and line feeds in a {@code String}
* @return an array of the tokens in the list
* @see #tokenizeToStringArray
*/
@@ -1107,19 +1119,21 @@ public abstract class StringUtils {
}
/**
- * Convert a CSV list into an array of Strings.
- * @param str the input String
- * @return an array of Strings, or the empty array in case of empty input
+ * Convert a comma delimited list (e.g., a row from a CSV file) into an
+ * array of strings.
+ * @param str the input {@code String}
+ * @return an array of strings, or the empty array in case of empty input
*/
public static String[] commaDelimitedListToStringArray(String str) {
return delimitedListToStringArray(str, ",");
}
/**
- * Convenience method to convert a CSV string list to a set.
- * Note that this will suppress duplicates.
- * @param str the input String
- * @return a Set of String entries in the list
+ * Convert a comma delimited list (e.g., a row from a CSV file) into a set.
+ * Note that this will suppress duplicates, and the elements in the
+ * returned set will be sorted, since a {@link TreeSet} is used internally.
+ * @param str the input {@code String}
+ * @return a set of {@code String} entries in the list
*/
public static Set Useful for {@code toString()} implementations.
+ * @param coll the {@code Collection} to convert
+ * @param delim the delimiter to use (typically a ",")
+ * @param prefix the {@code String} to start each element with
+ * @param suffix the {@code String} to end each element with
+ * @return the delimited {@code String}
*/
public static String collectionToDelimitedString(Collection coll, String delim, String prefix, String suffix) {
if (CollectionUtils.isEmpty(coll)) {
@@ -1155,32 +1169,32 @@ public abstract class StringUtils {
}
/**
- * Convenience method to return a Collection as a delimited (e.g. CSV)
- * String. E.g. useful for {@code toString()} implementations.
- * @param coll the Collection to display
- * @param delim the delimiter to use (probably a ",")
- * @return the delimited String
+ * Convert a {@code Collection} into a delimited {@code String} (e.g. CSV).
+ * Useful for {@code toString()} implementations.
+ * @param coll the {@code Collection} to convert
+ * @param delim the delimiter to use (typically a ",")
+ * @return the delimited {@code String}
*/
public static String collectionToDelimitedString(Collection coll, String delim) {
return collectionToDelimitedString(coll, delim, "", "");
}
/**
- * Convenience method to return a Collection as a CSV String.
- * E.g. useful for {@code toString()} implementations.
- * @param coll the Collection to display
- * @return the delimited String
+ * Convert a {@code Collection} into a delimited {@code String} (e.g., CSV).
+ * Useful for {@code toString()} implementations.
+ * @param coll the {@code Collection} to convert
+ * @return the delimited {@code String}
*/
public static String collectionToCommaDelimitedString(Collection coll) {
return collectionToDelimitedString(coll, ",");
}
/**
- * Convenience method to return a String array as a delimited (e.g. CSV)
- * String. E.g. useful for {@code toString()} implementations.
+ * Convert a {@code String} array into a delimited {@code String} (e.g. CSV).
+ * Useful for {@code toString()} implementations.
* @param arr the array to display
- * @param delim the delimiter to use (probably a ",")
- * @return the delimited String
+ * @param delim the delimiter to use (typically a ",")
+ * @return the delimited {@code String}
*/
public static String arrayToDelimitedString(Object[] arr, String delim) {
if (ObjectUtils.isEmpty(arr)) {
@@ -1200,10 +1214,11 @@ public abstract class StringUtils {
}
/**
- * Convenience method to return a String array as a CSV String.
- * E.g. useful for {@code toString()} implementations.
+ * Convert a {@code String} array into a comma delimited {@code String}
+ * (i.e., CSV).
+ * Useful for {@code toString()} implementations.
* @param arr the array to display
- * @return the delimited String
+ * @return the delimited {@code String}
*/
public static String arrayToCommaDelimitedString(Object[] arr) {
return arrayToDelimitedString(arr, ",");