Java Doc for StringUtils.java in  » Library » Apache-common-lang » org » apache » commons » lang » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Operations on java.lang.String that are null safe.

• IsEmpty/IsBlank - checks if a String contains text
• Trim/Strip - removes leading and trailing whitespace
• Equals - compares two strings null-safe
• IndexOf/LastIndexOf/Contains - null-safe index-of checks
• IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut - index-of any of a set of Strings
• ContainsOnly/ContainsNone - does String contains only/none of these characters
• Substring/Left/Right/Mid - null-safe substring extractions
• SubstringBefore/SubstringAfter/SubstringBetween - substring extraction relative to other strings
• Split/Join - splits a String into an array of substrings and vice versa
• Remove/Delete - removes part of a String
• Replace/Overlay - Searches a String and replaces one String with another
• Chomp/Chop - removes the last part of a String
• LeftPad/RightPad/Center/Repeat - pads a String
• UpperCase/LowerCase/SwapCase/Capitalize/Uncapitalize - changes the case of a String
• CountMatches - counts the number of occurrences of one String in another
• IsAlpha/IsNumeric/IsWhitespace/IsAsciiPrintable - checks the characters in a String
• DefaultString - protects against a null input String
• Reverse/ReverseDelimited - reverses a String
• Abbreviate - abbreviates a string using ellipsis
• Difference - compares two Strings and reports on their differences
• LevensteinDistance - the number of changes needed to change one String into another

The StringUtils class defines certain words related to String handling.

• null - null
• empty - a zero-length string ("")
• space - the space character (' ', char 32)
• whitespace - the characters defined by Character.isWhitespace(char)
• trim - the characters <= 32 as in String.trim

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.

StringUtils instances should NOT be constructed in standard programming.

Abbreviates a String using ellipses.

Abbreviates a String using ellipses.

Capitalizes a String changing the first letter to title case as per Character.toTitleCase(char) .

Capitalizes all the whitespace separated words in a String.

Capitalizes a String changing the first letter to title case as per Character.toTitleCase(char) .

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.

Centers a String in a larger String of size size.

Centers a String in a larger String of size size.

Removes one newline from end of a String if it's there, otherwise leave it alone.

Removes separator from the end of str if it's there, otherwise leave it alone.

NOTE: This method changed in version 2.0.

Removes \n from end of a String if it's there.

Concatenates elements of an array into a single String.

Checks if String contains a search character, handling null.

Checks if String contains a search String, handling null.

Checks if String contains a search String irrespective of case, handling null.

Checks that the String does not contain certain characters.

A null String will return true.

Checks that the String does not contain certain characters.

A null String will return true.

Checks if the String contains only certain characters.

A null String will return false.

Checks if the String contains only certain characters.

A null String will return false.

Deletes all 'space' characters from a String as defined by Character.isSpace(char) .

This is the only StringUtils method that uses the isSpace definition.

Compares two Strings, and returns the portion where they differ.

Compares two Strings, returning true if they are equal.

nulls are handled without exceptions.

Compares two Strings, returning true if they are equal ignoring the case.

nulls are handled without exceptions.

Escapes any values it finds into their String form.

So a tab becomes the characters '\\' and 't'.

As of Lang 2.0, this calls StringEscapeUtils.escapeJava(String) behind the scenes.

Gets the String that is nested in between two instances of the same String.

A null input String returns null.

Gets the String that is nested in between two Strings.

Finds the first index within a String, handling null.

Finds the first index within a String from a start position, handling null.

Finds the first index within a String, handling null.

Finds the first index within a String, handling null.

Search a String to find the first index of any character in the given set of characters.

A null String will return -1.

Search a String to find the first index of any character in the given set of characters.

A null String will return -1.

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.

Search a String to find the first index of any character not in the given set of characters.

A null String will return -1.

Search a String to find the first index of any character not in the given set of characters.

A null String will return -1.

Checks if the String contains only unicode letters.

null will return false.

Checks if the String contains only unicode letters or digits.

null will return false.

