提交 fefbd8f8 编写于 作者: S Sam Brannen

Polish Javadoc for StringUtils and Assert

上级 47f8d435
......@@ -21,17 +21,18 @@ import java.util.Map;
/**
* Assertion utility class that assists in validating arguments.
* Useful for identifying programmer errors early and clearly at runtime.
*
* <p>Useful for identifying programmer errors early and clearly at runtime.
*
* <p>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.
*
* <p>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.
*
* <p>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");</pre>
*
* Mainly for internal use within the framework; consider Apache's Commons Lang
* >= 2.0 for a more comprehensive suite of assertion utilities.
* <p>Mainly for internal use within the framework; consider
* <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a>
* 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 {
* <pre class="code">Assert.hasLength(name);</pre>
* @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 {
* <pre class="code">Assert.hasText(name, "'name' must not be empty");</pre>
* @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 {
* <pre class="code">Assert.doesNotContain(name, "rod");</pre>
* @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.
* <pre class="code">Assert.instanceOf(Foo.class, foo);</pre>
......@@ -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
......
......@@ -35,14 +35,13 @@ import java.util.TreeSet;
* Miscellaneous {@link String} utility methods.
*
* <p>Mainly for internal use within the framework; consider
* <a href="http://jakarta.apache.org/commons/lang/">Apache's Commons Lang</a>
* for a more comprehensive suite of String utilities.
* <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a>
* for a more comprehensive suite of {@code String} utilities.
*
* <p>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.
* <p>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.
* <p>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
* </pre>
* @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.
* <p>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 <em>text</em>.
* <p>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.
* <p><pre class="code">
* StringUtils.hasText(null) = false
* StringUtils.hasText("") = false
......@@ -158,8 +160,8 @@ public abstract class StringUtils {
* StringUtils.hasText("12345") = true
* StringUtils.hasText(" 12345 ") = true
* </pre>
* @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 <em>text</em>.
* <p>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 <i>all</i> whitespace from the given String:
* Trim <i>all</i> 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}.
* <p>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.
* <p>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.
* <p>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.
* <p>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<String> collection) {
if (collection == null) {
......@@ -872,10 +878,10 @@ public abstract class StringUtils {
}
/**
* Copy the given Enumeration into a String array.
* The Enumeration must contain String elements only.
* Copy the given Enumeration into a {@code String} array.
* The Enumeration must contain {@code String} elements only.
* @param enumeration the Enumeration to copy
* @return the String array ({@code null} if the passed-in
* @return the {@code String} array ({@code null} if the passed-in
* Enumeration was {@code null})
*/
public static String[] toStringArray(Enumeration<String> enumeration) {
......@@ -887,9 +893,9 @@ public abstract class StringUtils {
}
/**
* Trim the elements of the given String array,
* Trim the elements of the given {@code String} array,
* calling {@code String.trim()} on each of them.
* @param array the original String array
* @param array the original {@code String} array
* @return the resulting array (of the same size) with trimmed elements
*/
public static String[] trimArrayElements(String[] array) {
......@@ -905,9 +911,9 @@ public abstract class StringUtils {
}
/**
* Remove duplicate Strings from the given array.
* Also sorts the array, as it uses a TreeSet.
* @param array the String array
* Remove duplicate strings from the given array.
* <p>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.
* <p>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.
* <p>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.
* <p>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}.
* <p>Trims tokens and omits empty tokens.
* <p>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.
* <p>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}.
* <p>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.
* <p>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.
* <p>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.
* <p>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.
* <p>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.
* <p>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<String> commaDelimitedListToSet(String str) {
Set<String> set = new TreeSet<String>();
......@@ -1131,13 +1145,13 @@ 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 ",")
* @param prefix the String to start each element with
* @param suffix the String to end each element with
* @return the delimited String
* Convert a {@link Collection} to a delimited {@code String} (e.g. CSV).
* <p>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).
* <p>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).
* <p>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).
* <p>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).
* <p>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, ",");
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册