org.apache.commons.lang

Class StringUtils

public class StringUtils extends Object

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
startsWith - check if a String starts with a prefix null-safe
endsWith - check if a String ends with a suffix null-safe
IndexOf/LastIndexOf/Contains - null-safe index-of checks
IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut - index-of any of a set of Strings
ContainsOnly/ContainsNone/ContainsAny - does String contains only/none/any 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 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.

Since: 1.0

Version: $Id: StringUtils.java 635447 2008-03-10 06:27:09Z bayard $

Author: Apache Jakarta Turbine Jon S. Stevens Daniel L. Rall Greg Coladonato Ed Korthof Rand McNeely Stephen Colebourne Fredrik Westermarck Holger Krauth Alexander Day Chaffee Henning P. Schmiedehausen Arun Mammen Thomas Gary Gregory Phil Steitz Al Chou Michael Davey Reuben Sivan Chris Hyzer Scott Johnson

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() `StringUtils` instances should NOT be constructed in standard programming.

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 `size` using the space character (' '). 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 `size`.
static String	center(String str, int size, String padStr) Centers a String in a larger String of size `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 `separator` from the end of `str` if it's there, otherwise leave it alone. 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 `\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") = ""
static String	chopNewline(String str) Removes `\n` from end of a String if it's there.
static String	clean(String str) 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(" ") = ""
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 `null`.
static boolean	contains(String str, String searchStr) Checks if String contains a search String, handling `null`.
static boolean	containsAny(String str, char[] searchChars) Checks if the String contains any character in the given set of characters. A `null` String will return `false`.
static boolean	containsAny(String str, String searchChars) Checks if the String contains any character in the given set of characters.
static boolean	containsIgnoreCase(String str, String searchStr) Checks if String contains a search String irrespective of case, handling `null`.
static boolean	containsNone(String str, char[] invalidChars) Checks that the String does not contain certain characters. A `null` String will return `true`.
static boolean	containsNone(String str, String invalidChars) Checks that the String does not contain certain characters. A `null` String will return `true`.
static boolean	containsOnly(String str, char[] valid) Checks if the String contains only certain characters. A `null` String will return `false`.
static boolean	containsOnly(String str, String validChars) Checks if the String contains only certain characters. A `null` String will return `false`.
static int	countMatches(String str, String sub) 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
static String	defaultIfEmpty(String str, String defaultStr) 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"
static String	defaultString(String str) Returns either the passed in String, or if the String is `null`, an empty String (""). 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 `null`, the value of `defaultStr`. 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 `isSpace` definition.
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	endsWith(String str, String suffix) Check if a String ends with a specified suffix. `null`s are handled without exceptions.
static boolean	endsWithIgnoreCase(String str, String suffix) Case insensitive check if a String ends with a specified suffix. `null`s are handled without exceptions.
static boolean	equals(String str1, String str2) Compares two Strings, returning `true` if they are equal. `null`s are handled without exceptions.
static boolean	equalsIgnoreCase(String str1, String str2) Compares two Strings, returning `true` if they are equal ignoring the case. `null`s are handled without exceptions.
static String	escape(String str) 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.
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 String	getCommonPrefix(String[] strs) Compares all Strings in an array and returns the initial sequence of characters that is common to all of them. For example, `getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) -> "i am a "` StringUtils.getCommonPrefix(null) = "" StringUtils.getCommonPrefix(new String[] {}) = "" StringUtils.getCommonPrefix(new String[] {"abc"}) = "abc" StringUtils.getCommonPrefix(new String[] {null, null}) = "" StringUtils.getCommonPrefix(new String[] {"", ""}) = "" StringUtils.getCommonPrefix(new String[] {"", null}) = "" StringUtils.getCommonPrefix(new String[] {"abc", null, null}) = "" StringUtils.getCommonPrefix(new String[] {null, null, "abc"}) = "" StringUtils.getCommonPrefix(new String[] {"", "abc"}) = "" StringUtils.getCommonPrefix(new String[] {"abc", ""}) = "" StringUtils.getCommonPrefix(new String[] {"abc", "abc"}) = "abc" StringUtils.getCommonPrefix(new String[] {"abc", "a"}) = "a" StringUtils.getCommonPrefix(new String[] {"ab", "abxyz"}) = "ab" StringUtils.getCommonPrefix(new String[] {"abcde", "abxyz"}) = "ab" StringUtils.getCommonPrefix(new String[] {"abcde", "xyz"}) = "" StringUtils.getCommonPrefix(new String[] {"xyz", "abcde"}) = "" StringUtils.getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) = "i am a "
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. 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
static String	getNestedString(String str, String tag) Gets the String that is nested in between two instances of the same String. A `null` input String returns `null`.
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 `null`.
static int	indexOf(String str, char searchChar, int startPos) Finds the first index within a String from a start position, handling `null`.
static int	indexOf(String str, String searchStr) Finds the first index within a String, handling `null`.
static int	indexOf(String str, String searchStr, int startPos) Finds the first index within a String, handling `null`.
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 `null` String will return `-1`.
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 `null` String will return `-1`.
static int	indexOfAny(String str, String[] searchStrs) Find the first index of any of a set of potential substrings. A `null` String will return `-1`.
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 `null` String will return `-1`.
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 `null` String will return `-1`.
static int	indexOfDifference(String str1, String str2) 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
static int	indexOfDifference(String[] strs) Compares all Strings in an array and returns the index at which the Strings begin to differ. For example, `indexOfDifference(new String[] {"i am a machine", "i am a robot"}) -> 7` StringUtils.indexOfDifference(null) = -1 StringUtils.indexOfDifference(new String[] {}) = -1 StringUtils.indexOfDifference(new String[] {"abc"}) = -1 StringUtils.indexOfDifference(new String[] {null, null}) = -1 StringUtils.indexOfDifference(new String[] {"", ""}) = -1 StringUtils.indexOfDifference(new String[] {"", null}) = 0 StringUtils.indexOfDifference(new String[] {"abc", null, null}) = 0 StringUtils.indexOfDifference(new String[] {null, null, "abc"}) = 0 StringUtils.indexOfDifference(new String[] {"", "abc"}) = 0 StringUtils.indexOfDifference(new String[] {"abc", ""}) = 0 StringUtils.indexOfDifference(new String[] {"abc", "abc"}) = -1 StringUtils.indexOfDifference(new String[] {"abc", "a"}) = 1 StringUtils.indexOfDifference(new String[] {"ab", "abxyz"}) = 2 StringUtils.indexOfDifference(new String[] {"abcde", "abxyz"}) = 2 StringUtils.indexOfDifference(new String[] {"abcde", "xyz"}) = 0 StringUtils.indexOfDifference(new String[] {"xyz", "abcde"}) = 0 StringUtils.indexOfDifference(new String[] {"i am a machine", "i am a robot"}) = 7
static boolean	isAlpha(String str) Checks if the String contains only unicode letters. `null` will return `false`.
static boolean	isAlphanumeric(String str) Checks if the String contains only unicode letters or digits. `null` will return `false`.
static boolean	isAlphanumericSpace(String str) Checks if the String contains only unicode letters, digits or space (`' '`). `null` will return `false`.
static boolean	isAlphaSpace(String str) 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
static boolean	isAsciiPrintable(String str) Checks if the string contains only ASCII printable characters. `null` will return `false`.
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. `null` will return `false`.
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 `Iterator` into a single String containing the provided elements. No delimiter is added before or after the list.
static String	join(Iterator iterator, String separator) Joins the elements of the provided `Iterator` into a single String containing the provided elements. No delimiter is added before or after the list.
static String	join(Collection collection, char separator) Joins the elements of the provided `Collection` into a single String containing the provided elements. No delimiter is added before or after the list.
static String	join(Collection collection, String separator) Joins the elements of the provided `Collection` into a single String containing the provided elements. No delimiter is added before or after the list.
static int	lastIndexOf(String str, char searchChar) Finds the last index within a String, handling `null`.
static int	lastIndexOf(String str, char searchChar, int startPos) Finds the last index within a String from a start position, handling `null`.
static int	lastIndexOf(String str, String searchStr) Finds the last index within a String, handling `null`.
static int	lastIndexOf(String str, String searchStr, int startPos) Finds the first index within a String, handling `null`.
static int	lastIndexOfAny(String str, String[] searchStrs) Find the latest index of any of a set of potential substrings. A `null` String will return `-1`.
static String	left(String str, int len) 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.
static String	leftPad(String str, int size) 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"`
static String	leftPad(String str, int size, char padChar) 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"
static String	leftPad(String str, int size, String padStr) 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"
static int	length(String str) Gets a String's length or `0` if the String is `null`.
static String	lowerCase(String str) 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"
static String	mid(String str, int pos, int len) 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.
static int	ordinalIndexOf(String str, String searchStr, int ordinal) Finds the n-th index within a String, handling `null`.
static String	overlay(String str, String overlay, int start, int end) Overlays part of a String with another String. A `null` string input returns `null`.
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 occurrences of a substring from within the source string. A `null` source string will return `null`.
static String	remove(String str, char remove) Removes all occurrences of a character from within the source string. A `null` source string will return `null`.
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 `null` source string will return `null`.
static String	removeEndIgnoreCase(String str, String remove) Case insensitive removal of a substring if it is at the end of a source string, otherwise returns the source string. A `null` source string will return `null`.
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 `null` source string will return `null`.
static String	removeStartIgnoreCase(String str, String remove) Case insensitive removal of a substring if it is at the begining of a source string, otherwise returns the source string. A `null` source string will return `null`.
static String	repeat(String str, int repeat) 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) = ""
static String	replace(String text, String searchString, String replacement) 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"
static String	replace(String text, String searchString, String replacement, int max) 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"
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	replaceEach(String text, String[] searchList, String[] replacementList) Replaces all occurrences of Strings within another String.
static String	replaceEachRepeatedly(String text, String[] searchList, String[] replacementList) Replaces all occurrences of Strings within another String.
static String	replaceOnce(String text, String searchString, String replacement) 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"
static String	reverse(String str) Reverses a String as per StringBuffer#reverse(). A `null` String returns `null`. 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 `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.
static String	rightPad(String str, int size) 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"
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 `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"
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 `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 "
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[]	splitByCharacterType(String str) Splits a String by Character type as returned by `java.lang.Character.getType(char)`.
static String[]	splitByCharacterTypeCamelCase(String str) Splits a String by Character type as returned by `java.lang.Character.getType(char)`.
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[]	splitByWholeSeparatorPreserveAllTokens(String str, String separator) Splits the provided text into an array, separator string specified.
static String[]	splitByWholeSeparatorPreserveAllTokens(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 boolean	startsWith(String str, String prefix) Check if a String starts with a specified prefix. `null`s are handled without exceptions.
static boolean	startsWithIgnoreCase(String str, String prefix) Case insensitive check if a String starts with a specified prefix. `null`s are handled without exceptions.
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 `null` input String returns `null`.
static String	stripStart(String str, String stripChars) Strips any of a set of characters from the start of a String. A `null` input String returns `null`.
static String	stripToEmpty(String str) 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.
static String	stripToNull(String str) 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.
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 `n` characters from the end of the String. A `null` String will return `null`.
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 `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.
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 `null` input String returns `null`.
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 `null` input String returns `null`.
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. 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 swapCase.
static String	trim(String str) Removes control characters (char <= 32) from both ends of this String, handling `null` by returning `null`. 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 `null`.
static String	trimToNull(String str) 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`.
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 `null` input String returns `null`. StringUtils.upperCase(null) = null StringUtils.upperCase("") = "" StringUtils.upperCase("aBc") = "ABC"

Field Detail

EMPTY

public static final String EMPTY

The empty String "".

Since: 2.0

INDEX_NOT_FOUND

public static final int INDEX_NOT_FOUND

Represents a failed index search.

Since: 2.1

Constructor Detail

StringUtils

public StringUtils()

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.

Method Detail

abbreviate

public static String abbreviate(String str, int maxWidth)

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

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

abbreviate

public static String abbreviate(String str, int offset, int maxWidth)

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

capitalise

public static String capitalise(String str)

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

capitaliseAllWords

public static String capitaliseAllWords(String str)

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

capitalize

public static String capitalize(String str)

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

center

public static String center(String str, int size)

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

center

public static String center(String str, int size, char padChar)

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

center

public static String center(String str, int size, String padStr)

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

chomp

public static String chomp(String str)

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

chomp

public static String chomp(String str, String separator)

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

chompLast

public static String chompLast(String str)

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

chompLast

public static String chompLast(String str, String sep)

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

chop

public static String chop(String str)

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

chopNewline

public static String chopNewline(String str)

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

clean

public static String clean(String str)

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

concatenate

public static String concatenate(Object[] array)

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

contains

public static boolean contains(String str, char searchChar)

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

contains

public static boolean contains(String str, String searchStr)

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

containsAny

public static boolean containsAny(String str, char[] searchChars)

Checks if the String contains any character in the given set of characters.

A null String will return false. A null or zero length search array will return false.

 StringUtils.containsAny(null, *)                = false
 StringUtils.containsAny("", *)                  = false
 StringUtils.containsAny(*, null)                = false
 StringUtils.containsAny(*, [])                  = false
 StringUtils.containsAny("zzabyycdxx",['z','a']) = true
 StringUtils.containsAny("zzabyycdxx",['b','y']) = true
 StringUtils.containsAny("aba", ['z'])           = false

Parameters: str the String to check, may be null searchChars the chars to search for, may be null

Returns: the true if any of the chars are found, false if no match or null input

Since: 2.4

containsAny

public static boolean containsAny(String str, String searchChars)

Checks if the String contains any character in the given set of characters.

A null String will return false. A null search string will return false.

 StringUtils.containsAny(null, *)            = false
 StringUtils.containsAny("", *)              = false
 StringUtils.containsAny(*, null)            = false
 StringUtils.containsAny(*, "")              = false
 StringUtils.containsAny("zzabyycdxx", "za") = true
 StringUtils.containsAny("zzabyycdxx", "by") = true
 StringUtils.containsAny("aba","z")          = false

Parameters: str the String to check, may be null searchChars the chars to search for, may be null

Returns: the true if any of the chars are found, false if no match or null input

Since: 2.4

containsIgnoreCase

public static boolean containsIgnoreCase(String str, String searchStr)

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

containsNone

public static boolean containsNone(String str, char[] invalidChars)

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

containsNone

public static boolean containsNone(String str, String invalidChars)

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

containsOnly

public static boolean containsOnly(String str, char[] valid)

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

containsOnly

public static boolean containsOnly(String str, String validChars)

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

countMatches

public static int countMatches(String str, String sub)

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

defaultIfEmpty

public static String defaultIfEmpty(String str, String defaultStr)

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

defaultString

public static String defaultString(String str)

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)