Checks if the String contains only unicode letters, digits or space (' ').

null will return false.

Checks if the string contains only ASCII printable characters.

null will return false.

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.

Checks if the String contains only unicode digits.

Checks if the String contains only unicode digits or space (' ').

Checks if the String contains only whitespace.

null will return false.

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.

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.

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"
 

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.

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"
 

Joins the elements of the provided Iterator into a single String containing the provided elements.

No delimiter is added before or after the list.

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: StringUtils.join(Object[],String) .

Joins the elements of the provided Collection into a single String containing the provided elements.

No delimiter is added before or after the list.

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: StringUtils.join(Object[],String) .

Finds the last index within a String, handling null.

Finds the last index within a String from a start position, handling null.

Finds the last index within a String, handling null.

Finds the first index within a String, handling null.

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.

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.

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.

Finds the n-th index within a String, handling null.

Overlays part of a String with another String.

A null string input returns null.

Removes all occurances of a substring from within the source string.

A null source string will return null.

Removes all occurances of a character from within the source string.

A null source string will return null.

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.

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.

Replaces all occurrences of a character in a String with another.

Replaces multiple characters in a String in one go.

Reverses a String that is delimited by a specific character.

The Strings between the delimiters are not reversed.

Reverses a String that is delimited by a specific character.

The Strings between the delimiters are not reversed.

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.

Splits the provided text into an array, using whitespace as the separator.

Splits the provided text into an array, separator specified.

Splits the provided text into an array, separators specified.

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"]
 

Splits the provided text into an array, separator string specified.

The separator(s) will not be included in the returned String array.

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"]
 

Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators.

Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators.

Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators.

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"]
 

Strips whitespace from the start and end of a String.

This is similar to StringUtils.trim(String) but removes whitespace.

Strips any of a set of characters from the start and end of a String.

Strips whitespace from the start and end of every String in an array.

Strips any of a set of characters from the start and end of every String in an array.

A new array is returned each time, except for length zero.

Strips any of a set of characters from the end of a String.

A null input String returns null.

Strips any of a set of characters from the start of a String.

A null input String returns null.

Strips whitespace from the start and end of a String returning an empty String if null input.

This is similar to StringUtils.trimToEmpty(String) but removes whitespace.

Strips whitespace from the start and end of a String returning null if the String is empty ("") after the strip.

This is similar to StringUtils.trimToNull(String) but removes whitespace.

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.

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.

Gets the substring after the first occurrence of a separator.

Gets the substring after the last occurrence of a separator.

Gets the substring before the first occurrence of a separator.

Gets the substring before the last occurrence of a separator.

Gets the String that is nested in between two instances of the same String.

A null input String returns null.

Gets the String that is nested in between two Strings.

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.

Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.

• Upper case character converts to Lower case
• Title case character converts to Lower case
• Lower case character converts to Upper case

For a word based algorithm, see WordUtils.swapCase(String) .

Removes control characters (char <= 32) from both ends of this String, handling null by returning null.

The String is trimmed using String.trim .

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.

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.

Uncapitalizes a String changing the first letter to title case as per Character.toLowerCase(char) .

Uncapitalizes a String changing the first letter to title case as per Character.toLowerCase(char) .

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:

• If str is less than maxWidth characters long, return it.
• Else abbreviate it to (substring(str, 0, max-3) + "...").
• If maxWidth is less than 4, throw an IllegalArgumentException.
• In no case will it return a String of length greater than 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
 

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
 

Capitalizes a String changing the first letter to title case as per Character.toTitleCase(char) . No other letters are changed.

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.

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 WordUtils.capitalize(String) . A null input String returns null.

 StringUtils.capitalize(null)  = null
 StringUtils.capitalize("")    = ""
 StringUtils.capitalize("cat") = "Cat"
 StringUtils.capitalize("cAt") = "CAt"
 

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  "
 

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"
 

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  "
 

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")        = ""
 

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.substringBeforeLast(String,String) . 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"
 

Remove any "\n" if and only if it is at the end of the supplied String.

