org.apache.commons.lang
public class StringUtils extends Object
Operations on java.lang.String that are
null
safe.
The StringUtils
class defines certain words related to
String handling.
null
""
)' '
, char 32)StringUtils
handles null
input Strings quietly.
That is to say that a null
input will return null
.
Where a boolean
or int
is being returned
details vary by method.
A side effect of the null
handling is that a
NullPointerException
should be considered a bug in
StringUtils
(except for deprecated methods).
Methods in this class give sample code to explain their operation.
The symbol *
is used to indicate any input including null
.
Since: 1.0
Version: $Id: StringUtils.java 492377 2007-01-04 01:20:30Z scolebourne $
See Also: java.lang.String
Field Summary | |
---|---|
static String | EMPTY
The empty String "" . |
static int | INDEX_NOT_FOUND
Represents a failed index search. |
Constructor Summary | |
---|---|
StringUtils()
|
Method Summary | |
---|---|
static String | abbreviate(String str, int maxWidth) Abbreviates a String using ellipses. |
static String | abbreviate(String str, int offset, int maxWidth) Abbreviates a String using ellipses. |
static String | capitalise(String str) Capitalizes a String changing the first letter to title case as per Character#toTitleCase(char). |
static String | capitaliseAllWords(String str) Capitalizes all the whitespace separated words in a String. |
static String | capitalize(String str) Capitalizes a String changing the first letter to title case as per Character#toTitleCase(char). |
static String | center(String str, int size) Centers a String in a larger String of size
If the size is less than the String length, the String is returned. |
static String | center(String str, int size, char padChar) Centers a String in a larger String of size |
static String | center(String str, int size, String padStr) Centers a String in a larger String of size |
static String | chomp(String str) Removes one newline from end of a String if it's there, otherwise leave it alone. |
static String | chomp(String str, String separator) Removes NOTE: This method changed in version 2.0. |
static String | chompLast(String str) Remove any "\n" if and only if it is at the end of the supplied String. |
static String | chompLast(String str, String sep) Remove a value if and only if the String ends with that value. |
static String | chop(String str) Remove the last character from a String. If the String ends in StringUtils.chop(null) = null StringUtils.chop("") = "" StringUtils.chop("abc \r") = "abc " StringUtils.chop("abc\n") = "abc" StringUtils.chop("abc\r\n") = "abc" StringUtils.chop("abc") = "ab" StringUtils.chop("abc\nabc") = "abc\nab" StringUtils.chop("a") = "" StringUtils.chop("\r") = "" StringUtils.chop("\n") = "" StringUtils.chop("\r\n") = "" |
static String | chopNewline(String str) Removes |
static String | clean(String str) Removes control characters (char <= 32) from both
ends of this String, handling StringUtils.clean(null) = "" StringUtils.clean("") = "" StringUtils.clean("abc") = "abc" StringUtils.clean(" abc ") = "abc" StringUtils.clean(" ") = "" |
static String | concatenate(Object[] array) Concatenates elements of an array into a single String. |
static boolean | contains(String str, char searchChar) Checks if String contains a search character, handling |
static boolean | contains(String str, String searchStr) Checks if String contains a search String, handling |
static boolean | containsIgnoreCase(String str, String searchStr) Checks if String contains a search String irrespective of case,
handling |
static boolean | containsNone(String str, char[] invalidChars) Checks that the String does not contain certain characters. A |
static boolean | containsNone(String str, String invalidChars) Checks that the String does not contain certain characters. A |
static boolean | containsOnly(String str, char[] valid) Checks if the String contains only certain characters. A |
static boolean | containsOnly(String str, String validChars) Checks if the String contains only certain characters. A |
static int | countMatches(String str, String sub) Counts how many times the substring appears in the larger String. A StringUtils.countMatches(null, *) = 0 StringUtils.countMatches("", *) = 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 |
static String | defaultIfEmpty(String str, String defaultStr) Returns either the passed in String, or if the String is
empty or StringUtils.defaultIfEmpty(null, "NULL") = "NULL" StringUtils.defaultIfEmpty("", "NULL") = "NULL" StringUtils.defaultIfEmpty("bat", "NULL") = "bat" |
static String | defaultString(String str) Returns either the passed in String,
or if the String is StringUtils.defaultString(null) = "" StringUtils.defaultString("") = "" StringUtils.defaultString("bat") = "bat" |
static String | defaultString(String str, String defaultStr) Returns either the passed in String, or if the String is
StringUtils.defaultString(null, "NULL") = "NULL" StringUtils.defaultString("", "NULL") = "" StringUtils.defaultString("bat", "NULL") = "bat" |
static String | deleteSpaces(String str) Deletes all 'space' characters from a String as defined by Character#isSpace(char). This is the only StringUtils method that uses the
|
static String | deleteWhitespace(String str) Deletes all whitespaces from a String as defined by Character#isWhitespace(char). StringUtils.deleteWhitespace(null) = null StringUtils.deleteWhitespace("") = "" StringUtils.deleteWhitespace("abc") = "abc" StringUtils.deleteWhitespace(" ab c ") = "abc" |
static String | difference(String str1, String str2) Compares two Strings, and returns the portion where they differ. |
static boolean | equals(String str1, String str2) Compares two Strings, returning
|
static boolean | equalsIgnoreCase(String str1, String str2) Compares two Strings, returning
|
static String | escape(String str) Escapes any values it finds into their String form. So a tab becomes the characters As of Lang 2.0, this calls escapeJava behind the scenes. |
static String | getChomp(String str, String sep) Remove everything and return the last value of a supplied String, and everything after it from a String. |
static int | getLevenshteinDistance(String s, String t) Find the Levenshtein distance between two Strings. This is the number of changes needed to change one String into another, where each change is a single character modification (deletion, insertion or substitution). The previous implementation of the Levenshtein distance algorithm was from http://www.merriampark.com/ld.htm Chas Emerick has written an implementation in Java, which avoids an OutOfMemoryError
which can occur when my Java implementation is used with very large strings. StringUtils.getLevenshteinDistance(null, *) = IllegalArgumentException StringUtils.getLevenshteinDistance(*, null) = IllegalArgumentException StringUtils.getLevenshteinDistance("","") = 0 StringUtils.getLevenshteinDistance("","a") = 1 StringUtils.getLevenshteinDistance("aaapppp", "") = 7 StringUtils.getLevenshteinDistance("frog", "fog") = 1 StringUtils.getLevenshteinDistance("fly", "ant") = 3 StringUtils.getLevenshteinDistance("elephant", "hippo") = 7 StringUtils.getLevenshteinDistance("hippo", "elephant") = 7 StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8 StringUtils.getLevenshteinDistance("hello", "hallo") = 1 |
static String | getNestedString(String str, String tag) Gets the String that is nested in between two instances of the same String. A |
static String | getNestedString(String str, String open, String close) Gets the String that is nested in between two Strings. |
static String | getPrechomp(String str, String sep) Remove and return everything before the first value of a supplied String from another String. |
static int | indexOf(String str, char searchChar) Finds the first index within a String, handling |
static int | indexOf(String str, char searchChar, int startPos) Finds the first index within a String from a start position,
handling |
static int | indexOf(String str, String searchStr) Finds the first index within a String, handling |
static int | indexOf(String str, String searchStr, int startPos) Finds the first index within a String, handling |
static int | indexOfAny(String str, char[] searchChars) Search a String to find the first index of any character in the given set of characters. A |
static int | indexOfAny(String str, String searchChars) Search a String to find the first index of any character in the given set of characters. A |
static int | indexOfAny(String str, String[] searchStrs) Find the first index of any of a set of potential substrings. A |
static int | indexOfAnyBut(String str, char[] searchChars) Search a String to find the first index of any character not in the given set of characters. A |
static int | indexOfAnyBut(String str, String searchChars) Search a String to find the first index of any character not in the given set of characters. A |
static int | indexOfDifference(String str1, String str2) Compares two Strings, and returns the index at which the Strings begin to differ. For example,
StringUtils.indexOfDifference(null, null) = -1 StringUtils.indexOfDifference("", "") = -1 StringUtils.indexOfDifference("", "abc") = 0 StringUtils.indexOfDifference("abc", "") = 0 StringUtils.indexOfDifference("abc", "abc") = -1 StringUtils.indexOfDifference("ab", "abxyz") = 2 StringUtils.indexOfDifference("abcde", "abxyz") = 2 StringUtils.indexOfDifference("abcde", "xyz") = 0 |
static boolean | isAlpha(String str) Checks if the String contains only unicode letters.
|
static boolean | isAlphanumeric(String str) Checks if the String contains only unicode letters or digits.
|
static boolean | isAlphanumericSpace(String str) Checks if the String contains only unicode letters, digits
or space (
|
static boolean | isAlphaSpace(String str) Checks if the String contains only unicode letters and space (' ').
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 |
static boolean | isAsciiPrintable(String str) Checks if the string contains only ASCII printable characters.
|
static boolean | isBlank(String str) Checks if a String is whitespace, empty ("") or null. StringUtils.isBlank(null) = true StringUtils.isBlank("") = true StringUtils.isBlank(" ") = true StringUtils.isBlank("bob") = false StringUtils.isBlank(" bob ") = false |
static boolean | isEmpty(String str) Checks if a String is empty ("") or null. StringUtils.isEmpty(null) = true StringUtils.isEmpty("") = true StringUtils.isEmpty(" ") = false StringUtils.isEmpty("bob") = false StringUtils.isEmpty(" bob ") = false NOTE: This method changed in Lang version 2.0. |
static boolean | isNotBlank(String str) Checks if a String is not empty (""), not null and not whitespace only. StringUtils.isNotBlank(null) = false StringUtils.isNotBlank("") = false StringUtils.isNotBlank(" ") = false StringUtils.isNotBlank("bob") = true StringUtils.isNotBlank(" bob ") = true |
static boolean | isNotEmpty(String str) Checks if a String is not empty ("") and not null. StringUtils.isNotEmpty(null) = false StringUtils.isNotEmpty("") = false StringUtils.isNotEmpty(" ") = true StringUtils.isNotEmpty("bob") = true StringUtils.isNotEmpty(" bob ") = true |
static boolean | isNumeric(String str) Checks if the String contains only unicode digits. |
static boolean | isNumericSpace(String str) Checks if the String contains only unicode digits or space
( |
static boolean | isWhitespace(String str) Checks if the String contains only whitespace.
|
static String | join(Object[] array) Joins the elements of the provided array into a single String containing the provided list of elements. No separator is added to the joined String. |
static String | join(Object[] array, char separator) Joins the elements of the provided array into a single String containing the provided list of elements. No delimiter is added before or after the list. |
static String | join(Object[] array, char separator, int startIndex, int endIndex) Joins the elements of the provided array into a single String containing the provided list of elements. No delimiter is added before or after the list. |
static String | join(Object[] array, String separator) Joins the elements of the provided array into a single String containing the provided list of elements. No delimiter is added before or after the list. |
static String | join(Object[] array, String separator, int startIndex, int endIndex) Joins the elements of the provided array into a single String containing the provided list of elements. No delimiter is added before or after the list. |
static String | join(Iterator iterator, char separator) Joins the elements of the provided No delimiter is added before or after the list. |
static String | join(Iterator iterator, String separator) Joins the elements of the provided No delimiter is added before or after the list. |
static String | join(Collection collection, char separator) Joins the elements of the provided No delimiter is added before or after the list. |
static String | join(Collection collection, String separator) Joins the elements of the provided No delimiter is added before or after the list. |
static int | lastIndexOf(String str, char searchChar) Finds the last index within a String, handling |
static int | lastIndexOf(String str, char searchChar, int startPos) Finds the last index within a String from a start position,
handling |
static int | lastIndexOf(String str, String searchStr) Finds the last index within a String, handling |
static int | lastIndexOf(String str, String searchStr, int startPos) Finds the first index within a String, handling |
static int | lastIndexOfAny(String str, String[] searchStrs) Find the latest index of any of a set of potential substrings. A |
static String | left(String str, int len) Gets the leftmost If |
static String | leftPad(String str, int size) Left pad a String with spaces (' '). The String is padded to the size of StringUtils.leftPad(null, *) = null StringUtils.leftPad("", 3) = " " StringUtils.leftPad("bat", 3) = "bat" StringUtils.leftPad("bat", 5) = " bat" StringUtils.leftPad("bat", 1) = "bat" StringUtils.leftPad("bat", -1) = "bat" |
static String | leftPad(String str, int size, char padChar) Left pad a String with a specified character. Pad to a size of StringUtils.leftPad(null, *, *) = null StringUtils.leftPad("", 3, 'z') = "zzz" StringUtils.leftPad("bat", 3, 'z') = "bat" StringUtils.leftPad("bat", 5, 'z') = "zzbat" StringUtils.leftPad("bat", 1, 'z') = "bat" StringUtils.leftPad("bat", -1, 'z') = "bat" |
static String | leftPad(String str, int size, String padStr) Left pad a String with a specified String. Pad to a size of StringUtils.leftPad(null, *, *) = null StringUtils.leftPad("", 3, "z") = "zzz" StringUtils.leftPad("bat", 3, "yz") = "bat" StringUtils.leftPad("bat", 5, "yz") = "yzbat" StringUtils.leftPad("bat", 8, "yz") = "yzyzybat" StringUtils.leftPad("bat", 1, "yz") = "bat" StringUtils.leftPad("bat", -1, "yz") = "bat" StringUtils.leftPad("bat", 5, null) = " bat" StringUtils.leftPad("bat", 5, "") = " bat" |
static String | lowerCase(String str) Converts a String to lower case as per String#toLowerCase(). A StringUtils.lowerCase(null) = null StringUtils.lowerCase("") = "" StringUtils.lowerCase("aBc") = "abc" |
static String | mid(String str, int pos, int len) Gets If |
static int | ordinalIndexOf(String str, String searchStr, int ordinal) Finds the n-th index within a String, handling |
static String | overlay(String str, String overlay, int start, int end) Overlays part of a String with another String. A |
static String | overlayString(String text, String overlay, int start, int end) Overlays part of a String with another String. StringUtils.overlayString(null, *, *, *) = NullPointerException StringUtils.overlayString(*, null, *, *) = NullPointerException 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" StringUtils.overlayString("abcdef", "zzzz", 4, 2) = "abcdzzzzcdef" StringUtils.overlayString("abcdef", "zzzz", -1, 4) = IndexOutOfBoundsException StringUtils.overlayString("abcdef", "zzzz", 2, 8) = IndexOutOfBoundsException |
static String | prechomp(String str, String sep) Remove the first value of a supplied String, and everything before it from a String. |
static String | remove(String str, String remove) Removes all occurances of a substring from within the source string. A |
static String | remove(String str, char remove) Removes all occurances of a character from within the source string. A |
static String | removeEnd(String str, String remove) Removes a substring only if it is at the end of a source string, otherwise returns the source string. A |
static String | removeStart(String str, String remove) Removes a substring only if it is at the begining of a source string, otherwise returns the source string. A |
static String | repeat(String str, int repeat) Repeat a String StringUtils.repeat(null, 2) = null StringUtils.repeat("", 0) = "" StringUtils.repeat("", 2) = "" StringUtils.repeat("a", 3) = "aaa" StringUtils.repeat("ab", 2) = "abab" StringUtils.repeat("a", -2) = "" |
static String | replace(String text, String repl, String with) Replaces all occurrences of a String within another String. A StringUtils.replace(null, *, *) = null StringUtils.replace("", *, *) = "" StringUtils.replace("any", null, *) = "any" StringUtils.replace("any", *, null) = "any" StringUtils.replace("any", "", *) = "any" StringUtils.replace("aba", "a", null) = "aba" StringUtils.replace("aba", "a", "") = "b" StringUtils.replace("aba", "a", "z") = "zbz" |
static String | replace(String text, String repl, String with, int max) Replaces a String with another String inside a larger String,
for the first A StringUtils.replace(null, *, *, *) = null StringUtils.replace("", *, *, *) = "" StringUtils.replace("any", null, *, *) = "any" StringUtils.replace("any", *, null, *) = "any" StringUtils.replace("any", "", *, *) = "any" StringUtils.replace("any", *, *, 0) = "any" StringUtils.replace("abaa", "a", null, -1) = "abaa" StringUtils.replace("abaa", "a", "", -1) = "b" StringUtils.replace("abaa", "a", "z", 0) = "abaa" StringUtils.replace("abaa", "a", "z", 1) = "zbaa" StringUtils.replace("abaa", "a", "z", 2) = "zbza" StringUtils.replace("abaa", "a", "z", -1) = "zbzz" |
static String | replaceChars(String str, char searchChar, char replaceChar) Replaces all occurrences of a character in a String with another. |
static String | replaceChars(String str, String searchChars, String replaceChars) Replaces multiple characters in a String in one go. |
static String | replaceOnce(String text, String repl, String with) Replaces a String with another String inside a larger String, once. A StringUtils.replaceOnce(null, *, *) = null StringUtils.replaceOnce("", *, *) = "" StringUtils.replaceOnce("any", null, *) = "any" StringUtils.replaceOnce("any", *, null) = "any" StringUtils.replaceOnce("any", "", *) = "any" StringUtils.replaceOnce("aba", "a", null) = "aba" StringUtils.replaceOnce("aba", "a", "") = "ba" StringUtils.replaceOnce("aba", "a", "z") = "zba" |
static String | reverse(String str) Reverses a String as per StringBuffer#reverse(). A StringUtils.reverse(null) = null StringUtils.reverse("") = "" StringUtils.reverse("bat") = "tab" |
static String | reverseDelimited(String str, char separatorChar) Reverses a String that is delimited by a specific character. The Strings between the delimiters are not reversed. |
static String | reverseDelimitedString(String str, String separatorChars) Reverses a String that is delimited by a specific character. The Strings between the delimiters are not reversed. |
static String | right(String str, int len) Gets the rightmost If |
static String | rightPad(String str, int size) Right pad a String with spaces (' '). The String is padded to the size of StringUtils.rightPad(null, *) = null StringUtils.rightPad("", 3) = " " StringUtils.rightPad("bat", 3) = "bat" StringUtils.rightPad("bat", 5) = "bat " StringUtils.rightPad("bat", 1) = "bat" StringUtils.rightPad("bat", -1) = "bat" |
static String | rightPad(String str, int size, char padChar) Right pad a String with a specified character. The String is padded to the size of StringUtils.rightPad(null, *, *) = null StringUtils.rightPad("", 3, 'z') = "zzz" StringUtils.rightPad("bat", 3, 'z') = "bat" StringUtils.rightPad("bat", 5, 'z') = "batzz" StringUtils.rightPad("bat", 1, 'z') = "bat" StringUtils.rightPad("bat", -1, 'z') = "bat" |
static String | rightPad(String str, int size, String padStr) Right pad a String with a specified String. The String is padded to the size of StringUtils.rightPad(null, *, *) = null StringUtils.rightPad("", 3, "z") = "zzz" StringUtils.rightPad("bat", 3, "yz") = "bat" StringUtils.rightPad("bat", 5, "yz") = "batyz" StringUtils.rightPad("bat", 8, "yz") = "batyzyzy" StringUtils.rightPad("bat", 1, "yz") = "bat" StringUtils.rightPad("bat", -1, "yz") = "bat" StringUtils.rightPad("bat", 5, null) = "bat " StringUtils.rightPad("bat", 5, "") = "bat " |
static String[] | split(String str) Splits the provided text into an array, using whitespace as the separator. |
static String[] | split(String str, char separatorChar) Splits the provided text into an array, separator specified. |
static String[] | split(String str, String separatorChars) Splits the provided text into an array, separators specified. |
static String[] | split(String str, String separatorChars, int max) Splits the provided text into an array with a maximum length, separators specified. The separator is not included in the returned String array. |
static String[] | splitByWholeSeparator(String str, String separator) Splits the provided text into an array, separator string specified. The separator(s) will not be included in the returned String array. |
static String[] | splitByWholeSeparator(String str, String separator, int max) Splits the provided text into an array, separator string specified. |
static String[] | splitPreserveAllTokens(String str) Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators. |
static String[] | splitPreserveAllTokens(String str, char separatorChar) Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators. |
static String[] | splitPreserveAllTokens(String str, String separatorChars) Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators. |
static String[] | splitPreserveAllTokens(String str, String separatorChars, int max) Splits the provided text into an array with a maximum length, separators specified, preserving all tokens, including empty tokens created by adjacent separators. The separator is not included in the returned String array. |
static String | strip(String str) Strips whitespace from the start and end of a String. This is similar to trim but removes whitespace. |
static String | strip(String str, String stripChars) Strips any of a set of characters from the start and end of a String. |
static String[] | stripAll(String[] strs) Strips whitespace from the start and end of every String in an array. |
static String[] | stripAll(String[] strs, String stripChars) Strips any of a set of characters from the start and end of every String in an array. Whitespace is defined by Character#isWhitespace(char).A new array is returned each time, except for length zero. |
static String | stripEnd(String str, String stripChars) Strips any of a set of characters from the end of a String. A |
static String | stripStart(String str, String stripChars) Strips any of a set of characters from the start of a String. A |
static String | stripToEmpty(String str) Strips whitespace from the start and end of a String returning
an empty String if This is similar to trimToEmpty but removes whitespace. |
static String | stripToNull(String str) Strips whitespace from the start and end of a String returning
This is similar to trimToNull but removes whitespace. |
static String | substring(String str, int start) Gets a substring from the specified String avoiding exceptions. A negative start position can be used to start A |
static String | substring(String str, int start, int end) Gets a substring from the specified String avoiding exceptions. A negative start position can be used to start/end The returned substring starts with the character in the |
static String | substringAfter(String str, String separator) Gets the substring after the first occurrence of a separator. |
static String | substringAfterLast(String str, String separator) Gets the substring after the last occurrence of a separator. |
static String | substringBefore(String str, String separator) Gets the substring before the first occurrence of a separator. |
static String | substringBeforeLast(String str, String separator) Gets the substring before the last occurrence of a separator. |
static String | substringBetween(String str, String tag) Gets the String that is nested in between two instances of the same String. A |
static String | substringBetween(String str, String open, String close) Gets the String that is nested in between two Strings. |
static String[] | substringsBetween(String str, String open, String close) Searches a String for substrings delimited by a start and end tag, returning all matching substrings in an array. A |
static String | swapCase(String str) Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
For a word based algorithm, see swapCase. |
static String | trim(String str) Removes control characters (char <= 32) from both
ends of this String, handling The String is trimmed using String#trim(). |
static String | trimToEmpty(String str) Removes control characters (char <= 32) from both
ends of this String returning an empty String ("") if the String
is empty ("") after the trim or if it is |
static String | trimToNull(String str) Removes control characters (char <= 32) from both
ends of this String returning |
static String | uncapitalise(String str) Uncapitalizes a String changing the first letter to title case as per Character#toLowerCase(char). |
static String | uncapitalize(String str) Uncapitalizes a String changing the first letter to title case as per Character#toLowerCase(char). |
static String | upperCase(String str) Converts a String to upper case as per String#toUpperCase(). A StringUtils.upperCase(null) = null StringUtils.upperCase("") = "" StringUtils.upperCase("aBc") = "ABC" |
""
.Since: 2.0
Since: 2.1
StringUtils
instances should NOT be constructed in
standard programming. Instead, the class should be used as
StringUtils.trim(" foo ");
.
This constructor is public to permit tools that require a JavaBean instance to operate.
Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "Now is the time for..."
Specifically:
str
is less than maxWidth
characters
long, return it.(substring(str, 0, max-3) + "...")
.maxWidth
is less than 4
, throw an
IllegalArgumentException
.maxWidth
.StringUtils.abbreviate(null, *) = null StringUtils.abbreviate("", 4) = "" StringUtils.abbreviate("abcdefg", 6) = "abc..." StringUtils.abbreviate("abcdefg", 7) = "abcdefg" StringUtils.abbreviate("abcdefg", 8) = "abcdefg" StringUtils.abbreviate("abcdefg", 4) = "a..." StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException
Parameters: str the String to check, may be null maxWidth maximum length of result String, must be at least 4
Returns: abbreviated String, null
if null String input
Throws: IllegalArgumentException if the width is too small
Since: 2.0
Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "...is the time for..."
Works like abbreviate(String, int)
, but allows you to specify
a "left edge" offset. Note that this left edge is not necessarily going to
be the leftmost character in the result, or the first character following the
ellipses, but it will appear somewhere in the result.
In no case will it return a String of length greater than
maxWidth
.
StringUtils.abbreviate(null, *, *) = null StringUtils.abbreviate("", 0, 4) = "" StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 0, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 1, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 4, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 5, 10) = "...fghi..." StringUtils.abbreviate("abcdefghijklmno", 6, 10) = "...ghij..." StringUtils.abbreviate("abcdefghijklmno", 8, 10) = "...ijklmno" StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno" StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno" StringUtils.abbreviate("abcdefghij", 0, 3) = IllegalArgumentException StringUtils.abbreviate("abcdefghij", 5, 6) = IllegalArgumentException
Parameters: str the String to check, may be null offset left edge of source String maxWidth maximum length of result String, must be at least 4
Returns: abbreviated String, null
if null String input
Throws: IllegalArgumentException if the width is too small
Since: 2.0
Deprecated: Use the standardly named capitalize. Method will be removed in Commons Lang 3.0.
Capitalizes a String changing the first letter to title case as per Character#toTitleCase(char). No other letters are changed.
Parameters: str the String to capitalize, may be null
Returns: the capitalized String, null
if null String input
Deprecated: Use the relocated capitalize. Method will be removed in Commons Lang 3.0.
Capitalizes all the whitespace separated words in a String. Only the first letter of each word is changed.
Whitespace is defined by Character#isWhitespace(char).
A null
input String returns null
.
Parameters: str the String to capitalize, may be null
Returns: capitalized String, null
if null String input
Capitalizes a String changing the first letter to title case as per Character#toTitleCase(char). No other letters are changed.
For a word based algorithm, see capitalize.
A null
input String returns null
.
StringUtils.capitalize(null) = null StringUtils.capitalize("") = "" StringUtils.capitalize("cat") = "Cat" StringUtils.capitalize("cAt") = "CAt"
Parameters: str the String to capitalize, may be null
Returns: the capitalized String, null
if null String input
Since: 2.0
See Also: capitalize uncapitalize
Centers a String in a larger String of size size
using the space character (' ').
If the size is less than the String length, the String is returned.
A null
String returns null
.
A negative size is treated as zero.
Equivalent to center(str, size, " ")
.
StringUtils.center(null, *) = null StringUtils.center("", 4) = " " StringUtils.center("ab", -1) = "ab" StringUtils.center("ab", 4) = " ab " StringUtils.center("abcd", 2) = "abcd" StringUtils.center("a", 4) = " a "
Parameters: str the String to center, may be null size the int size of new String, negative treated as zero
Returns: centered String, null
if null String input
Centers a String in a larger String of size size
.
Uses a supplied character as the value to pad the String with.
If the size is less than the String length, the String is returned.
A null
String returns null
.
A negative size is treated as zero.
StringUtils.center(null, *, *) = null StringUtils.center("", 4, ' ') = " " StringUtils.center("ab", -1, ' ') = "ab" StringUtils.center("ab", 4, ' ') = " ab" StringUtils.center("abcd", 2, ' ') = "abcd" StringUtils.center("a", 4, ' ') = " a " StringUtils.center("a", 4, 'y') = "yayy"
Parameters: str the String to center, may be null size the int size of new String, negative treated as zero padChar the character to pad the new String with
Returns: centered String, null
if null String input
Since: 2.0
Centers a String in a larger String of size size
.
Uses a supplied String as the value to pad the String with.
If the size is less than the String length, the String is returned.
A null
String returns null
.
A negative size is treated as zero.
StringUtils.center(null, *, *) = null StringUtils.center("", 4, " ") = " " StringUtils.center("ab", -1, " ") = "ab" StringUtils.center("ab", 4, " ") = " ab" StringUtils.center("abcd", 2, " ") = "abcd" StringUtils.center("a", 4, " ") = " a " StringUtils.center("a", 4, "yz") = "yayz" StringUtils.center("abc", 7, null) = " abc " StringUtils.center("abc", 7, "") = " abc "
Parameters: str the String to center, may be null size the int size of new String, negative treated as zero padStr the String to pad the new String with, must not be null or empty
Returns: centered String, null
if null String input
Throws: IllegalArgumentException if padStr is null
or empty
Removes one newline from end of a String if it's there,
otherwise leave it alone. A newline is "\n
",
"\r
", or "\r\n
".
NOTE: This method changed in 2.0. It now more closely matches Perl chomp.
StringUtils.chomp(null) = null StringUtils.chomp("") = "" StringUtils.chomp("abc \r") = "abc " StringUtils.chomp("abc\n") = "abc" StringUtils.chomp("abc\r\n") = "abc" StringUtils.chomp("abc\r\n\r\n") = "abc\r\n" StringUtils.chomp("abc\n\r") = "abc\n" StringUtils.chomp("abc\n\rabc") = "abc\n\rabc" StringUtils.chomp("\r") = "" StringUtils.chomp("\n") = "" StringUtils.chomp("\r\n") = ""
Parameters: str the String to chomp a newline from, may be null
Returns: String without newline, null
if null String input
Removes separator
from the end of
str
if it's there, otherwise leave it alone.
NOTE: This method changed in version 2.0. It now more closely matches Perl chomp. For the previous behavior, use StringUtils. This method uses String#endsWith(String).
StringUtils.chomp(null, *) = null StringUtils.chomp("", *) = "" StringUtils.chomp("foobar", "bar") = "foo" StringUtils.chomp("foobar", "baz") = "foobar" StringUtils.chomp("foo", "foo") = "" StringUtils.chomp("foo ", "foo") = "foo " StringUtils.chomp(" foo", "foo") = " " StringUtils.chomp("foo", "foooo") = "foo" StringUtils.chomp("foo", "") = "foo" StringUtils.chomp("foo", null) = "foo"
Parameters: str the String to chomp from, may be null separator separator String, may be null
Returns: String without trailing separator, null
if null String input
Deprecated: Use chomp instead. Method will be removed in Commons Lang 3.0.
Remove any "\n" if and only if it is at the end of the supplied String.
Parameters: str the String to chomp from, must not be null
Returns: String without chomped ending
Throws: NullPointerException if str is null
Deprecated: Use chomp instead. Method will be removed in Commons Lang 3.0.
Remove a value if and only if the String ends with that value.
Parameters: str the String to chomp from, must not be null sep the String to chomp, must not be null
Returns: String without chomped ending
Throws: NullPointerException if str or sep is null
Remove the last character from a String.
If the String ends in \r\n
, then remove both
of them.
StringUtils.chop(null) = null StringUtils.chop("") = "" StringUtils.chop("abc \r") = "abc " StringUtils.chop("abc\n") = "abc" StringUtils.chop("abc\r\n") = "abc" StringUtils.chop("abc") = "ab" StringUtils.chop("abc\nabc") = "abc\nab" StringUtils.chop("a") = "" StringUtils.chop("\r") = "" StringUtils.chop("\n") = "" StringUtils.chop("\r\n") = ""
Parameters: str the String to chop last character from, may be null
Returns: String without last character, null
if null String input
Deprecated: Use chomp instead. Method will be removed in Commons Lang 3.0.
Removes \n
from end of a String if it's there.
If a \r
precedes it, then remove that too.
Parameters: str the String to chop a newline from, must not be null
Returns: String without newline
Throws: NullPointerException if str is null
Deprecated: Use the clearer named trimToEmpty. Method will be removed in Commons Lang 3.0.
Removes control characters (char <= 32) from both
ends of this String, handling null
by returning
an empty String ("").
StringUtils.clean(null) = "" StringUtils.clean("") = "" StringUtils.clean("abc") = "abc" StringUtils.clean(" abc ") = "abc" StringUtils.clean(" ") = ""
Parameters: str the String to clean, may be null
Returns: the trimmed text, never null
See Also: java.lang.String#trim()
Deprecated: Use the better named (Object[])
instead.
Method will be removed in Commons Lang 3.0.
Concatenates elements of an array into a single String. Null objects or empty strings within the array are represented by empty strings.
StringUtils.concatenate(null) = null StringUtils.concatenate([]) = "" StringUtils.concatenate([null]) = "" StringUtils.concatenate(["a", "b", "c"]) = "abc" StringUtils.concatenate([null, "", "a"]) = "a"
Parameters: array the array of values to concatenate, may be null
Returns: the concatenated String, null
if null array input
Checks if String contains a search character, handling null
.
This method uses String#indexOf(int).
A null
or empty ("") String will return false
.
StringUtils.contains(null, *) = false StringUtils.contains("", *) = false StringUtils.contains("abc", 'a') = true StringUtils.contains("abc", 'z') = false
Parameters: str the String to check, may be null searchChar the character to find
Returns: true if the String contains the search character,
false if not or null
string input
Since: 2.0
Checks if String contains a search String, handling null
.
This method uses String#indexOf(String).
A null
String will return false
.
StringUtils.contains(null, *) = false StringUtils.contains(*, null) = false StringUtils.contains("", "") = true StringUtils.contains("abc", "") = true StringUtils.contains("abc", "a") = true StringUtils.contains("abc", "z") = false
Parameters: str the String to check, may be null searchStr the String to find, may be null
Returns: true if the String contains the search String,
false if not or null
string input
Since: 2.0
Checks if String contains a search String irrespective of case,
handling null
. This method uses
StringUtils.
A null
String will return false
.
StringUtils.contains(null, *) = false StringUtils.contains(*, null) = false StringUtils.contains("", "") = true StringUtils.contains("abc", "") = true StringUtils.contains("abc", "a") = true StringUtils.contains("abc", "z") = false StringUtils.contains("abc", "A") = true StringUtils.contains("abc", "Z") = false
Parameters: str the String to check, may be null searchStr the String to find, may be null
Returns: true if the String contains the search String irrespective of
case or false if not or null
string input
Checks that the String does not contain certain characters.
A null
String will return true
.
A null
invalid character array will return true
.
An empty String ("") always returns true.
StringUtils.containsNone(null, *) = true StringUtils.containsNone(*, null) = true StringUtils.containsNone("", *) = true StringUtils.containsNone("ab", '') = true StringUtils.containsNone("abab", 'xyz') = true StringUtils.containsNone("ab1", 'xyz') = true StringUtils.containsNone("abz", 'xyz') = false
Parameters: str the String to check, may be null invalidChars an array of invalid chars, may be null
Returns: true if it contains none of the invalid chars, or is null
Since: 2.0
Checks that the String does not contain certain characters.
A null
String will return true
.
A null
invalid character array will return true
.
An empty String ("") always returns true.
StringUtils.containsNone(null, *) = true StringUtils.containsNone(*, null) = true StringUtils.containsNone("", *) = true StringUtils.containsNone("ab", "") = true StringUtils.containsNone("abab", "xyz") = true StringUtils.containsNone("ab1", "xyz") = true StringUtils.containsNone("abz", "xyz") = false
Parameters: str the String to check, may be null invalidChars a String of invalid chars, may be null
Returns: true if it contains none of the invalid chars, or is null
Since: 2.0
Checks if the String contains only certain characters.
A null
String will return false
.
A null
valid character array will return false
.
An empty String ("") always returns true
.
StringUtils.containsOnly(null, *) = false StringUtils.containsOnly(*, null) = false StringUtils.containsOnly("", *) = true StringUtils.containsOnly("ab", '') = false StringUtils.containsOnly("abab", 'abc') = true StringUtils.containsOnly("ab1", 'abc') = false StringUtils.containsOnly("abz", 'abc') = false
Parameters: str the String to check, may be null valid an array of valid chars, may be null
Returns: true if it only contains valid chars and is non-null
Checks if the String contains only certain characters.
A null
String will return false
.
A null
valid character String will return false
.
An empty String ("") always returns true
.
StringUtils.containsOnly(null, *) = false StringUtils.containsOnly(*, null) = false StringUtils.containsOnly("", *) = true StringUtils.containsOnly("ab", "") = false StringUtils.containsOnly("abab", "abc") = true StringUtils.containsOnly("ab1", "abc") = false StringUtils.containsOnly("abz", "abc") = false
Parameters: str the String to check, may be null validChars a String of valid chars, may be null
Returns: true if it only contains valid chars and is non-null
Since: 2.0
Counts how many times the substring appears in the larger String.
A null
or empty ("") String input returns 0
.
StringUtils.countMatches(null, *) = 0 StringUtils.countMatches("", *) = 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
Parameters: str the String to check, may be null sub the substring to count, may be null
Returns: the number of occurrences, 0 if either String is null
Returns either the passed in String, or if the String is
empty or null
, the value of defaultStr
.
StringUtils.defaultIfEmpty(null, "NULL") = "NULL" StringUtils.defaultIfEmpty("", "NULL") = "NULL" StringUtils.defaultIfEmpty("bat", "NULL") = "bat"
Parameters: str the String to check, may be null defaultStr the default String to return
if the input is empty ("") or null
, may be null
Returns: the passed in String, or the default
See Also: StringUtils
Returns either the passed in String,
or if the String is null
, an empty String ("").
StringUtils.defaultString(null) = "" StringUtils.defaultString("") = "" StringUtils.defaultString("bat") = "bat"
Parameters: str the String to check, may be null
Returns: the passed in String, or the empty String if it
was null
See Also: toString String#valueOf(Object)
Returns either the passed in String, or if the String is
null
, the value of defaultStr
.
StringUtils.defaultString(null, "NULL") = "NULL" StringUtils.defaultString("", "NULL") = "" StringUtils.defaultString("bat", "NULL") = "bat"
Parameters: str the String to check, may be null defaultStr the default String to return
if the input is null
, may be null
Returns: the passed in String, or the default if it was null
See Also: toString String#valueOf(Object)
Deprecated: Use the better localized deleteWhitespace. Method will be removed in Commons Lang 3.0.
Deletes all 'space' characters from a String as defined by Character#isSpace(char).
This is the only StringUtils method that uses the
isSpace
definition. You are advised to use
deleteWhitespace instead as whitespace is much
better localized.
StringUtils.deleteSpaces(null) = null StringUtils.deleteSpaces("") = "" StringUtils.deleteSpaces("abc") = "abc" StringUtils.deleteSpaces(" \t abc \n ") = "abc" StringUtils.deleteSpaces("ab c") = "abc" StringUtils.deleteSpaces("a\nb\tc ") = "abc"
Spaces are defined as {' ', '\t', '\r', '\n', '\b'}
in line with the deprecated isSpace
method.
Parameters: str the String to delete spaces from, may be null
Returns: the String without 'spaces', null
if null String input
Deletes all whitespaces from a String as defined by Character#isWhitespace(char).
StringUtils.deleteWhitespace(null) = null StringUtils.deleteWhitespace("") = "" StringUtils.deleteWhitespace("abc") = "abc" StringUtils.deleteWhitespace(" ab c ") = "abc"
Parameters: str the String to delete whitespace from, may be null
Returns: the String without whitespaces, null
if null String input
Compares two Strings, and returns the portion where they differ. (More precisely, return the remainder of the second String, starting from where it's different from the first.)
For example,
difference("i am a machine", "i am a robot") -> "robot"
.
StringUtils.difference(null, null) = null StringUtils.difference("", "") = "" StringUtils.difference("", "abc") = "abc" StringUtils.difference("abc", "") = "" StringUtils.difference("abc", "abc") = "" StringUtils.difference("ab", "abxyz") = "xyz" StringUtils.difference("abcde", "abxyz") = "xyz" StringUtils.difference("abcde", "xyz") = "xyz"
Parameters: str1 the first String, may be null str2 the second String, may be null
Returns: the portion of str2 where it differs from str1; returns the empty String if they are equal
Since: 2.0
Compares two Strings, returning true
if they are equal.
null
s are handled without exceptions. Two null
references are considered to be equal. The comparison is case sensitive.
StringUtils.equals(null, null) = true StringUtils.equals(null, "abc") = false StringUtils.equals("abc", null) = false StringUtils.equals("abc", "abc") = true StringUtils.equals("abc", "ABC") = false
Parameters: str1 the first String, may be null str2 the second String, may be null
Returns: true
if the Strings are equal, case sensitive, or
both null
See Also: java.lang.String#equals(Object)
Compares two Strings, returning true
if they are equal ignoring
the case.
null
s are handled without exceptions. Two null
references are considered equal. Comparison is case insensitive.
StringUtils.equalsIgnoreCase(null, null) = true StringUtils.equalsIgnoreCase(null, "abc") = false StringUtils.equalsIgnoreCase("abc", null) = false StringUtils.equalsIgnoreCase("abc", "abc") = true StringUtils.equalsIgnoreCase("abc", "ABC") = true
Parameters: str1 the first String, may be null str2 the second String, may be null
Returns: true
if the Strings are equal, case insensitive, or
both null
See Also: java.lang.String#equalsIgnoreCase(String)
Deprecated: Use escapeJava This method will be removed in Commons Lang 3.0
Escapes any values it finds into their String form.
So a tab becomes the characters '\\'
and
't'
.
As of Lang 2.0, this calls escapeJava behind the scenes.
Parameters: str String to escape values in
Returns: String with escaped values
Throws: NullPointerException if str is null
See Also: StringEscapeUtils
Deprecated: Use StringUtils instead (although this doesn't include the separator) Method will be removed in Commons Lang 3.0.
Remove everything and return the last value of a supplied String, and everything after it from a String.
Parameters: str the String to chomp from, must not be null sep the String to chomp, must not be null
Returns: String chomped
Throws: NullPointerException if str or sep is null
Find the Levenshtein distance between two Strings.
This is the number of changes needed to change one String into another, where each change is a single character modification (deletion, insertion or substitution).
The previous implementation of the Levenshtein distance algorithm was from http://www.merriampark.com/ld.htm
Chas Emerick has written an implementation in Java, which avoids an OutOfMemoryError
which can occur when my Java implementation is used with very large strings.
This implementation of the Levenshtein distance algorithm
is from http://www.merriampark.com/ldjava.htm
StringUtils.getLevenshteinDistance(null, *) = IllegalArgumentException StringUtils.getLevenshteinDistance(*, null) = IllegalArgumentException StringUtils.getLevenshteinDistance("","") = 0 StringUtils.getLevenshteinDistance("","a") = 1 StringUtils.getLevenshteinDistance("aaapppp", "") = 7 StringUtils.getLevenshteinDistance("frog", "fog") = 1 StringUtils.getLevenshteinDistance("fly", "ant") = 3 StringUtils.getLevenshteinDistance("elephant", "hippo") = 7 StringUtils.getLevenshteinDistance("hippo", "elephant") = 7 StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8 StringUtils.getLevenshteinDistance("hello", "hallo") = 1
Parameters: s the first String, must not be null t the second String, must not be null
Returns: result distance
Throws: IllegalArgumentException if either String input null
Deprecated: Use the better named StringUtils. Method will be removed in Commons Lang 3.0.
Gets the String that is nested in between two instances of the same String.
A null
input String returns null
.
A null
tag returns null
.
StringUtils.getNestedString(null, *) = null StringUtils.getNestedString("", "") = "" StringUtils.getNestedString("", "tag") = null StringUtils.getNestedString("tagabctag", null) = null StringUtils.getNestedString("tagabctag", "") = "" StringUtils.getNestedString("tagabctag", "tag") = "abc"
Parameters: str the String containing nested-string, may be null tag the String before and after nested-string, may be null
Returns: the nested String, null
if no match
Deprecated: Use the better named StringUtils. Method will be removed in Commons Lang 3.0.
Gets the String that is nested in between two Strings. Only the first match is returned.
A null
input String returns null
.
A null
open/close returns null
(no match).
An empty ("") open/close returns an empty string.
StringUtils.getNestedString(null, *, *) = 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" StringUtils.getNestedString("yabczyabcz", "y", "z") = "abc"
Parameters: str the String containing nested-string, may be null open the String before nested-string, may be null close the String after nested-string, may be null
Returns: the nested String, null
if no match
Deprecated: Use substringBefore instead (although this doesn't include the separator). Method will be removed in Commons Lang 3.0.
Remove and return everything before the first value of a supplied String from another String.
Parameters: str the String to chomp from, must not be null sep the String to chomp, must not be null
Returns: String prechomped
Throws: NullPointerException if str or sep is null
Finds the first index within a String, handling null
.
This method uses String#indexOf(int).
A null
or empty ("") String will return -1
.
StringUtils.indexOf(null, *) = -1 StringUtils.indexOf("", *) = -1 StringUtils.indexOf("aabaabaa", 'a') = 0 StringUtils.indexOf("aabaabaa", 'b') = 2
Parameters: str the String to check, may be null searchChar the character to find
Returns: the first index of the search character,
-1 if no match or null
string input
Since: 2.0
Finds the first index within a String from a start position,
handling null
.
This method uses String#indexOf(int, int).
A null
or empty ("") String will return -1
.
A negative start position is treated as zero.
A start position greater than the string length returns -1
.
StringUtils.indexOf(null, *, *) = -1 StringUtils.indexOf("", *, *) = -1 StringUtils.indexOf("aabaabaa", 'b', 0) = 2 StringUtils.indexOf("aabaabaa", 'b', 3) = 5 StringUtils.indexOf("aabaabaa", 'b', 9) = -1 StringUtils.indexOf("aabaabaa", 'b', -1) = 2
Parameters: str the String to check, may be null searchChar the character to find startPos the start position, negative treated as zero
Returns: the first index of the search character,
-1 if no match or null
string input
Since: 2.0
Finds the first index within a String, handling null
.
This method uses String#indexOf(String).
A null
String will return -1
.
StringUtils.indexOf(null, *) = -1 StringUtils.indexOf(*, null) = -1 StringUtils.indexOf("", "") = 0 StringUtils.indexOf("aabaabaa", "a") = 0 StringUtils.indexOf("aabaabaa", "b") = 2 StringUtils.indexOf("aabaabaa", "ab") = 1 StringUtils.indexOf("aabaabaa", "") = 0
Parameters: str the String to check, may be null searchStr the String to find, may be null
Returns: the first index of the search String,
-1 if no match or null
string input
Since: 2.0
Finds the first index within a String, handling null
.
This method uses String#indexOf(String, int).
A null
String will return -1
.
A negative start position is treated as zero.
An empty ("") search String always matches.
A start position greater than the string length only matches
an empty search String.
StringUtils.indexOf(null, *, *) = -1 StringUtils.indexOf(*, null, *) = -1 StringUtils.indexOf("", "", 0) = 0 StringUtils.indexOf("aabaabaa", "a", 0) = 0 StringUtils.indexOf("aabaabaa", "b", 0) = 2 StringUtils.indexOf("aabaabaa", "ab", 0) = 1 StringUtils.indexOf("aabaabaa", "b", 3) = 5 StringUtils.indexOf("aabaabaa", "b", 9) = -1 StringUtils.indexOf("aabaabaa", "b", -1) = 2 StringUtils.indexOf("aabaabaa", "", 2) = 2 StringUtils.indexOf("abc", "", 9) = 3
Parameters: str the String to check, may be null searchStr the String to find, may be null startPos the start position, negative treated as zero
Returns: the first index of the search String,
-1 if no match or null
string input
Since: 2.0
Search a String to find the first index of any character in the given set of characters.
A null
String will return -1
.
A null
or zero length search array will return -1
.
StringUtils.indexOfAny(null, *) = -1 StringUtils.indexOfAny("", *) = -1 StringUtils.indexOfAny(*, null) = -1 StringUtils.indexOfAny(*, []) = -1 StringUtils.indexOfAny("zzabyycdxx",['z','a']) = 0 StringUtils.indexOfAny("zzabyycdxx",['b','y']) = 3 StringUtils.indexOfAny("aba", ['z']) = -1
Parameters: str the String to check, may be null searchChars the chars to search for, may be null
Returns: the index of any of the chars, -1 if no match or null input
Since: 2.0
Search a String to find the first index of any character in the given set of characters.
A null
String will return -1
.
A null
search string will return -1
.
StringUtils.indexOfAny(null, *) = -1 StringUtils.indexOfAny("", *) = -1 StringUtils.indexOfAny(*, null) = -1 StringUtils.indexOfAny(*, "") = -1 StringUtils.indexOfAny("zzabyycdxx", "za") = 0 StringUtils.indexOfAny("zzabyycdxx", "by") = 3 StringUtils.indexOfAny("aba","z") = -1
Parameters: str the String to check, may be null searchChars the chars to search for, may be null
Returns: the index of any of the chars, -1 if no match or null input
Since: 2.0
Find the first index of any of a set of potential substrings.
A null
String will return -1
.
A null
or zero length search array will return -1
.
A null
search array entry will be ignored, but a search
array containing "" will return 0
if str
is not
null. This method uses String#indexOf(String).
StringUtils.indexOfAny(null, *) = -1 StringUtils.indexOfAny(*, null) = -1 StringUtils.indexOfAny(*, []) = -1 StringUtils.indexOfAny("zzabyycdxx", ["ab","cd"]) = 2 StringUtils.indexOfAny("zzabyycdxx", ["cd","ab"]) = 2 StringUtils.indexOfAny("zzabyycdxx", ["mn","op"]) = -1 StringUtils.indexOfAny("zzabyycdxx", ["zab","aby"]) = 1 StringUtils.indexOfAny("zzabyycdxx", [""]) = 0 StringUtils.indexOfAny("", [""]) = 0 StringUtils.indexOfAny("", ["a"]) = -1
Parameters: str the String to check, may be null searchStrs the Strings to search for, may be null
Returns: the first index of any of the searchStrs in str, -1 if no match
Search a String to find the first index of any character not in the given set of characters.
A null
String will return -1
.
A null
or zero length search array will return -1
.
StringUtils.indexOfAnyBut(null, *) = -1 StringUtils.indexOfAnyBut("", *) = -1 StringUtils.indexOfAnyBut(*, null) = -1 StringUtils.indexOfAnyBut(*, []) = -1 StringUtils.indexOfAnyBut("zzabyycdxx",'za') = 3 StringUtils.indexOfAnyBut("zzabyycdxx", '') = 0 StringUtils.indexOfAnyBut("aba", 'ab') = -1
Parameters: str the String to check, may be null searchChars the chars to search for, may be null
Returns: the index of any of the chars, -1 if no match or null input
Since: 2.0
Search a String to find the first index of any character not in the given set of characters.
A null
String will return -1
.
A null
search string will return -1
.
StringUtils.indexOfAnyBut(null, *) = -1 StringUtils.indexOfAnyBut("", *) = -1 StringUtils.indexOfAnyBut(*, null) = -1 StringUtils.indexOfAnyBut(*, "") = -1 StringUtils.indexOfAnyBut("zzabyycdxx", "za") = 3 StringUtils.indexOfAnyBut("zzabyycdxx", "") = 0 StringUtils.indexOfAnyBut("aba","ab") = -1
Parameters: str the String to check, may be null searchChars the chars to search for, may be null
Returns: the index of any of the chars, -1 if no match or null input
Since: 2.0
Compares two Strings, and returns the index at which the Strings begin to differ.
For example,
indexOfDifference("i am a machine", "i am a robot") -> 7
StringUtils.indexOfDifference(null, null) = -1 StringUtils.indexOfDifference("", "") = -1 StringUtils.indexOfDifference("", "abc") = 0 StringUtils.indexOfDifference("abc", "") = 0 StringUtils.indexOfDifference("abc", "abc") = -1 StringUtils.indexOfDifference("ab", "abxyz") = 2 StringUtils.indexOfDifference("abcde", "abxyz") = 2 StringUtils.indexOfDifference("abcde", "xyz") = 0
Parameters: str1 the first String, may be null str2 the second String, may be null
Returns: the index where str2 and str1 begin to differ; -1 if they are equal
Since: 2.0
Checks if the String contains only unicode letters.
null
will return false
.
An empty String ("") will return true
.
StringUtils.isAlpha(null) = false StringUtils.isAlpha("") = true StringUtils.isAlpha(" ") = false StringUtils.isAlpha("abc") = true StringUtils.isAlpha("ab2c") = false StringUtils.isAlpha("ab-c") = false
Parameters: str the String to check, may be null
Returns: true
if only contains letters, and is non-null
Checks if the String contains only unicode letters or digits.
null
will return false
.
An empty String ("") will return true
.
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
Parameters: str the String to check, may be null
Returns: true
if only contains letters or digits,
and is non-null
Checks if the String contains only unicode letters, digits
or space (' '
).
null
will return false
.
An empty String ("") will return true
.
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
Parameters: str the String to check, may be null
Returns: true
if only contains letters, digits or space,
and is non-null
Checks if the String contains only unicode letters and space (' ').
null
will return false
An empty String ("") will return true
.
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
Parameters: str the String to check, may be null
Returns: true
if only contains letters and space,
and is non-null
Checks if the string contains only ASCII printable characters.
null
will return false
.
An empty String ("") will return true
.
StringUtils.isAsciiPrintable(null) = false StringUtils.isAsciiPrintable("") = true StringUtils.isAsciiPrintable(" ") = true StringUtils.isAsciiPrintable("Ceki") = true StringUtils.isAsciiPrintable("ab2c") = true StringUtils.isAsciiPrintable("!ab-c~") = true StringUtils.isAsciiPrintable(" ") = true StringUtils.isAsciiPrintable("!") = true StringUtils.isAsciiPrintable("~") = true StringUtils.isAsciiPrintable("") = false StringUtils.isAsciiPrintable("Ceki Gülcü") = false
Parameters: str the string to check, may be null
Returns: true
if every character is in the range
32 thru 126
Since: 2.1
Checks if a String is whitespace, empty ("") or null.
StringUtils.isBlank(null) = true StringUtils.isBlank("") = true StringUtils.isBlank(" ") = true StringUtils.isBlank("bob") = false StringUtils.isBlank(" bob ") = false
Parameters: str the String to check, may be null
Returns: true
if the String is null, empty or whitespace
Since: 2.0
Checks if a String is empty ("") or null.
StringUtils.isEmpty(null) = true StringUtils.isEmpty("") = true StringUtils.isEmpty(" ") = false StringUtils.isEmpty("bob") = false StringUtils.isEmpty(" bob ") = false
NOTE: This method changed in Lang version 2.0. It no longer trims the String. That functionality is available in isBlank().
Parameters: str the String to check, may be null
Returns: true
if the String is empty or null
Checks if a String is not empty (""), not null and not whitespace only.
StringUtils.isNotBlank(null) = false StringUtils.isNotBlank("") = false StringUtils.isNotBlank(" ") = false StringUtils.isNotBlank("bob") = true StringUtils.isNotBlank(" bob ") = true
Parameters: str the String to check, may be null
Returns: true
if the String is
not empty and not null and not whitespace
Since: 2.0
Checks if a String is not empty ("") and not null.
StringUtils.isNotEmpty(null) = false StringUtils.isNotEmpty("") = false StringUtils.isNotEmpty(" ") = true StringUtils.isNotEmpty("bob") = true StringUtils.isNotEmpty(" bob ") = true
Parameters: str the String to check, may be null
Returns: true
if the String is not empty and not null
Checks if the String contains only unicode digits. A decimal point is not a unicode digit and returns false.
null
will return false
.
An empty String ("") will return true
.
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
Parameters: str the String to check, may be null
Returns: true
if only contains digits, and is non-null
Checks if the String contains only unicode digits or space
(' '
).
A decimal point is not a unicode digit and returns false.
null
will return false
.
An empty String ("") will return true
.
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
Parameters: str the String to check, may be null
Returns: true
if only contains digits or space,
and is non-null
Checks if the String contains only whitespace.
null
will return false
.
An empty String ("") will return true
.
StringUtils.isWhitespace(null) = false StringUtils.isWhitespace("") = true StringUtils.isWhitespace(" ") = true StringUtils.isWhitespace("abc") = false StringUtils.isWhitespace("ab2c") = false StringUtils.isWhitespace("ab-c") = false
Parameters: str the String to check, may be null
Returns: true
if only contains whitespace, and is non-null
Since: 2.0
Joins the elements of the provided array into a single String containing the provided list of elements.
No separator is added to the joined String. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null) = null StringUtils.join([]) = "" StringUtils.join([null]) = "" StringUtils.join(["a", "b", "c"]) = "abc" StringUtils.join([null, "", "a"]) = "a"
Parameters: array the array of values to join together, may be null
Returns: the joined String, null
if null array input
Since: 2.0
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join(["a", "b", "c"], ';') = "a;b;c" StringUtils.join(["a", "b", "c"], null) = "abc" StringUtils.join([null, "", "a"], ';') = ";;a"
Parameters: array the array of values to join together, may be null separator the separator character to use
Returns: the joined String, null
if null array input
Since: 2.0
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join(["a", "b", "c"], ';') = "a;b;c" StringUtils.join(["a", "b", "c"], null) = "abc" StringUtils.join([null, "", "a"], ';') = ";;a"
Parameters: array the array of values to join together, may be null separator the separator character to use startIndex the first index to start joining from. It is an error to pass in an end index past the end of the array endIndex the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array
Returns: the joined String, null
if null array input
Since: 2.0
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list.
A null
separator is the same as an empty String ("").
Null objects or empty strings within the array are represented by
empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join(["a", "b", "c"], "--") = "a--b--c" StringUtils.join(["a", "b", "c"], null) = "abc" StringUtils.join(["a", "b", "c"], "") = "abc" StringUtils.join([null, "", "a"], ',') = ",,a"
Parameters: array the array of values to join together, may be null separator the separator character to use, null treated as ""
Returns: the joined String, null
if null array input
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list.
A null
separator is the same as an empty String ("").
Null objects or empty strings within the array are represented by
empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join(["a", "b", "c"], "--") = "a--b--c" StringUtils.join(["a", "b", "c"], null) = "abc" StringUtils.join(["a", "b", "c"], "") = "abc" StringUtils.join([null, "", "a"], ',') = ",,a"
Parameters: array the array of values to join together, may be null separator the separator character to use, null treated as "" startIndex the first index to start joining from. It is an error to pass in an end index past the end of the array endIndex the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array
Returns: the joined String, null
if null array input
Joins the elements of the provided Iterator
into
a single String containing the provided elements.
No delimiter is added before or after the list. Null objects or empty strings within the iteration are represented by empty strings.
See the examples here: (Object[],char)
.
Parameters: iterator the Iterator
of values to join together, may be null separator the separator character to use
Returns: the joined String, null
if null iterator input
Since: 2.0
Joins the elements of the provided Iterator
into
a single String containing the provided elements.
No delimiter is added before or after the list.
A null
separator is the same as an empty String ("").
See the examples here: (Object[],String)
.
Parameters: iterator the Iterator
of values to join together, may be null separator the separator character to use, null treated as ""
Returns: the joined String, null
if null iterator input
Joins the elements of the provided Collection
into
a single String containing the provided elements.
No delimiter is added before or after the list. Null objects or empty strings within the iteration are represented by empty strings.
See the examples here: (Object[],char)
.
Parameters: collection the Collection
of values to join together, may be null separator the separator character to use
Returns: the joined String, null
if null iterator input
Since: 2.3
Joins the elements of the provided Collection
into
a single String containing the provided elements.
No delimiter is added before or after the list.
A null
separator is the same as an empty String ("").
See the examples here: (Object[],String)
.
Parameters: collection the Collection
of values to join together, may be null separator the separator character to use, null treated as ""
Returns: the joined String, null
if null iterator input
Since: 2.3
Finds the last index within a String, handling null
.
This method uses String#lastIndexOf(int).
A null
or empty ("") String will return -1
.
StringUtils.lastIndexOf(null, *) = -1 StringUtils.lastIndexOf("", *) = -1 StringUtils.lastIndexOf("aabaabaa", 'a') = 7 StringUtils.lastIndexOf("aabaabaa", 'b') = 5
Parameters: str the String to check, may be null searchChar the character to find
Returns: the last index of the search character,
-1 if no match or null
string input
Since: 2.0
Finds the last index within a String from a start position,
handling null
.
This method uses String#lastIndexOf(int, int).
A null
or empty ("") String will return -1
.
A negative start position returns -1
.
A start position greater than the string length searches the whole string.
StringUtils.lastIndexOf(null, *, *) = -1 StringUtils.lastIndexOf("", *, *) = -1 StringUtils.lastIndexOf("aabaabaa", 'b', 8) = 5 StringUtils.lastIndexOf("aabaabaa", 'b', 4) = 2 StringUtils.lastIndexOf("aabaabaa", 'b', 0) = -1 StringUtils.lastIndexOf("aabaabaa", 'b', 9) = 5 StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1 StringUtils.lastIndexOf("aabaabaa", 'a', 0) = 0
Parameters: str the String to check, may be null searchChar the character to find startPos the start position
Returns: the last index of the search character,
-1 if no match or null
string input
Since: 2.0
Finds the last index within a String, handling null
.
This method uses String#lastIndexOf(String).
A null
String will return -1
.
StringUtils.lastIndexOf(null, *) = -1 StringUtils.lastIndexOf(*, null) = -1 StringUtils.lastIndexOf("", "") = 0 StringUtils.lastIndexOf("aabaabaa", "a") = 0 StringUtils.lastIndexOf("aabaabaa", "b") = 2 StringUtils.lastIndexOf("aabaabaa", "ab") = 1 StringUtils.lastIndexOf("aabaabaa", "") = 8
Parameters: str the String to check, may be null searchStr the String to find, may be null
Returns: the last index of the search String,
-1 if no match or null
string input
Since: 2.0
Finds the first index within a String, handling null
.
This method uses String#lastIndexOf(String, int).
A null
String will return -1
.
A negative start position returns -1
.
An empty ("") search String always matches unless the start position is negative.
A start position greater than the string length searches the whole string.
StringUtils.lastIndexOf(null, *, *) = -1 StringUtils.lastIndexOf(*, null, *) = -1 StringUtils.lastIndexOf("aabaabaa", "a", 8) = 7 StringUtils.lastIndexOf("aabaabaa", "b", 8) = 5 StringUtils.lastIndexOf("aabaabaa", "ab", 8) = 4 StringUtils.lastIndexOf("aabaabaa", "b", 9) = 5 StringUtils.lastIndexOf("aabaabaa", "b", -1) = -1 StringUtils.lastIndexOf("aabaabaa", "a", 0) = 0 StringUtils.lastIndexOf("aabaabaa", "b", 0) = -1
Parameters: str the String to check, may be null searchStr the String to find, may be null startPos the start position, negative treated as zero
Returns: the first index of the search String,
-1 if no match or null
string input
Since: 2.0
Find the latest index of any of a set of potential substrings.
A null
String will return -1
.
A null
search array will return -1
.
A null
or zero length search array entry will be ignored,
but a search array containing "" will return the length of str
if str
is not null. This method uses String#indexOf(String)
StringUtils.lastIndexOfAny(null, *) = -1 StringUtils.lastIndexOfAny(*, null) = -1 StringUtils.lastIndexOfAny(*, []) = -1 StringUtils.lastIndexOfAny(*, [null]) = -1 StringUtils.lastIndexOfAny("zzabyycdxx", ["ab","cd"]) = 6 StringUtils.lastIndexOfAny("zzabyycdxx", ["cd","ab"]) = 6 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn",""]) = 10
Parameters: str the String to check, may be null searchStrs the Strings to search for, may be null
Returns: the last index of any of the Strings, -1 if no match
Gets the leftmost len
characters of a String.
If len
characters are not available, or the
String is null
, the String will be returned without
an exception. An exception is thrown if len is negative.
StringUtils.left(null, *) = null StringUtils.left(*, -ve) = "" StringUtils.left("", *) = "" StringUtils.left("abc", 0) = "" StringUtils.left("abc", 2) = "ab" StringUtils.left("abc", 4) = "abc"
Parameters: str the String to get the leftmost characters from, may be null len the length of the required String, must be zero or positive
Returns: the leftmost characters, null
if null String input
Left pad a String with spaces (' ').
The String is padded to the size of size
.
StringUtils.leftPad(null, *) = null StringUtils.leftPad("", 3) = " " StringUtils.leftPad("bat", 3) = "bat" StringUtils.leftPad("bat", 5) = " bat" StringUtils.leftPad("bat", 1) = "bat" StringUtils.leftPad("bat", -1) = "bat"
Parameters: str the String to pad out, may be null size the size to pad to
Returns: left padded String or original String if no padding is necessary,
null
if null String input
Left pad a String with a specified character.
Pad to a size of size
.
StringUtils.leftPad(null, *, *) = null StringUtils.leftPad("", 3, 'z') = "zzz" StringUtils.leftPad("bat", 3, 'z') = "bat" StringUtils.leftPad("bat", 5, 'z') = "zzbat" StringUtils.leftPad("bat", 1, 'z') = "bat" StringUtils.leftPad("bat", -1, 'z') = "bat"
Parameters: str the String to pad out, may be null size the size to pad to padChar the character to pad with
Returns: left padded String or original String if no padding is necessary,
null
if null String input
Since: 2.0
Left pad a String with a specified String.
Pad to a size of size
.
StringUtils.leftPad(null, *, *) = null StringUtils.leftPad("", 3, "z") = "zzz" StringUtils.leftPad("bat", 3, "yz") = "bat" StringUtils.leftPad("bat", 5, "yz") = "yzbat" StringUtils.leftPad("bat", 8, "yz") = "yzyzybat" StringUtils.leftPad("bat", 1, "yz") = "bat" StringUtils.leftPad("bat", -1, "yz") = "bat" StringUtils.leftPad("bat", 5, null) = " bat" StringUtils.leftPad("bat", 5, "") = " bat"
Parameters: str the String to pad out, may be null size the size to pad to padStr the String to pad with, null or empty treated as single space
Returns: left padded String or original String if no padding is necessary,
null
if null String input
Converts a String to lower case as per String#toLowerCase().
A null
input String returns null
.
StringUtils.lowerCase(null) = null StringUtils.lowerCase("") = "" StringUtils.lowerCase("aBc") = "abc"
Parameters: str the String to lower case, may be null
Returns: the lower cased String, null
if null String input
Gets len
characters from the middle of a String.
If len
characters are not available, the remainder
of the String will be returned without an exception. If the
String is null
, null
will be returned.
An exception is thrown if len is negative.
StringUtils.mid(null, *, *) = null StringUtils.mid(*, *, -ve) = "" StringUtils.mid("", 0, *) = "" StringUtils.mid("abc", 0, 2) = "ab" StringUtils.mid("abc", 0, 4) = "abc" StringUtils.mid("abc", 2, 4) = "c" StringUtils.mid("abc", 4, 2) = "" StringUtils.mid("abc", -2, 2) = "ab"
Parameters: str the String to get the characters from, may be null pos the position to start from, negative treated as zero len the length of the required String, must be zero or positive
Returns: the middle characters, null
if null String input
Finds the n-th index within a String, handling null
.
This method uses String#indexOf(String).
A null
String will return -1
.
StringUtils.ordinalIndexOf(null, *, *) = -1 StringUtils.ordinalIndexOf(*, null, *) = -1 StringUtils.ordinalIndexOf("", "", *) = 0 StringUtils.ordinalIndexOf("aabaabaa", "a", 1) = 0 StringUtils.ordinalIndexOf("aabaabaa", "a", 2) = 1 StringUtils.ordinalIndexOf("aabaabaa", "b", 1) = 2 StringUtils.ordinalIndexOf("aabaabaa", "b", 2) = 5 StringUtils.ordinalIndexOf("aabaabaa", "ab", 1) = 1 StringUtils.ordinalIndexOf("aabaabaa", "ab", 2) = 4 StringUtils.ordinalIndexOf("aabaabaa", "", 1) = 0 StringUtils.ordinalIndexOf("aabaabaa", "", 2) = 0
Parameters: str the String to check, may be null searchStr the String to find, may be null ordinal the n-th searchStr
to find
Returns: the n-th index of the search String,
-1
(INDEX_NOT_FOUND
) if no match or null
string input
Since: 2.1
Overlays part of a String with another String.
A null
string input returns null
.
A negative index is treated as zero.
An index greater than the string length is treated as the string length.
The start index is always the smaller of the two indices.
StringUtils.overlay(null, *, *, *) = null StringUtils.overlay("", "abc", 0, 0) = "abc" StringUtils.overlay("abcdef", null, 2, 4) = "abef" StringUtils.overlay("abcdef", "", 2, 4) = "abef" StringUtils.overlay("abcdef", "", 4, 2) = "abef" StringUtils.overlay("abcdef", "zzzz", 2, 4) = "abzzzzef" StringUtils.overlay("abcdef", "zzzz", 4, 2) = "abzzzzef" StringUtils.overlay("abcdef", "zzzz", -1, 4) = "zzzzef" StringUtils.overlay("abcdef", "zzzz", 2, 8) = "abzzzz" StringUtils.overlay("abcdef", "zzzz", -2, -3) = "zzzzabcdef" StringUtils.overlay("abcdef", "zzzz", 8, 10) = "abcdefzzzz"
Parameters: str the String to do overlaying in, may be null overlay the String to overlay, may be null start the position to start overlaying at end the position to stop overlaying before
Returns: overlayed String, null
if null String input
Since: 2.0
Deprecated: Use better named StringUtils instead. Method will be removed in Commons Lang 3.0.
Overlays part of a String with another String.
StringUtils.overlayString(null, *, *, *) = NullPointerException StringUtils.overlayString(*, null, *, *) = NullPointerException 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" StringUtils.overlayString("abcdef", "zzzz", 4, 2) = "abcdzzzzcdef" StringUtils.overlayString("abcdef", "zzzz", -1, 4) = IndexOutOfBoundsException StringUtils.overlayString("abcdef", "zzzz", 2, 8) = IndexOutOfBoundsException
Parameters: text the String to do overlaying in, may be null overlay the String to overlay, may be null start the position to start overlaying at, must be valid end the position to stop overlaying before, must be valid
Returns: overlayed String, null
if null String input
Throws: NullPointerException if text or overlay is null IndexOutOfBoundsException if either position is invalid
Deprecated: Use substringAfter instead. Method will be removed in Commons Lang 3.0.
Remove the first value of a supplied String, and everything before it from a String.
Parameters: str the String to chomp from, must not be null sep the String to chomp, must not be null
Returns: String without chomped beginning
Throws: NullPointerException if str or sep is null
Removes all occurances of a substring from within the source string.
A null
source string will return null
.
An empty ("") source string will return the empty string.
A null
remove string will return the source string.
An empty ("") remove string will return the source string.
StringUtils.remove(null, *) = null StringUtils.remove("", *) = "" StringUtils.remove(*, null) = * StringUtils.remove(*, "") = * StringUtils.remove("queued", "ue") = "qd" StringUtils.remove("queued", "zz") = "queued"
Parameters: str the source String to search, may be null remove the String to search for and remove, may be null
Returns: the substring with the string removed if found,
null
if null String input
Since: 2.1
Removes all occurances of a character from within the source string.
A null
source string will return null
.
An empty ("") source string will return the empty string.
StringUtils.remove(null, *) = null StringUtils.remove("", *) = "" StringUtils.remove("queued", 'u') = "qeed" StringUtils.remove("queued", 'z') = "queued"
Parameters: str the source String to search, may be null remove the char to search for and remove, may be null
Returns: the substring with the char removed if found,
null
if null String input
Since: 2.1
Removes a substring only if it is at the end of a source string, otherwise returns the source string.
A null
source string will return null
.
An empty ("") source string will return the empty string.
A null
search string will return the source string.
StringUtils.removeEnd(null, *) = null StringUtils.removeEnd("", *) = "" StringUtils.removeEnd(*, null) = * StringUtils.removeEnd("www.domain.com", ".com.") = "www.domain.com." StringUtils.removeEnd("www.domain.com", ".com") = "www.domain" StringUtils.removeEnd("www.domain.com", "domain") = "www.domain.com" StringUtils.removeEnd("abc", "") = "abc"
Parameters: str the source String to search, may be null remove the String to search for and remove, may be null
Returns: the substring with the string removed if found,
null
if null String input
Since: 2.1
Removes a substring only if it is at the begining of a source string, otherwise returns the source string.
A null
source string will return null
.
An empty ("") source string will return the empty string.
A null
search string will return the source string.
StringUtils.removeStart(null, *) = null StringUtils.removeStart("", *) = "" StringUtils.removeStart(*, null) = * StringUtils.removeStart("www.domain.com", "www.") = "domain.com" StringUtils.removeStart("domain.com", "www.") = "domain.com" StringUtils.removeStart("www.domain.com", "domain") = "www.domain.com" StringUtils.removeStart("abc", "") = "abc"
Parameters: str the source String to search, may be null remove the String to search for and remove, may be null
Returns: the substring with the string removed if found,
null
if null String input
Since: 2.1
Repeat a String repeat
times to form a
new String.
StringUtils.repeat(null, 2) = null StringUtils.repeat("", 0) = "" StringUtils.repeat("", 2) = "" StringUtils.repeat("a", 3) = "aaa" StringUtils.repeat("ab", 2) = "abab" StringUtils.repeat("a", -2) = ""
Parameters: str the String to repeat, may be null repeat number of times to repeat str, negative treated as zero
Returns: a new String consisting of the original String repeated,
null
if null String input
Replaces all occurrences of a String within another String.
A null
reference passed to this method is a no-op.
StringUtils.replace(null, *, *) = null StringUtils.replace("", *, *) = "" StringUtils.replace("any", null, *) = "any" StringUtils.replace("any", *, null) = "any" StringUtils.replace("any", "", *) = "any" StringUtils.replace("aba", "a", null) = "aba" StringUtils.replace("aba", "a", "") = "b" StringUtils.replace("aba", "a", "z") = "zbz"
Parameters: text text to search and replace in, may be null repl the String to search for, may be null with the String to replace with, may be null
Returns: the text with any replacements processed,
null
if null String input
See Also: StringUtils
Replaces a String with another String inside a larger String,
for the first max
values of the search String.
A null
reference passed to this method is a no-op.
StringUtils.replace(null, *, *, *) = null StringUtils.replace("", *, *, *) = "" StringUtils.replace("any", null, *, *) = "any" StringUtils.replace("any", *, null, *) = "any" StringUtils.replace("any", "", *, *) = "any" StringUtils.replace("any", *, *, 0) = "any" StringUtils.replace("abaa", "a", null, -1) = "abaa" StringUtils.replace("abaa", "a", "", -1) = "b" StringUtils.replace("abaa", "a", "z", 0) = "abaa" StringUtils.replace("abaa", "a", "z", 1) = "zbaa" StringUtils.replace("abaa", "a", "z", 2) = "zbza" StringUtils.replace("abaa", "a", "z", -1) = "zbzz"
Parameters: text text to search and replace in, may be null repl the String to search for, may be null with the String to replace with, may be null max maximum number of values to replace, or -1
if no maximum
Returns: the text with any replacements processed,
null
if null String input
Replaces all occurrences of a character in a String with another. This is a null-safe version of String#replace(char, char).
A null
string input returns null
.
An empty ("") string input returns an empty string.
StringUtils.replaceChars(null, *, *) = null StringUtils.replaceChars("", *, *) = "" StringUtils.replaceChars("abcba", 'b', 'y') = "aycya" StringUtils.replaceChars("abcba", 'z', 'y') = "abcba"
Parameters: str String to replace characters in, may be null searchChar the character to search for, may be null replaceChar the character to replace, may be null
Returns: modified String, null
if null string input
Since: 2.0
Replaces multiple characters in a String in one go. This method can also be used to delete characters.
For example:
replaceChars("hello", "ho", "jy") = jelly
.
A null
string input returns null
.
An empty ("") string input returns an empty string.
A null or empty set of search characters returns the input string.
The length of the search characters should normally equal the length of the replace characters. If the search characters is longer, then the extra search characters are deleted. If the search characters is shorter, then the extra replace characters are ignored.
StringUtils.replaceChars(null, *, *) = null StringUtils.replaceChars("", *, *) = "" StringUtils.replaceChars("abc", null, *) = "abc" StringUtils.replaceChars("abc", "", *) = "abc" StringUtils.replaceChars("abc", "b", null) = "ac" StringUtils.replaceChars("abc", "b", "") = "ac" StringUtils.replaceChars("abcba", "bc", "yz") = "ayzya" StringUtils.replaceChars("abcba", "bc", "y") = "ayya" StringUtils.replaceChars("abcba", "bc", "yzx") = "ayzya"
Parameters: str String to replace characters in, may be null searchChars a set of characters to search for, may be null replaceChars a set of characters to replace, may be null
Returns: modified String, null
if null string input
Since: 2.0
Replaces a String with another String inside a larger String, once.
A null
reference passed to this method is a no-op.
StringUtils.replaceOnce(null, *, *) = null StringUtils.replaceOnce("", *, *) = "" StringUtils.replaceOnce("any", null, *) = "any" StringUtils.replaceOnce("any", *, null) = "any" StringUtils.replaceOnce("any", "", *) = "any" StringUtils.replaceOnce("aba", "a", null) = "aba" StringUtils.replaceOnce("aba", "a", "") = "ba" StringUtils.replaceOnce("aba", "a", "z") = "zba"
Parameters: text text to search and replace in, may be null repl the String to search for, may be null with the String to replace with, may be null
Returns: the text with any replacements processed,
null
if null String input
See Also: StringUtils
Reverses a String as per StringBuffer#reverse().
A null
String returns null
.
StringUtils.reverse(null) = null StringUtils.reverse("") = "" StringUtils.reverse("bat") = "tab"
Parameters: str the String to reverse, may be null
Returns: the reversed String, null
if null String input
Reverses a String that is delimited by a specific character.
The Strings between the delimiters are not reversed.
Thus java.lang.String becomes String.lang.java (if the delimiter
is '.'
).
StringUtils.reverseDelimited(null, *) = null StringUtils.reverseDelimited("", *) = "" StringUtils.reverseDelimited("a.b.c", 'x') = "a.b.c" StringUtils.reverseDelimited("a.b.c", ".") = "c.b.a"
Parameters: str the String to reverse, may be null separatorChar the separator character to use
Returns: the reversed String, null
if null String input
Since: 2.0
Deprecated: Use StringUtils instead. This method is broken as the join doesn't know which char to use. Method will be removed in Commons Lang 3.0.
Reverses a String that is delimited by a specific character.
The Strings between the delimiters are not reversed.
Thus java.lang.String becomes String.lang.java (if the delimiter
is "."
).
StringUtils.reverseDelimitedString(null, *) = null StringUtils.reverseDelimitedString("",*) = "" StringUtils.reverseDelimitedString("a.b.c", null) = "a.b.c" StringUtils.reverseDelimitedString("a.b.c", ".") = "c.b.a"
Parameters: str the String to reverse, may be null separatorChars the separator characters to use, null treated as whitespace
Returns: the reversed String, null
if null String input
Gets the rightmost len
characters of a String.
If len
characters are not available, or the String
is null
, the String will be returned without an
an exception. An exception is thrown if len is negative.
StringUtils.right(null, *) = null StringUtils.right(*, -ve) = "" StringUtils.right("", *) = "" StringUtils.right("abc", 0) = "" StringUtils.right("abc", 2) = "bc" StringUtils.right("abc", 4) = "abc"
Parameters: str the String to get the rightmost characters from, may be null len the length of the required String, must be zero or positive
Returns: the rightmost characters, null
if null String input
Right pad a String with spaces (' ').
The String is padded to the size of size
.
StringUtils.rightPad(null, *) = null StringUtils.rightPad("", 3) = " " StringUtils.rightPad("bat", 3) = "bat" StringUtils.rightPad("bat", 5) = "bat " StringUtils.rightPad("bat", 1) = "bat" StringUtils.rightPad("bat", -1) = "bat"
Parameters: str the String to pad out, may be null size the size to pad to
Returns: right padded String or original String if no padding is necessary,
null
if null String input
Right pad a String with a specified character.
The String is padded to the size of size
.
StringUtils.rightPad(null, *, *) = null StringUtils.rightPad("", 3, 'z') = "zzz" StringUtils.rightPad("bat", 3, 'z') = "bat" StringUtils.rightPad("bat", 5, 'z') = "batzz" StringUtils.rightPad("bat", 1, 'z') = "bat" StringUtils.rightPad("bat", -1, 'z') = "bat"
Parameters: str the String to pad out, may be null size the size to pad to padChar the character to pad with
Returns: right padded String or original String if no padding is necessary,
null
if null String input
Since: 2.0
Right pad a String with a specified String.
The String is padded to the size of size
.
StringUtils.rightPad(null, *, *) = null StringUtils.rightPad("", 3, "z") = "zzz" StringUtils.rightPad("bat", 3, "yz") = "bat" StringUtils.rightPad("bat", 5, "yz") = "batyz" StringUtils.rightPad("bat", 8, "yz") = "batyzyzy" StringUtils.rightPad("bat", 1, "yz") = "bat" StringUtils.rightPad("bat", -1, "yz") = "bat" StringUtils.rightPad("bat", 5, null) = "bat " StringUtils.rightPad("bat", 5, "") = "bat "
Parameters: str the String to pad out, may be null size the size to pad to padStr the String to pad with, null or empty treated as single space
Returns: right padded String or original String if no padding is necessary,
null
if null String input
Splits the provided text into an array, using whitespace as the separator. Whitespace is defined by Character#isWhitespace(char).
The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.
A null
input String returns null
.
StringUtils.split(null) = null StringUtils.split("") = [] StringUtils.split("abc def") = ["abc", "def"] StringUtils.split("abc def") = ["abc", "def"] StringUtils.split(" abc ") = ["abc"]
Parameters: str the String to parse, may be null
Returns: an array of parsed Strings, null
if null String input
Splits the provided text into an array, separator specified. This is an alternative to using StringTokenizer.
The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.
A null
input String returns null
.
StringUtils.split(null, *) = null StringUtils.split("", *) = [] StringUtils.split("a.b.c", '.') = ["a", "b", "c"] StringUtils.split("a..b.c", '.') = ["a", "b", "c"] StringUtils.split("a:b:c", '.') = ["a:b:c"] StringUtils.split("a\tb\nc", null) = ["a", "b", "c"] StringUtils.split("a b c", ' ') = ["a", "b", "c"]
Parameters: str the String to parse, may be null separatorChar the character used as the delimiter,
null
splits on whitespace
Returns: an array of parsed Strings, null
if null String input
Since: 2.0
Splits the provided text into an array, separators specified. This is an alternative to using StringTokenizer.
The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.
A null
input String returns null
.
A null
separatorChars splits on whitespace.
StringUtils.split(null, *) = null StringUtils.split("", *) = [] StringUtils.split("abc def", null) = ["abc", "def"] StringUtils.split("abc def", " ") = ["abc", "def"] StringUtils.split("abc def", " ") = ["abc", "def"] StringUtils.split("ab:cd:ef", ":") = ["ab", "cd", "ef"]
Parameters: str the String to parse, may be null separatorChars the characters used as the delimiters,
null
splits on whitespace
Returns: an array of parsed Strings, null
if null String input
Splits the provided text into an array with a maximum length, separators specified.
The separator is not included in the returned String array. Adjacent separators are treated as one separator.
A null
input String returns null
.
A null
separatorChars splits on whitespace.
If more than max
delimited substrings are found, the last
returned string includes all characters after the first max - 1
returned strings (including separator characters).
StringUtils.split(null, *, *) = null StringUtils.split("", *, *) = [] StringUtils.split("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.split("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.split("ab:cd:ef", ":", 0) = ["ab", "cd", "ef"] StringUtils.split("ab:cd:ef", ":", 2) = ["ab", "cd:ef"]
Parameters: str the String to parse, may be null separatorChars the characters used as the delimiters,
null
splits on whitespace max the maximum number of elements to include in the
array. A zero or negative value implies no limit
Returns: an array of parsed Strings, null
if null String input
Splits the provided text into an array, separator string specified.
The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator.
A null
input String returns null
.
A null
separator splits on whitespace.
StringUtils.splitByWholeSeparator(null, *) = null StringUtils.splitByWholeSeparator("", *) = [] StringUtils.splitByWholeSeparator("ab de fg", null) = ["ab", "de", "fg"] StringUtils.splitByWholeSeparator("ab de fg", null) = ["ab", "de", "fg"] StringUtils.splitByWholeSeparator("ab:cd:ef", ":") = ["ab", "cd", "ef"] StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]
Parameters: str the String to parse, may be null separator String containing the String to be used as a delimiter,
null
splits on whitespace
Returns: an array of parsed Strings, null
if null String was input
Splits the provided text into an array, separator string specified.
Returns a maximum of max
substrings.
The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator.
A null
input String returns null
.
A null
separator splits on whitespace.
StringUtils.splitByWholeSeparator(null, *, *) = null StringUtils.splitByWholeSeparator("", *, *) = [] StringUtils.splitByWholeSeparator("ab de fg", null, 0) = ["ab", "de", "fg"] StringUtils.splitByWholeSeparator("ab de fg", null, 0) = ["ab", "de", "fg"] StringUtils.splitByWholeSeparator("ab:cd:ef", ":", 2) = ["ab", "cd:ef"] StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"] StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
Parameters: str the String to parse, may be null separator String containing the String to be used as a delimiter,
null
splits on whitespace max the maximum number of elements to include in the returned
array. A zero or negative value implies no limit.
Returns: an array of parsed Strings, null
if null String was input
Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer. Whitespace is defined by Character#isWhitespace(char).
The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.
A null
input String returns null
.
StringUtils.splitPreserveAllTokens(null) = null StringUtils.splitPreserveAllTokens("") = [] StringUtils.splitPreserveAllTokens("abc def") = ["abc", "def"] StringUtils.splitPreserveAllTokens("abc def") = ["abc", "", "def"] StringUtils.splitPreserveAllTokens(" abc ") = ["", "abc", ""]
Parameters: str the String to parse, may be null
Returns: an array of parsed Strings, null
if null String input
Since: 2.1
Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer.
The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.
A null
input String returns null
.
StringUtils.splitPreserveAllTokens(null, *) = null StringUtils.splitPreserveAllTokens("", *) = [] StringUtils.splitPreserveAllTokens("a.b.c", '.') = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a..b.c", '.') = ["a", "", "b", "c"] StringUtils.splitPreserveAllTokens("a:b:c", '.') = ["a:b:c"] StringUtils.splitPreserveAllTokens("a\tb\nc", null) = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a b c", ' ') = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a b c ", ' ') = ["a", "b", "c", ""] StringUtils.splitPreserveAllTokens("a b c ", ' ') = ["a", "b", "c", "", ""] StringUtils.splitPreserveAllTokens(" a b c", ' ') = ["", a", "b", "c"] StringUtils.splitPreserveAllTokens(" a b c", ' ') = ["", "", a", "b", "c"] StringUtils.splitPreserveAllTokens(" a b c ", ' ') = ["", a", "b", "c", ""]
Parameters: str the String to parse, may be null
separatorChar the character used as the delimiter,
null
splits on whitespace
Returns: an array of parsed Strings, null
if null String input
Since: 2.1
Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer.
The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.
A null
input String returns null
.
A null
separatorChars splits on whitespace.
StringUtils.splitPreserveAllTokens(null, *) = null StringUtils.splitPreserveAllTokens("", *) = [] StringUtils.splitPreserveAllTokens("abc def", null) = ["abc", "def"] StringUtils.splitPreserveAllTokens("abc def", " ") = ["abc", "def"] StringUtils.splitPreserveAllTokens("abc def", " ") = ["abc", "", def"] StringUtils.splitPreserveAllTokens("ab:cd:ef", ":") = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab:cd:ef:", ":") = ["ab", "cd", "ef", ""] StringUtils.splitPreserveAllTokens("ab:cd:ef::", ":") = ["ab", "cd", "ef", "", ""] StringUtils.splitPreserveAllTokens("ab::cd:ef", ":") = ["ab", "", cd", "ef"] StringUtils.splitPreserveAllTokens(":cd:ef", ":") = ["", cd", "ef"] StringUtils.splitPreserveAllTokens("::cd:ef", ":") = ["", "", cd", "ef"] StringUtils.splitPreserveAllTokens(":cd:ef:", ":") = ["", cd", "ef", ""]
Parameters: str the String to parse, may be null
separatorChars the characters used as the delimiters,
null
splits on whitespace
Returns: an array of parsed Strings, null
if null String input
Since: 2.1
Splits the provided text into an array with a maximum length, separators specified, preserving all tokens, including empty tokens created by adjacent separators.
The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. Adjacent separators are treated as one separator.
A null
input String returns null
.
A null
separatorChars splits on whitespace.
If more than max
delimited substrings are found, the last
returned string includes all characters after the first max - 1
returned strings (including separator characters).
StringUtils.splitPreserveAllTokens(null, *, *) = null StringUtils.splitPreserveAllTokens("", *, *) = [] StringUtils.splitPreserveAllTokens("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 0) = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 2) = ["ab", "cd:ef"] StringUtils.splitPreserveAllTokens("ab de fg", null, 2) = ["ab", " de fg"] StringUtils.splitPreserveAllTokens("ab de fg", null, 3) = ["ab", "", " de fg"] StringUtils.splitPreserveAllTokens("ab de fg", null, 4) = ["ab", "", "", "de fg"]
Parameters: str the String to parse, may be null
separatorChars the characters used as the delimiters,
null
splits on whitespace max the maximum number of elements to include in the
array. A zero or negative value implies no limit
Returns: an array of parsed Strings, null
if null String input
Since: 2.1
Strips whitespace from the start and end of a String.
This is similar to trim but removes whitespace. Whitespace is defined by Character#isWhitespace(char).
A null
input String returns null
.
StringUtils.strip(null) = null StringUtils.strip("") = "" StringUtils.strip(" ") = "" StringUtils.strip("abc") = "abc" StringUtils.strip(" abc") = "abc" StringUtils.strip("abc ") = "abc" StringUtils.strip(" abc ") = "abc" StringUtils.strip(" ab c ") = "ab c"
Parameters: str the String to remove whitespace from, may be null
Returns: the stripped String, null
if null String input
Strips any of a set of characters from the start and end of a String. This is similar to String#trim() but allows the characters to be stripped to be controlled.
A null
input String returns null
.
An empty string ("") input returns the empty string.
If the stripChars String is null
, whitespace is
stripped as defined by Character#isWhitespace(char).
Alternatively use strip.
StringUtils.strip(null, *) = null StringUtils.strip("", *) = "" 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"
Parameters: str the String to remove characters from, may be null stripChars the characters to remove, null treated as whitespace
Returns: the stripped String, null
if null String input
Strips whitespace from the start and end of every String in an array. Whitespace is defined by Character#isWhitespace(char).
A new array is returned each time, except for length zero.
A null
array will return null
.
An empty array will return itself.
A null
array entry will be ignored.
StringUtils.stripAll(null) = null StringUtils.stripAll([]) = [] StringUtils.stripAll(["abc", " abc"]) = ["abc", "abc"] StringUtils.stripAll(["abc ", null]) = ["abc", null]
Parameters: strs the array to remove whitespace from, may be null
Returns: the stripped Strings, null
if null array input
Strips any of a set of characters from the start and end of every String in an array.
Whitespace is defined by Character#isWhitespace(char).A new array is returned each time, except for length zero.
A null
array will return null
.
An empty array will return itself.
A null
array entry will be ignored.
A null
stripChars will strip whitespace as defined by
Character#isWhitespace(char).
StringUtils.stripAll(null, *) = null StringUtils.stripAll([], *) = [] StringUtils.stripAll(["abc", " abc"], null) = ["abc", "abc"] StringUtils.stripAll(["abc ", null], null) = ["abc", null] StringUtils.stripAll(["abc ", null], "yz") = ["abc ", null] StringUtils.stripAll(["yabcz", null], "yz") = ["abc", null]
Parameters: strs the array to remove characters from, may be null stripChars the characters to remove, null treated as whitespace
Returns: the stripped Strings, null
if null array input
Strips any of a set of characters from the end of a String.
A null
input String returns null
.
An empty string ("") input returns the empty string.
If the stripChars String is null
, whitespace is
stripped as defined by Character#isWhitespace(char).
StringUtils.stripEnd(null, *) = null StringUtils.stripEnd("", *) = "" 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"
Parameters: str the String to remove characters from, may be null stripChars the characters to remove, null treated as whitespace
Returns: the stripped String, null
if null String input
Strips any of a set of characters from the start of a String.
A null
input String returns null
.
An empty string ("") input returns the empty string.
If the stripChars String is null
, whitespace is
stripped as defined by Character#isWhitespace(char).
StringUtils.stripStart(null, *) = null StringUtils.stripStart("", *) = "" 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 "
Parameters: str the String to remove characters from, may be null stripChars the characters to remove, null treated as whitespace
Returns: the stripped String, null
if null String input
Strips whitespace from the start and end of a String returning
an empty String if null
input.
This is similar to trimToEmpty but removes whitespace. Whitespace is defined by Character#isWhitespace(char).
StringUtils.stripToEmpty(null) = "" StringUtils.stripToEmpty("") = "" StringUtils.stripToEmpty(" ") = "" StringUtils.stripToEmpty("abc") = "abc" StringUtils.stripToEmpty(" abc") = "abc" StringUtils.stripToEmpty("abc ") = "abc" StringUtils.stripToEmpty(" abc ") = "abc" StringUtils.stripToEmpty(" ab c ") = "ab c"
Parameters: str the String to be stripped, may be null
Returns: the trimmed String, or an empty String if null
input
Since: 2.0
Strips whitespace from the start and end of a String returning
null
if the String is empty ("") after the strip.
This is similar to trimToNull but removes whitespace. Whitespace is defined by Character#isWhitespace(char).
StringUtils.stripToNull(null) = null StringUtils.stripToNull("") = null StringUtils.stripToNull(" ") = null StringUtils.stripToNull("abc") = "abc" StringUtils.stripToNull(" abc") = "abc" StringUtils.stripToNull("abc ") = "abc" StringUtils.stripToNull(" abc ") = "abc" StringUtils.stripToNull(" ab c ") = "ab c"
Parameters: str the String to be stripped, may be null
Returns: the stripped String,
null
if whitespace, empty or null String input
Since: 2.0
Gets a substring from the specified String avoiding exceptions.
A negative start position can be used to start n
characters from the end of the String.
A null
String will return null
.
An empty ("") String will return "".
StringUtils.substring(null, *) = null StringUtils.substring("", *) = "" StringUtils.substring("abc", 0) = "abc" StringUtils.substring("abc", 2) = "c" StringUtils.substring("abc", 4) = "" StringUtils.substring("abc", -2) = "bc" StringUtils.substring("abc", -4) = "abc"
Parameters: str the String to get the substring from, may be null start the position to start from, negative means count back from the end of the String by this many characters
Returns: substring from start position, null
if null String input
Gets a substring from the specified String avoiding exceptions.
A negative start position can be used to start/end n
characters from the end of the String.
The returned substring starts with the character in the start
position and ends before the end
position. All position counting is
zero-based -- i.e., to start at the beginning of the string use
start = 0
. Negative start and end positions can be used to
specify offsets relative to the end of the String.
If start
is not strictly to the left of end
, ""
is returned.
StringUtils.substring(null, *, *) = null StringUtils.substring("", * , *) = ""; StringUtils.substring("abc", 0, 2) = "ab" StringUtils.substring("abc", 2, 0) = "" StringUtils.substring("abc", 2, 4) = "c" StringUtils.substring("abc", 4, 6) = "" StringUtils.substring("abc", 2, 2) = "" StringUtils.substring("abc", -2, -1) = "b" StringUtils.substring("abc", -4, 2) = "ab"
Parameters: str the String to get the substring from, may be null start the position to start from, negative means count back from the end of the String by this many characters end the position to end at (exclusive), negative means count back from the end of the String by this many characters
Returns: substring from start position to end positon,
null
if null String input
Gets the substring after the first occurrence of a separator. The separator is not returned.
A null
string input will return null
.
An empty ("") string input will return the empty string.
A null
separator will return the empty string if the
input string is not null
.
StringUtils.substringAfter(null, *) = null StringUtils.substringAfter("", *) = "" StringUtils.substringAfter(*, null) = "" StringUtils.substringAfter("abc", "a") = "bc" StringUtils.substringAfter("abcba", "b") = "cba" StringUtils.substringAfter("abc", "c") = "" StringUtils.substringAfter("abc", "d") = "" StringUtils.substringAfter("abc", "") = "abc"
Parameters: str the String to get a substring from, may be null separator the String to search for, may be null
Returns: the substring after the first occurrence of the separator,
null
if null String input
Since: 2.0
Gets the substring after the last occurrence of a separator. The separator is not returned.
A null
string input will return null
.
An empty ("") string input will return the empty string.
An empty or null
separator will return the empty string if
the input string is not null
.
StringUtils.substringAfterLast(null, *) = null StringUtils.substringAfterLast("", *) = "" StringUtils.substringAfterLast(*, "") = "" StringUtils.substringAfterLast(*, null) = "" StringUtils.substringAfterLast("abc", "a") = "bc" StringUtils.substringAfterLast("abcba", "b") = "a" StringUtils.substringAfterLast("abc", "c") = "" StringUtils.substringAfterLast("a", "a") = "" StringUtils.substringAfterLast("a", "z") = ""
Parameters: str the String to get a substring from, may be null separator the String to search for, may be null
Returns: the substring after the last occurrence of the separator,
null
if null String input
Since: 2.0
Gets the substring before the first occurrence of a separator. The separator is not returned.
A null
string input will return null
.
An empty ("") string input will return the empty string.
A null
separator will return the input string.
StringUtils.substringBefore(null, *) = null StringUtils.substringBefore("", *) = "" StringUtils.substringBefore("abc", "a") = "" StringUtils.substringBefore("abcba", "b") = "a" StringUtils.substringBefore("abc", "c") = "ab" StringUtils.substringBefore("abc", "d") = "abc" StringUtils.substringBefore("abc", "") = "" StringUtils.substringBefore("abc", null) = "abc"
Parameters: str the String to get a substring from, may be null separator the String to search for, may be null
Returns: the substring before the first occurrence of the separator,
null
if null String input
Since: 2.0
Gets the substring before the last occurrence of a separator. The separator is not returned.
A null
string input will return null
.
An empty ("") string input will return the empty string.
An empty or null
separator will return the input string.
StringUtils.substringBeforeLast(null, *) = null StringUtils.substringBeforeLast("", *) = "" StringUtils.substringBeforeLast("abcba", "b") = "abc" StringUtils.substringBeforeLast("abc", "c") = "ab" StringUtils.substringBeforeLast("a", "a") = "" StringUtils.substringBeforeLast("a", "z") = "a" StringUtils.substringBeforeLast("a", null) = "a" StringUtils.substringBeforeLast("a", "") = "a"
Parameters: str the String to get a substring from, may be null separator the String to search for, may be null
Returns: the substring before the last occurrence of the separator,
null
if null String input
Since: 2.0
Gets the String that is nested in between two instances of the same String.
A null
input String returns null
.
A null
tag returns null
.
StringUtils.substringBetween(null, *) = null StringUtils.substringBetween("", "") = "" StringUtils.substringBetween("", "tag") = null StringUtils.substringBetween("tagabctag", null) = null StringUtils.substringBetween("tagabctag", "") = "" StringUtils.substringBetween("tagabctag", "tag") = "abc"
Parameters: str the String containing the substring, may be null tag the String before and after the substring, may be null
Returns: the substring, null
if no match
Since: 2.0
Gets the String that is nested in between two Strings. Only the first match is returned.
A null
input String returns null
.
A null
open/close returns null
(no match).
An empty ("") open and close returns an empty string.
StringUtils.substringBetween("wx[b]yz", "[", "]") = "b" StringUtils.substringBetween(null, *, *) = null StringUtils.substringBetween(*, null, *) = null StringUtils.substringBetween(*, *, null) = null StringUtils.substringBetween("", "", "") = "" StringUtils.substringBetween("", "", "]") = null StringUtils.substringBetween("", "[", "]") = null StringUtils.substringBetween("yabcz", "", "") = "" StringUtils.substringBetween("yabcz", "y", "z") = "abc" StringUtils.substringBetween("yabczyabcz", "y", "z") = "abc"
Parameters: str the String containing the substring, may be null open the String before the substring, may be null close the String after the substring, may be null
Returns: the substring, null
if no match
Since: 2.0
Searches a String for substrings delimited by a start and end tag, returning all matching substrings in an array.
A null
input String returns null
.
A null
open/close returns null
(no match).
An empty ("") open/close returns null
(no match).
StringUtils.substringsBetween("[a][b][c]", "[", "]") = ["a","b","c"] StringUtils.substringsBetween(null, *, *) = null StringUtils.substringsBetween(*, null, *) = null StringUtils.substringsBetween(*, *, null) = null StringUtils.substringsBetween("", "[", "]") = []
Parameters: str the String containing the substrings, null returns null, empty returns empty open the String identifying the start of the substring, empty returns null close the String identifying the end of the substring, empty returns null
Returns: a String Array of substrings, or null
if no match
Since: 2.3
Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
For a word based algorithm, see swapCase.
A null
input String returns null
.
StringUtils.swapCase(null) = null StringUtils.swapCase("") = "" StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"
NOTE: This method changed in Lang version 2.0. It no longer performs a word based algorithm. If you only use ASCII, you will notice no change. That functionality is available in WordUtils.
Parameters: str the String to swap case, may be null
Returns: the changed String, null
if null String input
Removes control characters (char <= 32) from both
ends of this String, handling null
by returning
null
.
The String is trimmed using String#trim(). Trim removes start and end characters <= 32. To strip whitespace use strip.
To trim your choice of characters, use the StringUtils methods.
StringUtils.trim(null) = null StringUtils.trim("") = "" StringUtils.trim(" ") = "" StringUtils.trim("abc") = "abc" StringUtils.trim(" abc ") = "abc"
Parameters: str the String to be trimmed, may be null
Returns: the trimmed string, null
if null String input
Removes control characters (char <= 32) from both
ends of this String returning an empty String ("") if the String
is empty ("") after the trim or if it is null
.
The String is trimmed using String#trim(). Trim removes start and end characters <= 32. To strip whitespace use stripToEmpty.
StringUtils.trimToEmpty(null) = "" StringUtils.trimToEmpty("") = "" StringUtils.trimToEmpty(" ") = "" StringUtils.trimToEmpty("abc") = "abc" StringUtils.trimToEmpty(" abc ") = "abc"
Parameters: str the String to be trimmed, may be null
Returns: the trimmed String, or an empty String if null
input
Since: 2.0
Removes control characters (char <= 32) from both
ends of this String returning null
if the String is
empty ("") after the trim or if it is null
.
The String is trimmed using String#trim(). Trim removes start and end characters <= 32. To strip whitespace use stripToNull.
StringUtils.trimToNull(null) = null StringUtils.trimToNull("") = null StringUtils.trimToNull(" ") = null StringUtils.trimToNull("abc") = "abc" StringUtils.trimToNull(" abc ") = "abc"
Parameters: str the String to be trimmed, may be null
Returns: the trimmed String,
null
if only chars <= 32, empty or null String input
Since: 2.0
Deprecated: Use the standardly named uncapitalize. Method will be removed in Commons Lang 3.0.
Uncapitalizes a String changing the first letter to title case as per Character#toLowerCase(char). No other letters are changed.
Parameters: str the String to uncapitalize, may be null
Returns: the uncapitalized String, null
if null String input
Uncapitalizes a String changing the first letter to title case as per Character#toLowerCase(char). No other letters are changed.
For a word based algorithm, see uncapitalize.
A null
input String returns null
.
StringUtils.uncapitalize(null) = null StringUtils.uncapitalize("") = "" StringUtils.uncapitalize("Cat") = "cat" StringUtils.uncapitalize("CAT") = "cAT"
Parameters: str the String to uncapitalize, may be null
Returns: the uncapitalized String, null
if null String input
Since: 2.0
See Also: uncapitalize capitalize
Converts a String to upper case as per String#toUpperCase().
A null
input String returns null
.
StringUtils.upperCase(null) = null StringUtils.upperCase("") = "" StringUtils.upperCase("aBc") = "ABC"
Parameters: str the String to upper case, may be null
Returns: the upper cased String, null
if null String input