defaultString

public static String defaultString(String str, String defaultStr)

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)

deleteSpaces

public static String deleteSpaces(String str)

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

deleteWhitespace

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

Parameters: str the String to delete whitespace from, may be null

Returns: the String without whitespaces, null if null String input

difference

public static String difference(String str1, String str2)

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

endsWith

public static boolean endsWith(String str, String suffix)

Check if a String ends with a specified suffix.

nulls are handled without exceptions. Two null references are considered to be equal. The comparison is case sensitive.

 StringUtils.endsWith(null, null)      = true
 StringUtils.endsWith(null, "abcdef")  = false
 StringUtils.endsWith("def", null)     = false
 StringUtils.endsWith("def", "abcdef") = true
 StringUtils.endsWith("def", "ABCDEF") = false

Parameters: str the String to check, may be null suffix the suffix to find, may be null

Returns: true if the String ends with the suffix, case sensitive, or both null

Since: 2.4

See Also: java.lang.String#endsWith(String)

endsWithIgnoreCase

public static boolean endsWithIgnoreCase(String str, String suffix)

Case insensitive check if a String ends with a specified suffix.

nulls are handled without exceptions. Two null references are considered to be equal. The comparison is case insensitive.

 StringUtils.endsWithIgnoreCase(null, null)      = true
 StringUtils.endsWithIgnoreCase(null, "abcdef")  = false
 StringUtils.endsWithIgnoreCase("def", null)     = false
 StringUtils.endsWithIgnoreCase("def", "abcdef") = true
 StringUtils.endsWithIgnoreCase("def", "ABCDEF") = false