Remove a value if and only if the String ends with that value.

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")        = ""
 

Removes \n from end of a String if it's there. If a \r precedes it, then remove that too.

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("     ")       = ""
 

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"
 

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
 

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
 

Checks if String contains a search String irrespective of case, handling null. This method uses StringUtils.contains(String,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
 StringUtils.contains("abc", "A") = true
 StringUtils.contains("abc", "Z") = false
 

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
 

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
 

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
 

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
 

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
 

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"
 

Returns either the passed in String, or if the String is null, an empty String ("").

 StringUtils.defaultString(null)  = ""
 StringUtils.defaultString("")    = ""
 StringUtils.defaultString("bat") = "bat"
 

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"
 

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 StringUtils.deleteWhitespace(String) 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.

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"
 

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"
 

Compares two Strings, returning true if they are equal.

nulls 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
 

Compares two Strings, returning true if they are equal ignoring the case.

nulls 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
 

Escapes any values it finds into their String form.

So a tab becomes the characters '\\' and 't'.

As of Lang 2.0, this calls StringEscapeUtils.escapeJava(String) behind the scenes.

Remove everything and return the last value of a supplied String, and everything after it from a String.

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
 

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"
 

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"
 

Remove and return everything before the first value of a supplied String from another String.

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
 

Finds the first index within a String from a start position, handling null. This method uses String.indexOf(intint) .

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
 

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
 

Finds the first index within a String, handling null. This method uses String.indexOf(Stringint) .

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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("\u0020") = true
 StringUtils.isAsciiPrintable("\u0021") = true
 StringUtils.isAsciiPrintable("\u007e") = true
 StringUtils.isAsciiPrintable("\u007f") = false
 StringUtils.isAsciiPrintable("Ceki G\u00fclc\u00fc") = false
 

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
 

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().

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
 

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
 

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
 

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
 

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
 

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"
 

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"
 

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"
 

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"
 

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"
 

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: StringUtils.join(Object[],char) .

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: StringUtils.join(Object[],String) .

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: StringUtils.join(Object[],char) .

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: StringUtils.join(Object[],String) .

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
 

Finds the last index within a String from a start position, handling null. This method uses String.lastIndexOf(intint) .

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
 

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
 

Finds the first index within a String, handling null. This method uses String.lastIndexOf(Stringint) .

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
 

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
 

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"
 

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"
 

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"
 

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"
 

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"
 

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"
 

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
 

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"
 

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
 

Remove the first value of a supplied String, and everything before it from a String.

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"
 

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"
 

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"
 

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"
 

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) = ""
 

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"
 

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"
 

Replaces all occurrences of a character in a String with another. This is a null-safe version of String.replace(charchar) .

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"
 

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"
 

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"
 

Reverses a String as per StringBuffer.reverse .

A null String returns null.

 StringUtils.reverse(null)  = null
 StringUtils.reverse("")    = ""
 StringUtils.reverse("bat") = "tab"
 

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"
 

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"
 

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"
 

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"
 

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"
 

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  "
 

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"]
 

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"]
 

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"]
 

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"]
 

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"]
 

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"]
 

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", ""]
 

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", ""]
 

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", ""]
 

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"]
 

Strips whitespace from the start and end of a String.

This is similar to StringUtils.trim(String) 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"
 

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 StringUtils.strip(String) .

 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"
 

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]
 

Strips any of a set of characters from the start and end of every String in an array.

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]
 

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"
 

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  "
 

Strips whitespace from the start and end of a String returning an empty String if null input.

This is similar to StringUtils.trimToEmpty(String) 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"
 

Strips whitespace from the start and end of a String returning null if the String is empty ("") after the strip.

This is similar to StringUtils.trimToNull(String) 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"
 

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"
 

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"
 

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"
 

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")     = ""
 

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"
 

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"
 

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"
 

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"
 

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("", "[", "]")          = []
 

Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.

• Upper case character converts to Lower case
• Title case character converts to Lower case
• Lower case character converts to Upper case

For a word based algorithm, see WordUtils.swapCase(String) . 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.