Parameters: str the String to check, may be null suffix the suffix to find, may be null

Returns: true if the String ends with the suffix, case insensitive, or both null

Since: 2.4

See Also: java.lang.String#endsWith(String)

equals

public static boolean equals(String str1, String str2)

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

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)

equalsIgnoreCase

public static boolean equalsIgnoreCase(String str1, String str2)

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

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)

escape

public static String escape(String str)

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

getChomp

public static String getChomp(String str, String sep)

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

getCommonPrefix

public static String getCommonPrefix(String[] strs)

Compares all Strings in an array and returns the initial sequence of characters that is common to all of them.

For example, getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) -> "i am a "

 StringUtils.getCommonPrefix(null) = ""
 StringUtils.getCommonPrefix(new String[] {}) = ""
 StringUtils.getCommonPrefix(new String[] {"abc"}) = "abc"
 StringUtils.getCommonPrefix(new String[] {null, null}) = ""
 StringUtils.getCommonPrefix(new String[] {"", ""}) = ""
 StringUtils.getCommonPrefix(new String[] {"", null}) = ""
 StringUtils.getCommonPrefix(new String[] {"abc", null, null}) = ""
 StringUtils.getCommonPrefix(new String[] {null, null, "abc"}) = ""
 StringUtils.getCommonPrefix(new String[] {"", "abc"}) = ""
 StringUtils.getCommonPrefix(new String[] {"abc", ""}) = ""
 StringUtils.getCommonPrefix(new String[] {"abc", "abc"}) = "abc"
 StringUtils.getCommonPrefix(new String[] {"abc", "a"}) = "a"
 StringUtils.getCommonPrefix(new String[] {"ab", "abxyz"}) = "ab"
 StringUtils.getCommonPrefix(new String[] {"abcde", "abxyz"}) = "ab"
 StringUtils.getCommonPrefix(new String[] {"abcde", "xyz"}) = ""
 StringUtils.getCommonPrefix(new String[] {"xyz", "abcde"}) = ""
 StringUtils.getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) = "i am a "

Parameters: strs array of String objects, entries may be null

Returns: the initial sequence of characters that are common to all Strings in the array; empty String if the array is null, the elements are all null or if there is no common prefix.

Since: 2.4

getLevenshteinDistance

public 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.
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

getNestedString

public static String getNestedString(String str, String tag)

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

getNestedString

public static String getNestedString(String str, String open, String close)

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

getPrechomp

public static String getPrechomp(String str, String sep)

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

indexOf

public static int indexOf(String str, char searchChar)

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

indexOf

public static int indexOf(String str, char searchChar, int startPos)

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

indexOf

public static int indexOf(String str, String searchStr)

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

indexOf

public static int indexOf(String str, String searchStr, int startPos)

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

indexOfAny

public 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 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

indexOfAny

public 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 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

indexOfAny

public static int indexOfAny(String str, String[] searchStrs)

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

indexOfAnyBut

public 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 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

indexOfAnyBut

public 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 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

indexOfDifference

public static int indexOfDifference(String str1, String str2)

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

indexOfDifference

public static int indexOfDifference(String[] strs)

Compares all Strings in an array and returns the index at which the Strings begin to differ.

For example, indexOfDifference(new String[] {"i am a machine", "i am a robot"}) -> 7

 StringUtils.indexOfDifference(null) = -1
 StringUtils.indexOfDifference(new String[] {}) = -1
 StringUtils.indexOfDifference(new String[] {"abc"}) = -1
 StringUtils.indexOfDifference(new String[] {null, null}) = -1
 StringUtils.indexOfDifference(new String[] {"", ""}) = -1
 StringUtils.indexOfDifference(new String[] {"", null}) = 0
 StringUtils.indexOfDifference(new String[] {"abc", null, null}) = 0
 StringUtils.indexOfDifference(new String[] {null, null, "abc"}) = 0
 StringUtils.indexOfDifference(new String[] {"", "abc"}) = 0
 StringUtils.indexOfDifference(new String[] {"abc", ""}) = 0
 StringUtils.indexOfDifference(new String[] {"abc", "abc"}) = -1
 StringUtils.indexOfDifference(new String[] {"abc", "a"}) = 1
 StringUtils.indexOfDifference(new String[] {"ab", "abxyz"}) = 2
 StringUtils.indexOfDifference(new String[] {"abcde", "abxyz"}) = 2
 StringUtils.indexOfDifference(new String[] {"abcde", "xyz"}) = 0
 StringUtils.indexOfDifference(new String[] {"xyz", "abcde"}) = 0
 StringUtils.indexOfDifference(new String[] {"i am a machine", "i am a robot"}) = 7

Parameters: strs array of strings, entries may be null

Returns: the index where the strings begin to differ; -1 if they are all equal

Since: 2.4

isAlpha

public static boolean isAlpha(String str)

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

isAlphanumeric

public static boolean isAlphanumeric(String str)

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

isAlphanumericSpace

public static boolean isAlphanumericSpace(String str)

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

isAlphaSpace

public static boolean isAlphaSpace(String str)

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

isAsciiPrintable

public static boolean isAsciiPrintable(String str)

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

isBlank

public 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

Parameters: str the String to check, may be null

Returns: true if the String is null, empty or whitespace

Since: 2.0

isEmpty

public 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. 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

isNotBlank

public 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

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

isNotEmpty

public 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

Parameters: str the String to check, may be null

Returns: true if the String is not empty and not null

isNumeric

public static boolean isNumeric(String str)

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

isNumericSpace

public static boolean isNumericSpace(String str)

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

isWhitespace

public static boolean isWhitespace(String str)

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

join

public 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. 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

join

public 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. 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

join

public 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. 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

join

public 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. 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

join

public 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. 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

join

public static String join(Iterator iterator, char separator)

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

join

public static String join(Iterator iterator, String separator)

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

join

public static String join(Collection collection, char separator)

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

join

public static String join(Collection collection, String separator)

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

lastIndexOf

public static int lastIndexOf(String str, char searchChar)

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

lastIndexOf

public static int lastIndexOf(String str, char searchChar, int startPos)

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

lastIndexOf

public static int lastIndexOf(String str, String searchStr)

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

lastIndexOf

public static int lastIndexOf(String str, String searchStr, int startPos)

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

lastIndexOfAny

public static int lastIndexOfAny(String str, String[] searchStrs)

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

left

public static String left(String str, int len)

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

leftPad

public static String leftPad(String str, int size)

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




   leftPad
   public static  String leftPad(String str, int size, char padChar)
   
 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 



   leftPad
   public static  String leftPad(String str, int size, String padStr)
   
 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 



   length
   public static  int length(String str)
   
 Gets a String's length or 0 if the String is null.
Parameters: str
            a String or null 
Returns: String length or 0 if the String is null. 
Since: 2.4 



   lowerCase
   public static  String lowerCase(String str)
   
 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 



   mid
   public static  String mid(String str, int pos, int len)
   
 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 



   ordinalIndexOf
   public static  int ordinalIndexOf(String str, String searchStr, int ordinal)
   
 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 



   overlay
   public static  String overlay(String str, String overlay, int start, int end)
   
 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 



   overlayString
   public static  String overlayString(String text, String overlay, int start, int end)
   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 



   prechomp
   public static  String prechomp(String str, String sep)
   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 



   remove
   public static  String remove(String str, String remove)
   
 Removes all occurrences 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 



   remove
   public static  String remove(String str, char remove)
   
 Removes all occurrences 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 



   removeEnd
   public 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 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 



   removeEndIgnoreCase
   public static  String removeEndIgnoreCase(String str, String remove)
   
 Case insensitive removal of a substring 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 (case insensitive) and remove, may be null 
Returns: the substring with the string removed if found,
  null if null String input 
Since: 2.4 



   removeStart
   public 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 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 



   removeStartIgnoreCase
   public static  String removeStartIgnoreCase(String str, String remove)
   
 Case insensitive removal of a substring 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.removeStartIgnoreCase(null, *)      = null
 StringUtils.removeStartIgnoreCase("", *)        = ""
 StringUtils.removeStartIgnoreCase(*, null)      = *
 StringUtils.removeStartIgnoreCase("www.domain.com", "www.")   = "domain.com"
 StringUtils.removeStartIgnoreCase("www.domain.com", "WWW.")   = "domain.com"
 StringUtils.removeStartIgnoreCase("domain.com", "www.")       = "domain.com"
 StringUtils.removeStartIgnoreCase("www.domain.com", "domain") = "www.domain.com"
 StringUtils.removeStartIgnoreCase("abc", "")    = "abc"
 
Parameters: str  the source String to search, may be null remove  the String to search for (case insensitive) and remove, may be null 
Returns: the substring with the string removed if found,
  null if null String input 
Since: 2.4 



   repeat
   public static  String repeat(String str, int repeat)
   
 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 



   replace
   public static  String replace(String text, String searchString, String replacement)
   
 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 searchString  the String to search for, may be null replacement  the String to replace it with, may be null 
Returns: the text with any replacements processed,
  null if null String input 
See Also: StringUtils 



   replace
   public static  String replace(String text, String searchString, String replacement, int max)
   
 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 searchString  the String to search for, may be null replacement  the String to replace it 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 



   replaceChars
   public static  String replaceChars(String str, char searchChar, char replaceChar)
   
 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 



   replaceChars
   public static  String replaceChars(String str, String searchChars, String replaceChars)
   
 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 



   replaceEach
   public static  String replaceEach(String text, String[] searchList, String[] replacementList)
   
 
 Replaces all occurrences of Strings within another String.
 
 
 
 A null reference passed to this method is a no-op, or if
 any "search string" or "string to replace" is null, that replace will be
 ignored. This will not repeat. For repeating replaces, call the
 overloaded method.
 
 
   StringUtils.replaceEach(null, *, *)        = null
  StringUtils.replaceEach("", *, *)          = ""
  StringUtils.replaceEach("aba", null, null) = "aba"
  StringUtils.replaceEach("aba", new String[0], null) = "aba"
  StringUtils.replaceEach("aba", null, new String[0]) = "aba"
  StringUtils.replaceEach("aba", new String[]{"a"}, null)  = "aba"
  StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""})  = "b"
  StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"})  = "aba"
  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"})  = "wcte"
  (example of how it does not repeat)
  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"})  = "dcte"
 
Parameters: text
            text to search and replace in, no-op if null searchList
            the Strings to search for, no-op if null replacementList
            the Strings to replace them with, no-op if null 
Returns: the text with any replacements processed, null if
         null String input 
Throws: IndexOutOfBoundsException
             if the lengths of the arrays are not the same (null is ok,
             and/or size 0) 
Since: 2.4 



   replaceEachRepeatedly
   public static  String replaceEachRepeatedly(String text, String[] searchList, String[] replacementList)
   
 
 Replaces all occurrences of Strings within another String.
 
 
 
 A null reference passed to this method is a no-op, or if
 any "search string" or "string to replace" is null, that replace will be
 ignored. This will not repeat. For repeating replaces, call the
 overloaded method.
 
 
   StringUtils.replaceEach(null, *, *, *) = null
  StringUtils.replaceEach("", *, *, *) = ""
  StringUtils.replaceEach("aba", null, null, *) = "aba"
  StringUtils.replaceEach("aba", new String[0], null, *) = "aba"
  StringUtils.replaceEach("aba", null, new String[0], *) = "aba"
  StringUtils.replaceEach("aba", new String[]{"a"}, null, *) = "aba"
  StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""}, *) = "b"
  StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"}, *) = "aba"
  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"}, *) = "wcte"
  (example of how it repeats)
  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}, false) = "dcte"
  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}, true) = "tcte"
  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}, true) = IllegalArgumentException
  StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}, false) = "dcabe"
 
Parameters: text
            text to search and replace in, no-op if null searchList
            the Strings to search for, no-op if null replacementList
            the Strings to replace them with, no-op if null 
Returns: the text with any replacements processed, null if
         null String input 
Throws: IllegalArgumentException
             if the search is repeating and there is an endless loop due
             to outputs of one being inputs to another IndexOutOfBoundsException
             if the lengths of the arrays are not the same (null is ok,
             and/or size 0) 
Since: 2.4 



   replaceOnce
   public static  String replaceOnce(String text, String searchString, String replacement)
   
 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 searchString  the String to search for, may be null replacement  the String to replace with, may be null 
Returns: the text with any replacements processed,
  null if null String input 
See Also: StringUtils 



   reverse
   public static  String reverse(String str)
   
 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 



   reverseDelimited
   public 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.
 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 



   reverseDelimitedString
   public static  String reverseDelimitedString(String str, String separatorChars)
   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 



   right
   public static  String right(String str, int len)
   
 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 



   rightPad
   public static  String rightPad(String str, int size)
   
 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 



   rightPad
   public 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 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 



   rightPad
   public 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 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 



   split
   public static  String[] split(String str)
   
 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 



   split
   public static  String[] split(String str, char separatorChar)
   
 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 b c", ' ')    = ["a", "b", "c"]
 
Parameters: str  the String to parse, may be null separatorChar  the character used as the delimiter 
Returns: an array of parsed Strings, null if null String input 
Since: 2.0 



   split
   public static  String[] split(String str, String separatorChars)
   
 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 



   split
   public 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.
 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 



   splitByCharacterType
   public static  String[] splitByCharacterType(String str)
   
 Splits a String by Character type as returned by
 java.lang.Character.getType(char). Groups of contiguous
 characters of the same type are returned as complete tokens. 
 
 StringUtils.splitByCharacterType(null)         = null
 StringUtils.splitByCharacterType("")           = []
 StringUtils.splitByCharacterType("ab de fg")   = ["ab", " ", "de", " ", "fg"]
 StringUtils.splitByCharacterType("ab   de fg") = ["ab", "   ", "de", " ", "fg"]
 StringUtils.splitByCharacterType("ab:cd:ef")   = ["ab", ":", "cd", ":", "ef"]
 StringUtils.splitByCharacterType("number5")    = ["number", "5"]
 StringUtils.splitByCharacterType("fooBar")     = ["foo", "B", "ar"]
 StringUtils.splitByCharacterType("foo200Bar")  = ["foo", "200", "B", "ar"]
 StringUtils.splitByCharacterType("ASFRules")   = ["ASFR", "ules"]
 
Parameters: str the String to split, may be null 
Returns: an array of parsed Strings, null if null String input 
Since: 2.4 



   splitByCharacterTypeCamelCase
   public static  String[] splitByCharacterTypeCamelCase(String str)
   
 Splits a String by Character type as returned by
 java.lang.Character.getType(char). Groups of contiguous
 characters of the same type are returned as complete tokens, with the
 following exception: the character of type
 Character.UPPERCASE_LETTER, if any, immediately
 preceding a token of type Character.LOWERCASE_LETTER
 will belong to the following token rather than to the preceding, if any,
 Character.UPPERCASE_LETTER token. 
 
 StringUtils.splitByCharacterTypeCamelCase(null)         = null
 StringUtils.splitByCharacterTypeCamelCase("")           = []
 StringUtils.splitByCharacterTypeCamelCase("ab de fg")   = ["ab", " ", "de", " ", "fg"]
 StringUtils.splitByCharacterTypeCamelCase("ab   de fg") = ["ab", "   ", "de", " ", "fg"]
 StringUtils.splitByCharacterTypeCamelCase("ab:cd:ef")   = ["ab", ":", "cd", ":", "ef"]
 StringUtils.splitByCharacterTypeCamelCase("number5")    = ["number", "5"]
 StringUtils.splitByCharacterTypeCamelCase("fooBar")     = ["foo", "Bar"]
 StringUtils.splitByCharacterTypeCamelCase("foo200Bar")  = ["foo", "200", "Bar"]
 StringUtils.splitByCharacterTypeCamelCase("ASFRules")   = ["ASF", "Rules"]
 
Parameters: str the String to split, may be null 
Returns: an array of parsed Strings, null if null String input 
Since: 2.4 



   splitByWholeSeparator
   public 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.
 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 



   splitByWholeSeparator
   public static  String[] splitByWholeSeparator(String str, String separator, int max)
   
 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 



   splitByWholeSeparatorPreserveAllTokens
   public static  String[] splitByWholeSeparatorPreserveAllTokens(String str, String separator)
   
 Splits the provided text into an array, separator string specified. 

 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 separator splits on whitespace.

  StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *)               = null
 StringUtils.splitByWholeSeparatorPreserveAllTokens("", *)                 = []
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null)      = ["ab", "de", "fg"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null)    = ["ab", "", "", "de", "fg"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":")       = ["ab", "cd", "ef"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("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 
Since: 2.4 



   splitByWholeSeparatorPreserveAllTokens
   public static  String[] splitByWholeSeparatorPreserveAllTokens(String str, String separator, int max)
   
 Splits the provided text into an array, separator string specified.
 Returns a maximum of max substrings.

 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 separator splits on whitespace.

  StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *, *)               = null
 StringUtils.splitByWholeSeparatorPreserveAllTokens("", *, *)                 = []
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null, 0)      = ["ab", "de", "fg"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null, 0)    = ["ab", "", "", "de", "fg"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":", 2)       = ["ab", "cd:ef"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("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 
Since: 2.4 



   splitPreserveAllTokens
   public 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. 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 



   splitPreserveAllTokens
   public 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. 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 



   splitPreserveAllTokens
   public 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. 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 



   splitPreserveAllTokens
   public 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.
 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 



   startsWith
   public static  boolean startsWith(String str, String prefix)
   
 Check if a String starts with a specified prefix.

 nulls are handled without exceptions. Two null
 references are considered to be equal. The comparison is case sensitive.

  StringUtils.startsWith(null, null)      = true
 StringUtils.startsWith(null, "abcdef")  = false
 StringUtils.startsWith("abc", null)     = false
 StringUtils.startsWith("abc", "abcdef") = true
 StringUtils.startsWith("abc", "ABCDEF") = false
 
Parameters: str  the String to check, may be null prefix the prefix to find, may be null 
Returns: true if the String starts with the prefix, case sensitive, or
  both null 
Since: 2.4 
See Also: java.lang.String#startsWith(String) 



   startsWithIgnoreCase
   public static  boolean startsWithIgnoreCase(String str, String prefix)
   
 Case insensitive check if a String starts with a specified prefix.

 nulls are handled without exceptions. Two null
 references are considered to be equal. The comparison is case insensitive.

  StringUtils.startsWithIgnoreCase(null, null)      = true
 StringUtils.startsWithIgnoreCase(null, "abcdef")  = false
 StringUtils.startsWithIgnoreCase("abc", null)     = false
 StringUtils.startsWithIgnoreCase("abc", "abcdef") = true
 StringUtils.startsWithIgnoreCase("abc", "ABCDEF") = true
 
Parameters: str  the String to check, may be null prefix the prefix to find, may be null 
Returns: true if the String starts with the prefix, case insensitive, or
  both null 
Since: 2.4 
See Also: java.lang.String#startsWith(String) 



   strip
   public static  String strip(String str)
   
 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 



   strip
   public static  String strip(String str, String stripChars)
   
 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 



   stripAll
   public static  String[] stripAll(String[] strs)
   
 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 



   stripAll
   public 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.
 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 



   stripEnd
   public static  String stripEnd(String str, String stripChars)
   
 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 



   stripStart
   public static  String stripStart(String str, String stripChars)
   
 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 



   stripToEmpty
   public static  String stripToEmpty(String str)
   
 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 



   stripToNull
   public static  String stripToNull(String str)
   
 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 



   substring
   public 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 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 



   substring
   public 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 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 



   substringAfter
   public static  String substringAfter(String str, String separator)
   
 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 



   substringAfterLast
   public static  String substringAfterLast(String str, String separator)
   
 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 



   substringBefore
   public static  String substringBefore(String str, String separator)
   
 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 



   substringBeforeLast
   public static  String substringBeforeLast(String str, String separator)
   
 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 



   substringBetween
   public static  String substringBetween(String str, String tag)
   
 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 



   substringBetween
   public static  String substringBetween(String str, String open, String close)
   
 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 



   substringsBetween
   public 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 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 



   swapCase
   public 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.

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



   trim
   public static  String trim(String str)
   
 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 



   trimToEmpty
   public 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 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 



   trimToNull
   public static  String trimToNull(String str)
   
 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 



   uncapitalise
   public static  String uncapitalise(String str)
   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 



   uncapitalize
   public static  String uncapitalize(String str)
   
 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 



   upperCase
   public static  String upperCase(String str)
   
 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 


   
   
    
      Overview
      Package
      Class
      Use
      Tree
      Deprecated
      Index
      Help
    
    
      
       Prev Class
       Next Class
      
      
       Frames
       NoFrames
      
      All Classes
   
   
      Summary:
       Nested
       Field
       Constr
       Method
      
      Detail:
       Field
       Constr
       Method
      
   
    
     Core Language Utilities (Version 2.4)
    
    
   
   Copyright © 2001-2010 - Apache Software Foundation