On this page

StringUtils¶

public class org.apache.commons.lang3.StringUtils[source]¶

Operations on String that are null safe.

IsEmpty/IsBlank - checks if a String contains text
Trim/Strip - removes leading and trailing whitespace
Equals/Compare - compares two strings in a null-safe manner
startsWith - check if a String starts with a prefix in a null-safe manner
endsWith - check if a String ends with a suffix in a null-safe manner
IndexOf/LastIndexOf/Contains - null-safe index-of checks
IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut - index-of any of a set of Strings
ContainsOnly/ContainsNone/ContainsAny - checks if 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
AppendIfMissing - appends a suffix to the end of the String if not present
PrependIfMissing - prepends a prefix to the start of the String if not present
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
Rotate - rotate (circular shift) a String
Reverse/ReverseDelimited - reverses a String
Abbreviate - abbreviates a string using ellipses or another given String
Difference - compares Strings and reports on their differences
LevenshteinDistance - 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.

Methods in this class include sample code in their Javadoc comments to explain their operation. The symbol * is used to indicate any input including null.

#ThreadSafe#

See also:: String
Since:: 1.0

Constructors¶

StringUtils()

Deprecated. StringUtils instances should NOT be constructed in standard programming.

@Deprecated public StringUtils()[source]¶

Deprecated: TODO Make private in 4.0.

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.

Fields and constants¶

`CR`	A String for carriage return CR (“\r”).
`EMPTY`	The empty String `""`.
`INDEX_NOT_FOUND`	Represents a failed index search.
`LF`	A String for linefeed LF (“\n”).
`SPACE`	A String for a space character.

public static final String CR = "\r"[source]¶

A String for carriage return CR (“\r”).

See also:: JLF: Escape Sequences for Character and String Literals
Since:: 3.2

public static final String EMPTY = ""[source]¶

The empty String "".

Since:: 2.0

public static final int INDEX_NOT_FOUND = -1[source]¶

Represents a failed index search.

Since:: 2.1

public static final String LF = "\n"[source]¶

A String for linefeed LF (“\n”).

See also:: JLF: Escape Sequences for Character and String Literals
Since:: 3.2

public static final String SPACE = " "[source]¶

A String for a space character.

Since:: 3.2

Methods¶

`abbreviate(String, int)`	Abbreviates a String using ellipses.
`abbreviate(String, int, int)`	Abbreviates a String using ellipses.
`abbreviate(String, String, int)`	Abbreviates a String using another given String as replacement marker.
`abbreviate(String, String, int, int)`	Abbreviates a String using a given replacement marker.
`abbreviateMiddle(String, String, int)`	Abbreviates a String to the length passed, replacing the middle characters with the supplied replacement String.
`appendIfMissing(String, CharSequence, CharSequence[])`	Deprecated. Appends the suffix to the end of the string if the string does not already end with any of the suffixes.
`appendIfMissingIgnoreCase(String, CharSequence, CharSequence[])`	Deprecated. Appends the suffix to the end of the string if the string does not already end, case-insensitive, with any of the suffixes.
`capitalize(String)`	Capitalizes a String changing the first character to title case as per `Character#toTitleCase(int)`.
`center(String, int)`	Centers a String in a larger String of size `size` using the space character (’ ‘).
`center(String, int, char)`	Centers a String in a larger String of size `size`.
`center(String, int, String)`	Centers a String in a larger String of size `size`.
`chomp(String)`	Removes one newline from end of a String if it’s there, otherwise leave it alone.
`chomp(String, String)`	Deprecated. Removes `separator` from the end of `str` if it’s there, otherwise leave it alone.
`chop(String)`	Removes the last character from a String.
`compare(String, String)`	Deprecated. Compares two Strings lexicographically, as per `String#compareTo(String)`, returning :
`compare(String, String, boolean)`	Compares two Strings lexicographically, as per `String#compareTo(String)`, returning :
`compareIgnoreCase(String, String)`	Deprecated. Compares two Strings lexicographically, ignoring case differences, as per `String#compareToIgnoreCase(String)`, returning :
`compareIgnoreCase(String, String, boolean)`	Compares two Strings lexicographically, ignoring case differences, as per `String#compareToIgnoreCase(String)`, returning :
`contains(CharSequence, int)`	Tests if CharSequence contains a search character, handling `null`.
`contains(CharSequence, CharSequence)`	Deprecated. Tests if CharSequence contains a search CharSequence, handling `null`.
`containsAny(CharSequence, char[])`	Tests if the CharSequence contains any character in the given set of characters.
`containsAny(CharSequence, CharSequence)`	Tests if the CharSequence contains any character in the given set of characters.
`containsAny(CharSequence, CharSequence[])`	Deprecated. Tests if the CharSequence contains any of the CharSequences in the given array.
`containsAnyIgnoreCase(CharSequence, CharSequence[])`	Deprecated. Tests if the CharSequence contains any of the CharSequences in the given array, ignoring case.
`containsIgnoreCase(CharSequence, CharSequence)`	Deprecated. Tests if CharSequence contains a search CharSequence irrespective of case, handling `null`.
`containsNone(CharSequence, char[])`	Tests that the CharSequence does not contain certain characters.
`containsNone(CharSequence, String)`	Tests that the CharSequence does not contain certain characters.
`containsOnly(CharSequence, char[])`	Tests if the CharSequence contains only certain characters.
`containsOnly(CharSequence, String)`	Tests if the CharSequence contains only certain characters.
`containsWhitespace(CharSequence)`	Tests whether the given CharSequence contains any whitespace characters.
`countMatches(CharSequence, char)`	Counts how many times the char appears in the given string.
`countMatches(CharSequence, CharSequence)`	Counts how many times the substring appears in the larger string.
`defaultIfBlank(CharSequence, CharSequence)`	Returns either the passed in CharSequence, or if the CharSequence is `blank` (whitespaces, empty (`""`), or `null`), the value of `defaultStr`.
`defaultIfEmpty(CharSequence, CharSequence)`	Returns either the passed in CharSequence, or if the CharSequence is empty or `null`, the value of `defaultStr`.
`defaultString(String)`	Returns either the passed in String, or if the String is `null`, an empty String (“”).
`defaultString(String, String)`	Deprecated. Returns either the given String, or if the String is `null`, `nullDefault`.
`deleteWhitespace(String)`	Deletes all whitespaces from a String as defined by `Character#isWhitespace(char)`.
`difference(String, String)`	Compares two Strings, and returns the portion where they differ.
`endsWith(CharSequence, CharSequence)`	Deprecated. Tests if a CharSequence ends with a specified suffix.
`endsWithAny(CharSequence, CharSequence[])`	Deprecated. Tests if a CharSequence ends with any of the provided case-sensitive suffixes.
`endsWithIgnoreCase(CharSequence, CharSequence)`	Deprecated. Case-insensitive check if a CharSequence ends with a specified suffix.
`equals(CharSequence, CharSequence)`	Deprecated. Compares two CharSequences, returning `true` if they represent equal sequences of characters.
`equalsAny(CharSequence, CharSequence[])`	Deprecated. Compares given `string` to a CharSequences vararg of `searchStrings`, returning `true` if the `string` is equal to any of the `searchStrings`.
`equalsAnyIgnoreCase(CharSequence, CharSequence[])`	Deprecated. Compares given `string` to a CharSequences vararg of `searchStrings`, returning `true` if the `string` is equal to any of the `searchStrings`, ignoring case.
`equalsIgnoreCase(CharSequence, CharSequence)`	Deprecated. Compares two CharSequences, returning `true` if they represent equal sequences of characters, ignoring case.
`firstNonBlank(CharSequence[])`	Returns the first value in the array which is not empty (“”), `null` or whitespace only.
`firstNonEmpty(CharSequence[])`	Returns the first value in the array which is not empty.
`getBytes(String, String)`	Gets the bytes of the string using `String#getBytes(String)`, handling `null` safely.
`getBytes(String, Charset)`	Gets the bytes of the string using `String#getBytes(Charset)`, handling `null` safely.
`getCommonPrefix(String[])`	Gets the initial sequence of characters common to all strings in the array.
`getDigits(String)`	Gets the Unicode digits in `str`, concatenated in their original order.
`getFuzzyDistance(CharSequence, CharSequence, Locale)`	Deprecated. Gets the Fuzzy Distance which indicates the similarity score between two Strings.
`getIfBlank(CharSequence, Supplier)`	Gets either the passed in CharSequence, or if the CharSequence is `blank` (whitespaces, empty (`""`), or `null`), the value supplied by `defaultStrSupplier`.
`getIfEmpty(CharSequence, Supplier)`	Gets either the passed in CharSequence, or if the CharSequence is empty or `null`, the value supplied by `defaultStrSupplier`.
`getJaroWinklerDistance(CharSequence, CharSequence)`	Deprecated. Gets the Jaro Winkler Distance which indicates the similarity score between two Strings.
`getLevenshteinDistance(CharSequence, CharSequence)`	Deprecated. Gets the Levenshtein distance between two Strings.
`getLevenshteinDistance(CharSequence, CharSequence, int)`	Deprecated. Gets the Levenshtein distance between two Strings if it’s less than or equal to a given threshold.
`indexOf(CharSequence, int)`	Returns the index within `seq` of the first occurrence of the specified character.
`indexOf(CharSequence, int, int)`	Returns the index within `seq` of the first occurrence of the specified character, starting the search at the specified index.
`indexOf(CharSequence, CharSequence)`	Deprecated. Finds the first index within a CharSequence, handling `null`.
`indexOf(CharSequence, CharSequence, int)`	Deprecated. Finds the first index within a CharSequence, handling `null`.
`indexOfAny(CharSequence, char[])`	Search a CharSequence to find the first index of any character in the given set of characters.
`indexOfAny(CharSequence, int, char[])`	Search a CharSequence to find the first index of any character in the given set of characters.
`indexOfAny(CharSequence, CharSequence[])`	Find the first index of any of a set of potential substrings.
`indexOfAny(CharSequence, String)`	Search a CharSequence to find the first index of any character in the given set of characters.
`indexOfAnyBut(CharSequence, char[])`	Searches a CharSequence to find the first index of any character not in the given set of characters, i.e., find index i of first char in cs such that (cs.codePointAt(i) ∉ { x ∈ codepoints(searchChars) })
`indexOfAnyBut(CharSequence, CharSequence)`	Search a CharSequence to find the first index of any character not in the given set of characters, i.e., find index i of first char in seq such that (seq.codePointAt(i) ∉ { x ∈ codepoints(searchChars) })
`indexOfDifference(CharSequence, CharSequence)`	Compares two CharSequences, and returns the index at which the CharSequences begin to differ.
`indexOfDifference(CharSequence[])`	Compares all CharSequences in an array and returns the index at which the CharSequences begin to differ.
`indexOfIgnoreCase(CharSequence, CharSequence)`	Deprecated. Case insensitive find of the first index within a CharSequence.
`indexOfIgnoreCase(CharSequence, CharSequence, int)`	Deprecated. Case insensitive find of the first index within a CharSequence from the specified position.
`isAllBlank(CharSequence[])`	Tests if all of the CharSequences are empty (“”), null or whitespace only.
`isAllEmpty(CharSequence[])`	Tests if all of the CharSequences are empty (“”) or null.
`isAllLowerCase(CharSequence)`	Tests if the CharSequence contains only lowercase characters.
`isAllUpperCase(CharSequence)`	Tests if the CharSequence contains only uppercase characters.
`isAlpha(CharSequence)`	Tests if the CharSequence contains only Unicode letters.
`isAlphaSpace(CharSequence)`	Tests if the CharSequence contains only Unicode letters and space (’ ‘).
`isAlphanumeric(CharSequence)`	Tests if the CharSequence contains only Unicode letters or digits.
`isAlphanumericSpace(CharSequence)`	Tests if the CharSequence contains only Unicode letters, digits or space (`' '`).
`isAnyBlank(CharSequence[])`	Tests if any of the CharSequences are `blank` (whitespaces, empty (`""`), or `null`).
`isAnyEmpty(CharSequence[])`	Tests if any of the CharSequences are empty (“”) or null.
`isAsciiPrintable(CharSequence)`	Tests if the CharSequence contains only ASCII printable characters.
`isBlank(CharSequence)`	Tests if a CharSequence is empty (`"")`, null, or contains only whitespace as defined by `Character#isWhitespace(char)`.
`isEmpty(CharSequence)`	Tests if a CharSequence is empty (“”) or null.
`isMixedCase(CharSequence)`	Tests if the CharSequence contains mixed casing of both uppercase and lowercase characters.
`isNoneBlank(CharSequence[])`	Tests if none of the CharSequences are empty (“”), null or whitespace only.
`isNoneEmpty(CharSequence[])`	Tests if none of the CharSequences are empty (“”) or null.
`isNotBlank(CharSequence)`	Tests if a CharSequence is not `blank` (whitespaces, empty (`""`), or `null`).
`isNotEmpty(CharSequence)`	Tests if a CharSequence is not empty (“”) and not null.
`isNumeric(CharSequence)`	Tests if the CharSequence contains only Unicode digits.
`isNumericSpace(CharSequence)`	Tests if the CharSequence contains only Unicode digits or space (`' '`).
`isWhitespace(CharSequence)`	Tests if the CharSequence contains only whitespace.
`join(boolean[], char)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(boolean[], char, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(byte[], char)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(byte[], char, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(char[], char)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(char[], char, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(double[], char)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(double[], char, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(float[], char)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(float[], char, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(int[], char)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(int[], char, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(Iterable, char)`	Joins the elements of the provided `Iterable` into a single String containing the provided elements.
`join(Iterable, String)`	Joins the elements of the provided `Iterable` into a single String containing the provided elements.
`join(Object[])`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(Object[], char)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(Object[], char, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(Object[], String)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(Object[], String, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(Iterator, char)`	Joins the elements of the provided `Iterator` into a single String containing the provided elements.
`join(Iterator, String)`	Joins the elements of the provided `Iterator` into a single String containing the provided elements.
`join(List, char, int, int)`	Joins the elements of the provided `List` into a single String containing the provided list of elements.
`join(List, String, int, int)`	Joins the elements of the provided `List` into a single String containing the provided list of elements.
`join(long[], char)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(long[], char, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(short[], char)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`join(short[], char, int, int)`	Joins the elements of the provided array into a single String containing the provided list of elements.
`joinWith(String, Object[])`	Joins the elements of the provided varargs into a single String containing the provided elements.
`lastIndexOf(CharSequence, int)`	Returns the index within `seq` of the last occurrence of the specified character.
`lastIndexOf(CharSequence, int, int)`	Returns the index within `seq` of the last occurrence of the specified character, searching backward starting at the specified index.
`lastIndexOf(CharSequence, CharSequence)`	Deprecated. Finds the last index within a CharSequence, handling `null`.
`lastIndexOf(CharSequence, CharSequence, int)`	Deprecated. Finds the last index within a CharSequence, handling `null`.
`lastIndexOfAny(CharSequence, CharSequence[])`	Finds the latest index of any substring in a set of potential substrings.
`lastIndexOfIgnoreCase(CharSequence, CharSequence)`	Deprecated. Case insensitive find of the last index within a CharSequence.
`lastIndexOfIgnoreCase(CharSequence, CharSequence, int)`	Deprecated. Case insensitive find of the last index within a CharSequence from the specified position.
`lastOrdinalIndexOf(CharSequence, CharSequence, int)`	Finds the n-th last index within a String, handling `null`.
`left(String, int)`	Gets the leftmost `len` characters of a String.
`leftPad(String, int)`	Left pad a String with spaces (’ ‘).
`leftPad(String, int, char)`	Left pad a String with a specified character.
`leftPad(String, int, String)`	Left pad a String with a specified String.
`length(CharSequence)`	Gets a CharSequence length or `0` if the CharSequence is `null`.
`lowerCase(String)`	Converts a String to lower case as per `String#toLowerCase()`.
`lowerCase(String, Locale)`	Converts a String to lower case as per `String#toLowerCase(Locale)`.
`mid(String, int, int)`	Gets `len` characters from the middle of a String.
`normalizeSpace(String)`	Similar to https://www.w3.org/TR/xpath/#function-normalize -space
`ordinalIndexOf(CharSequence, CharSequence, int)`	Finds the n-th index within a CharSequence, handling `null`.
`overlay(String, String, int, int)`	Overlays part of a String with another String.
`prependIfMissing(String, CharSequence, CharSequence[])`	Deprecated. Prepends the prefix to the start of the string if the string does not already start with any of the prefixes.
`prependIfMissingIgnoreCase(String, CharSequence, CharSequence[])`	Deprecated. Prepends the prefix to the start of the string if the string does not already start, case-insensitive, with any of the prefixes.
`remove(String, char)`	Removes all occurrences of a character from within the source string.
`remove(String, String)`	Deprecated. Removes all occurrences of a substring from within the source string.
`removeAll(String, String)`	Deprecated. Removes each substring of the text String that matches the given regular expression.
`removeEnd(String, String)`	Deprecated. Removes a substring only if it is at the end of a source string, otherwise returns the source string.
`removeEndIgnoreCase(String, String)`	Deprecated. Case-insensitive removal of a substring if it is at the end of a source string, otherwise returns the source string.
`removeFirst(String, String)`	Deprecated. Removes the first substring of the text string that matches the given regular expression.
`removeIgnoreCase(String, String)`	Deprecated. Case-insensitive removal of all occurrences of a substring from within the source string.
`removePattern(String, String)`	Deprecated. Removes each substring of the source String that matches the given regular expression using the DOTALL option.
`removeStart(String, char)`	Removes a char only if it is at the beginning of a source string, otherwise returns the source string.
`removeStart(String, String)`	Deprecated. Removes a substring only if it is at the beginning of a source string, otherwise returns the source string.
`removeStartIgnoreCase(String, String)`	Deprecated. Case-insensitive removal of a substring if it is at the beginning of a source string, otherwise returns the source string.
`repeat(char, int)`	Returns padding using the specified delimiter repeated to a given length.
`repeat(String, int)`	Repeats a String `repeat` times to form a new String.
`repeat(String, String, int)`	Repeats a String `repeat` times to form a new String, with a String separator injected each time.
`replace(String, String, String)`	Deprecated. Replaces all occurrences of a String within another String.
`replace(String, String, String, int)`	Deprecated. Replaces a String with another String inside a larger String, for the first `max` values of the search String.
`replaceAll(String, String, String)`	Deprecated. Replaces each substring of the text String that matches the given regular expression with the given replacement.
`replaceChars(String, char, char)`	Replaces all occurrences of a character in a String with another.
`replaceChars(String, String, String)`	Replaces multiple characters in a String in one go.
`replaceEach(String, String[], String[])`	Replaces all occurrences of Strings within another String.
`replaceEachRepeatedly(String, String[], String[])`	Replaces all occurrences of Strings within another String.
`replaceFirst(String, String, String)`	Deprecated. Replaces the first substring of the text string that matches the given regular expression with the given replacement.
`replaceIgnoreCase(String, String, String)`	Deprecated. Case insensitively replaces all occurrences of a String within another String.
`replaceIgnoreCase(String, String, String, int)`	Deprecated. Case insensitively replaces a String with another String inside a larger String, for the first `max` values of the search String.
`replaceOnce(String, String, String)`	Deprecated. Replaces a String with another String inside a larger String, once.
`replaceOnceIgnoreCase(String, String, String)`	Deprecated. Case insensitively replaces a String with another String inside a larger String, once.
`replacePattern(String, String, String)`	Deprecated. Replaces each substring of the source String that matches the given regular expression with the given replacement using the `Pattern#DOTALL` option.
`reverse(String)`	Reverses a String as per `StringBuilder#reverse()`.
`reverseDelimited(String, char)`	Reverses a String that is delimited by a specific character.
`right(String, int)`	Gets the rightmost `len` characters of a String.
`rightPad(String, int)`	Right pad a String with spaces (’ ‘).
`rightPad(String, int, char)`	Right pad a String with a specified character.
`rightPad(String, int, String)`	Right pad a String with a specified String.
`rotate(String, int)`	Rotate (circular shift) a String of `shift` characters.
`split(String)`	Splits the provided text into an array, using whitespace as the separator.
`split(String, char)`	Splits the provided text into an array, separator specified.
`split(String, String)`	Splits the provided text into an array, separators specified.
`split(String, String, int)`	Splits the provided text into an array with a maximum length, separators specified.
`splitByCharacterType(String)`	Splits a String by Character type as returned by `Character#getType(int)`.
`splitByCharacterTypeCamelCase(String)`	Splits a String by Character type as returned by `Character#getType(int)`.
`splitByWholeSeparator(String, String)`	Splits the provided text into an array, separator string specified.
`splitByWholeSeparator(String, String, int)`	Splits the provided text into an array, separator string specified.
`splitByWholeSeparatorPreserveAllTokens(String, String)`	Splits the provided text into an array, separator string specified.
`splitByWholeSeparatorPreserveAllTokens(String, String, int)`	Splits the provided text into an array, separator string specified.
`splitPreserveAllTokens(String)`	Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators.
`splitPreserveAllTokens(String, char)`	Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators.
`splitPreserveAllTokens(String, String)`	Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators.
`splitPreserveAllTokens(String, String, int)`	Splits the provided text into an array with a maximum length, separators specified, preserving all tokens, including empty tokens created by adjacent separators.
`startsWith(CharSequence, CharSequence)`	Deprecated. Tests if a CharSequence starts with a specified prefix.
`startsWithAny(CharSequence, CharSequence[])`	Deprecated. Tests if a CharSequence starts with any of the provided case-sensitive prefixes.
`startsWithIgnoreCase(CharSequence, CharSequence)`	Deprecated. Case-insensitive check if a CharSequence starts with a specified prefix.
`strip(String)`	Strips whitespace from the start and end of a String.
`strip(String, String)`	Strips any of a set of characters from the start and end of a String.
`stripAccents(String)`	Removes diacritics (~= accents) from a string.
`stripAll(String[])`	Strips whitespace from the start and end of every String in an array.
`stripAll(String[], String)`	Strips any of a set of characters from the start and end of every String in an array.
`stripEnd(String, String)`	Strips any of a set of characters from the end of a String.
`stripStart(String, String)`	Strips any of a set of characters from the start of a String.
`stripToEmpty(String)`	Strips whitespace from the start and end of a String returning an empty String if `null` input.
`stripToNull(String)`	Strips whitespace from the start and end of a String returning `null` if the String is empty (“”) after the strip.
`substring(String, int)`	Gets a substring from the specified String avoiding exceptions.
`substring(String, int, int)`	Gets a substring from the specified String avoiding exceptions.
`substringAfter(String, int)`	Gets the substring after the first occurrence of a separator.
`substringAfter(String, String)`	Gets the substring after the first occurrence of a separator.
`substringAfterLast(String, int)`	Gets the substring after the last occurrence of a separator.
`substringAfterLast(String, String)`	Gets the substring after the last occurrence of a separator.
`substringBefore(String, int)`	Gets the substring before the first occurrence of a separator.
`substringBefore(String, String)`	Gets the substring before the first occurrence of a separator.
`substringBeforeLast(String, String)`	Gets the substring before the last occurrence of a separator.
`substringBetween(String, String)`	Gets the String that is nested in between two instances of the same String.
`substringBetween(String, String, String)`	Gets the String that is nested in between two Strings.
`substringsBetween(String, String, String)`	Searches a String for substrings delimited by a start and end tag, returning all matching substrings in an array.
`swapCase(String)`	Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
`toCodePoints(CharSequence)`	Converts a `CharSequence` into an array of code points.
`toEncodedString(byte[], Charset)`	Converts a `byte[]` to a String using the specified character encoding.
`toRootLowerCase(String)`	Converts the given source String as a lower-case using the `Locale#ROOT` locale in a null-safe manner.
`toRootUpperCase(String)`	Converts the given source String as an upper-case using the `Locale#ROOT` locale in a null-safe manner.
`toString(byte[], String)`	Deprecated. Converts a `byte[]` to a String using the specified character encoding.
`trim(String)`	Removes control characters plus space (char <= 32) from both ends of this String, handling `null` by returning `null`.
`trimAsciiControl(String)`	Removes `ASCII control characters` (char <= 31 or char == 127) from both ends of this String, handling `null` by returning `null`.
`trimToEmpty(String)`	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`.
`trimToNull(String)`	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`.
`truncate(String, int)`	Truncates a String.
`truncate(String, int, int)`	Truncates a String.
`uncapitalize(String)`	Uncapitalizes a String, changing the first character to lower case as per `Character#toLowerCase(int)`.
`unwrap(String, char)`	Unwraps a given string from a character.
`unwrap(String, String)`	Unwraps a given string from another string.
`upperCase(String)`	Converts a String to upper case as per `String#toUpperCase()`.
`upperCase(String, Locale)`	Converts a String to upper case as per `String#toUpperCase(Locale)`.
`valueOf(char[])`	Returns the string representation of the `char` array or null.
`wrap(String, char)`	Wraps a string with a char.
`wrap(String, String)`	Wraps a String with another String.
`wrapIfMissing(String, char)`	Wraps a string with a char if that char is missing from the start or end of the given string.
`wrapIfMissing(String, String)`	Wraps a string with a string if that string is missing from the start or end of the given string.

public static String abbreviate(String str, int maxWidth)[source]¶

Abbreviates a String using ellipses. This will convert “Now is the time for all good men” into “Now is the time for…”

Specifically:

If the number of characters in str is less than or equal to maxWidth, return str.
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) = Throws 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:

java.lang.IllegalArgumentException – Thrown if the width is too small.

Since:

2.0

public static String abbreviate(String str, int offset, int maxWidth)[source]¶

Abbreviates a String using ellipses. This will convert “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)        = Throws IllegalArgumentException.
StringUtils.abbreviate("abcdefghij", 5, 6)        = Throws 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:

java.lang.IllegalArgumentException – Thrown if the width is too small.

Since:

2.0

public static String abbreviate(String str, String abbrevMarker, int maxWidth)[source]¶

Abbreviates a String using another given String as replacement marker. This will convert “Now is the time for all good men” into “Now is the time for…” when “…” is the replacement marker.

Specifically:

If the number of characters in str is less than or equal to maxWidth, return str.
Else abbreviate it to (substring(str, 0, max - abbrevMarker.length) + abbrevMarker).
If maxWidth is less than abbrevMarker.length + 1, throw an IllegalArgumentException.
In no case will it return a String of length greater than maxWidth.

StringUtils.abbreviate(null, "...", *)      = null
StringUtils.abbreviate("abcdefg", null, *)  = "abcdefg"
StringUtils.abbreviate("", "...", 4)        = ""
StringUtils.abbreviate("abcdefg", ".", 5)   = "abcd."
StringUtils.abbreviate("abcdefg", ".", 7)   = "abcdefg"
StringUtils.abbreviate("abcdefg", ".", 8)   = "abcdefg"
StringUtils.abbreviate("abcdefg", "..", 4)  = "ab.."
StringUtils.abbreviate("abcdefg", "..", 3)  = "a.."
StringUtils.abbreviate("abcdefg", "..", 2)  = Throws IllegalArgumentException.
StringUtils.abbreviate("abcdefg", "...", 3) = Throws IllegalArgumentException.

Parameters:

str – The String to check, may be null.
abbrevMarker – The String used as replacement marker.
maxWidth – maximum length of result String, must be at least abbrevMarker.length + 1.

Returns:

abbreviated String, null if null String input.

Throws:

java.lang.IllegalArgumentException – Thrown if the width is too small.

Since:

3.6

public static String abbreviate(String str, String abbrevMarker, int offset, int maxWidth)[source]¶

Abbreviates a String using a given replacement marker. This will convert “Now is the time for all good men” into “…is the time for…” when “…” is the replacement marker.

Works like abbreviate(String, 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 replacement marker, 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, *, *)                 = null
StringUtils.abbreviate("abcdefghijklmno", null, *, *)    = "abcdefghijklmno"
StringUtils.abbreviate("", "...", 0, 4)                  = ""
StringUtils.abbreviate("abcdefghijklmno", "---", -1, 10) = "abcdefg---"
StringUtils.abbreviate("abcdefghijklmno", ",", 0, 10)    = "abcdefghi,"
StringUtils.abbreviate("abcdefghijklmno", ",", 1, 10)    = "abcdefghi,"
StringUtils.abbreviate("abcdefghijklmno", ",", 2, 10)    = "abcdefghi,"
StringUtils.abbreviate("abcdefghijklmno", "::", 4, 10)   = "::efghij::"
StringUtils.abbreviate("abcdefghijklmno", "...", 6, 10)  = "...ghij..."
StringUtils.abbreviate("abcdefghijklmno", "…", 6, 10)    = "…ghijklmno"
StringUtils.abbreviate("abcdefghijklmno", "*", 9, 10)    = "*ghijklmno"
StringUtils.abbreviate("abcdefghijklmno", "'", 10, 10)   = "'ghijklmno"
StringUtils.abbreviate("abcdefghijklmno", "!", 12, 10)   = "!ghijklmno"
StringUtils.abbreviate("abcdefghij", "abra", 0, 4)       = Throws IllegalArgumentException.
StringUtils.abbreviate("abcdefghij", "...", 5, 6)        = Throws IllegalArgumentException.

Parameters:

str – The String to check, may be null.
abbrevMarker – The String used as replacement marker, for example “…”, or Unicode HORIZONTAL ELLIPSIS, U+2026 ‘…’.
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:

java.lang.IllegalArgumentException – Thrown if the width is too small.

Since:

3.6

public static String abbreviateMiddle(String str, String middle, int length)[source]¶

Abbreviates a String to the length passed, replacing the middle characters with the supplied replacement String.

This abbreviation only occurs if the following criteria is met:

Neither the String for abbreviation nor the replacement String are null or empty
The length to truncate to is less than the length of the supplied String
The length to truncate to is greater than 0
The abbreviated String will have enough room for the length supplied replacement String and the first and last characters of the supplied String for abbreviation

Otherwise, the returned String will be the same as the supplied String for abbreviation.

StringUtils.abbreviateMiddle(null, null, 0)    = null
StringUtils.abbreviateMiddle("abc", null, 0)   = "abc"
StringUtils.abbreviateMiddle("abc", ".", 0)    = "abc"
StringUtils.abbreviateMiddle("abc", ".", 3)    = "abc"
StringUtils.abbreviateMiddle("abcdef", ".", 4) = "ab.f"

Parameters:

str – The String to abbreviate, may be null.
middle – The String to replace the middle characters with, may be null.
length – The length to abbreviate str to.

Returns:

The abbreviated String if the above criteria is met, or the original String supplied for abbreviation.

Since:

2.5

@Deprecated public static String appendIfMissing(String str, CharSequence suffix, CharSequence... suffixes)[source]¶

Deprecated: Use Strings.CS.appendIfMissing(String, CharSequence, CharSequence...).

Appends the suffix to the end of the string if the string does not already end with any of the suffixes.

StringUtils.appendIfMissing(null, null)      = null
StringUtils.appendIfMissing("abc", null)     = "abc"
StringUtils.appendIfMissing("", "xyz")       = "xyz"
StringUtils.appendIfMissing("abc", "xyz")    = "abcxyz"
StringUtils.appendIfMissing("abcxyz", "xyz") = "abcxyz"
StringUtils.appendIfMissing("abcXYZ", "xyz") = "abcXYZxyz"

With additional suffixes,

StringUtils.appendIfMissing(null, null, null)       = null
StringUtils.appendIfMissing("abc", null, null)      = "abc"
StringUtils.appendIfMissing("", "xyz", null)        = "xyz"
StringUtils.appendIfMissing("abc", "xyz", new CharSequence[]{null}) = "abcxyz"
StringUtils.appendIfMissing("abc", "xyz", "")       = "abc"
StringUtils.appendIfMissing("abc", "xyz", "mno")    = "abcxyz"
StringUtils.appendIfMissing("abcxyz", "xyz", "mno") = "abcxyz"
StringUtils.appendIfMissing("abcmno", "xyz", "mno") = "abcmno"
StringUtils.appendIfMissing("abcXYZ", "xyz", "mno") = "abcXYZxyz"
StringUtils.appendIfMissing("abcMNO", "xyz", "mno") = "abcMNOxyz"

Parameters:

str – The string.
suffix – The suffix to append to the end of the string.
suffixes – Additional suffixes that are valid terminators.

Returns:

A new String if suffix was appended, the same string otherwise.

Since:

3.2

@Deprecated public static String appendIfMissingIgnoreCase(String str, CharSequence suffix, CharSequence... suffixes)[source]¶

Deprecated: Use Strings.CI.appendIfMissing(String, CharSequence, CharSequence...).

Appends the suffix to the end of the string if the string does not already end, case-insensitive, with any of the suffixes.

StringUtils.appendIfMissingIgnoreCase(null, null)      = null
StringUtils.appendIfMissingIgnoreCase("abc", null)     = "abc"
StringUtils.appendIfMissingIgnoreCase("", "xyz")       = "xyz"
StringUtils.appendIfMissingIgnoreCase("abc", "xyz")    = "abcxyz"
StringUtils.appendIfMissingIgnoreCase("abcxyz", "xyz") = "abcxyz"
StringUtils.appendIfMissingIgnoreCase("abcXYZ", "xyz") = "abcXYZ"

With additional suffixes,

StringUtils.appendIfMissingIgnoreCase(null, null, null)       = null
StringUtils.appendIfMissingIgnoreCase("abc", null, null)      = "abc"
StringUtils.appendIfMissingIgnoreCase("", "xyz", null)        = "xyz"
StringUtils.appendIfMissingIgnoreCase("abc", "xyz", new CharSequence[]{null}) = "abcxyz"
StringUtils.appendIfMissingIgnoreCase("abc", "xyz", "")       = "abc"
StringUtils.appendIfMissingIgnoreCase("abc", "xyz", "mno")    = "abcxyz"
StringUtils.appendIfMissingIgnoreCase("abcxyz", "xyz", "mno") = "abcxyz"
StringUtils.appendIfMissingIgnoreCase("abcmno", "xyz", "mno") = "abcmno"
StringUtils.appendIfMissingIgnoreCase("abcXYZ", "xyz", "mno") = "abcXYZ"
StringUtils.appendIfMissingIgnoreCase("abcMNO", "xyz", "mno") = "abcMNO"

Parameters:

str – The string.
suffix – The suffix to append to the end of the string.
suffixes – Additional suffixes that are valid terminators.

Returns:

A new String if suffix was appended, the same string otherwise.

Since:

3.2

public static String capitalize(String str)[source]¶

Capitalizes a String changing the first character to title case as per Character#toTitleCase(int). No other characters are changed.

For a word based algorithm, see org.apache.commons.text.WordUtils#capitalize(String). A null input String returns null.

StringUtils.capitalize(null)    = null
StringUtils.capitalize("")      = ""
StringUtils.capitalize("cat")   = "Cat"
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.

See also:

org.apache.commons.text.WordUtils#capitalize(String)
#uncapitalize(String)

Since:

2.0

public static String center(String str, int size)[source]¶

Centers a String in a larger String of size size using the space character (’ ‘).

If the size is less than the String length, the original 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.

public static String center(String str, int size, char padChar)[source]¶

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

public static String center(String str, int size, String padStr)[source]¶

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:

java.lang.IllegalArgumentException – Thrown if padStr is null or empty.

public static String chomp(String str)[source]¶

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.

@Deprecated public static String chomp(String str, String separator)[source]¶

Deprecated: This feature will be removed in Lang 4, use StringUtils#removeEnd(String, String) instead.

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 #substringBeforeLast(String, String). This method uses String#endsWith(String).

StringUtils.chomp(null, *)         = null
StringUtils.chomp("", *)           = ""
StringUtils.chomp("foobar", "bar") = "foo"
StringUtils.chomp("foobar", "baz") = "foobar"
StringUtils.chomp("foo", "foo")    = ""
StringUtils.chomp("foo ", "foo")   = "foo "
StringUtils.chomp(" foo", "foo")   = " "
StringUtils.chomp("foo", "foooo")  = "foo"
StringUtils.chomp("foo", "")       = "foo"
StringUtils.chomp("foo", null)     = "foo"

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.

public static String chop(String str)[source]¶

Removes the last character from a String.

If the String ends in \r\n, then remove both of them.

StringUtils.chop(null)          = null
StringUtils.chop("")            = ""
StringUtils.chop("abc \r")      = "abc "
StringUtils.chop("abc\n")       = "abc"
StringUtils.chop("abc\r\n")     = "abc"
StringUtils.chop("abc")         = "ab"
StringUtils.chop("abc\nabc")    = "abc\nab"
StringUtils.chop("a")           = ""
StringUtils.chop("\r")          = ""
StringUtils.chop("\n")          = ""
StringUtils.chop("\r\n")        = ""

Parameters:: str – The String to chop last character from, may be null.
Returns:: String without last character, null if null String input.

@Deprecated public static int compare(String str1, String str2)[source]¶

Deprecated: Use Strings.CS.compare(String, String).

Compares two Strings lexicographically, as per String#compareTo(String), returning :

int = 0, if str1 is equal to str2 (or both null)
int < 0, if str1 is less than str2
int > 0, if str1 is greater than str2

This is a null safe version of:

str1.compareTo(str2)

null value is considered less than non-null value. Two null references are considered equal.

StringUtils.compare(null, null)   = 0
StringUtils.compare(null , "a")   < 0
StringUtils.compare("a", null)   > 0
StringUtils.compare("abc", "abc") = 0
StringUtils.compare("a", "b")     < 0
StringUtils.compare("b", "a")     > 0
StringUtils.compare("a", "B")     > 0
StringUtils.compare("ab", "abc")  < 0

Parameters:

str1 – The String to compare from.
str2 – The String to compare to.

Returns:

< 0, 0, > 0, if str1 is respectively less, equal or greater than str2.

See also:

Since:

3.5

public static int compare(String str1, String str2, boolean nullIsLess)[source]¶

Compares two Strings lexicographically, as per String#compareTo(String), returning :

int = 0, if str1 is equal to str2 (or both null)
int < 0, if str1 is less than str2
int > 0, if str1 is greater than str2

This is a null safe version of :

str1.compareTo(str2)

null inputs are handled according to the nullIsLess parameter. Two null references are considered equal.

StringUtils.compare(null, null, *)     = 0
StringUtils.compare(null , "a", true)  < 0
StringUtils.compare(null , "a", false) > 0
StringUtils.compare("a", null, true)   > 0
StringUtils.compare("a", null, false)  < 0
StringUtils.compare("abc", "abc", *)   = 0
StringUtils.compare("a", "b", *)       < 0
StringUtils.compare("b", "a", *)       > 0
StringUtils.compare("a", "B", *)       > 0
StringUtils.compare("ab", "abc", *)    < 0

Parameters:

str1 – The String to compare from.
str2 – The String to compare to.
nullIsLess – whether consider null value less than non-null value.

Returns:

< 0, 0, > 0, if str1 is respectively less, equal ou greater than str2.

See also:

String#compareTo(String)

Since:

3.5

@Deprecated public static int compareIgnoreCase(String str1, String str2)[source]¶

Deprecated: Use Strings.CI.compare(String, String).

Compares two Strings lexicographically, ignoring case differences, as per String#compareToIgnoreCase(String), returning :

int = 0, if str1 is equal to str2 (or both null)
int < 0, if str1 is less than str2
int > 0, if str1 is greater than str2

This is a null safe version of:

str1.compareToIgnoreCase(str2)

null value is considered less than non-null value. Two null references are considered equal. Comparison is case insensitive.

StringUtils.compareIgnoreCase(null, null)   = 0
StringUtils.compareIgnoreCase(null , "a")   < 0
StringUtils.compareIgnoreCase("a", null)    > 0
StringUtils.compareIgnoreCase("abc", "abc") = 0
StringUtils.compareIgnoreCase("abc", "ABC") = 0
StringUtils.compareIgnoreCase("a", "b")     < 0
StringUtils.compareIgnoreCase("b", "a")     > 0
StringUtils.compareIgnoreCase("a", "B")     < 0
StringUtils.compareIgnoreCase("A", "b")     < 0
StringUtils.compareIgnoreCase("ab", "ABC")  < 0

Parameters:

str1 – The String to compare from.
str2 – The String to compare to.

Returns:

< 0, 0, > 0, if str1 is respectively less, equal ou greater than str2, ignoring case differences.

See also:

Since:

3.5

public static int compareIgnoreCase(String str1, String str2, boolean nullIsLess)[source]¶

Compares two Strings lexicographically, ignoring case differences, as per String#compareToIgnoreCase(String), returning :

int = 0, if str1 is equal to str2 (or both null)
int < 0, if str1 is less than str2
int > 0, if str1 is greater than str2

This is a null safe version of :

str1.compareToIgnoreCase(str2)

null inputs are handled according to the nullIsLess parameter. Two null references are considered equal. Comparison is case insensitive.

StringUtils.compareIgnoreCase(null, null, *)     = 0
StringUtils.compareIgnoreCase(null , "a", true)  < 0
StringUtils.compareIgnoreCase(null , "a", false) > 0
StringUtils.compareIgnoreCase("a", null, true)   > 0
StringUtils.compareIgnoreCase("a", null, false)  < 0
StringUtils.compareIgnoreCase("abc", "abc", *)   = 0
StringUtils.compareIgnoreCase("abc", "ABC", *)   = 0
StringUtils.compareIgnoreCase("a", "b", *)       < 0
StringUtils.compareIgnoreCase("b", "a", *)       > 0
StringUtils.compareIgnoreCase("a", "B", *)       < 0
StringUtils.compareIgnoreCase("A", "b", *)       < 0
StringUtils.compareIgnoreCase("ab", "abc", *)    < 0

Parameters:

str1 – The String to compare from.
str2 – The String to compare to.
nullIsLess – whether consider null value less than non-null value.

Returns:

< 0, 0, > 0, if str1 is respectively less, equal ou greater than str2, ignoring case differences.

See also:

String#compareToIgnoreCase(String)

Since:

3.5

public static boolean contains(CharSequence seq, int searchChar)[source]¶

Tests if CharSequence contains a search character, handling null. This method uses String#indexOf(int) if possible.

A null or empty (“”) CharSequence will return false.

StringUtils.contains(null, *)    = false
StringUtils.contains("", *)      = false
StringUtils.contains("abc", 'a') = true
StringUtils.contains("abc", 'z') = false

Parameters:

seq – The CharSequence to check, may be null
searchChar – The character to find

Returns:

true if the CharSequence contains the search character, false if not or null string input

Since:

3.0 Changed signature from contains(String, int) to contains(CharSequence, int)

@Deprecated public static boolean contains(CharSequence seq, CharSequence searchSeq)[source]¶

Deprecated: Use Strings.CS.contains(CharSequence, CharSequence).

Tests if CharSequence contains a search CharSequence, handling null. This method uses String#indexOf(String) if possible.

A null CharSequence 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:

seq – The CharSequence to check, may be null
searchSeq – The CharSequence to find, may be null

Returns:

true if the CharSequence contains the search CharSequence, false if not or null string input

Since:

3.0 Changed signature from contains(String, String) to contains(CharSequence, CharSequence)

public static boolean containsAny(CharSequence cs, char... searchChars)[source]¶

Tests if the CharSequence contains any character in the given set of characters.

A null CharSequence 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("zzabyycdxx", 'z', 'y')   = true
StringUtils.containsAny("aba", 'z])               = false

Parameters:

cs – The CharSequence 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:

3.0 Changed signature from containsAny(String, char[]) to containsAny(CharSequence, char…)

public static boolean containsAny(CharSequence cs, CharSequence searchChars)[source]¶

Tests if the CharSequence contains any character in the given set of characters.

A null CharSequence will return false. A null search CharSequence 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("zzabyycdxx", "zy")    = true
StringUtils.containsAny("zzabyycdxx", "\tx")   = true
StringUtils.containsAny("zzabyycdxx", "$.#yF") = true
StringUtils.containsAny("aba", "z")            = false

Parameters:

cs – The CharSequence 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:

3.0 Changed signature from containsAny(String, String) to containsAny(CharSequence, CharSequence)

@Deprecated public static boolean containsAny(CharSequence cs, CharSequence... searchCharSequences)[source]¶

Deprecated: Use Strings.CS.containsAny(CharSequence, CharSequence...).

Tests if the CharSequence contains any of the CharSequences in the given array.

A null cs CharSequence 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("abcd", "ab", null) = true
StringUtils.containsAny("abcd", "ab", "cd") = true
StringUtils.containsAny("abc", "d", "abc")  = true

Parameters:

cs – The CharSequence to check, may be null.
searchCharSequences – The array of CharSequences to search for, may be null. Individual CharSequences may be null as well.

Returns:

true if any of the search CharSequences are found, false otherwise.

Since:

3.4

@Deprecated public static boolean containsAnyIgnoreCase(CharSequence cs, CharSequence... searchCharSequences)[source]¶

Deprecated: Use Strings.CI.containsAny(CharSequence, CharSequence...).

Tests if the CharSequence contains any of the CharSequences in the given array, ignoring case.

A null cs CharSequence 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("abcd", "ab", null) = true
StringUtils.containsAny("abcd", "ab", "cd") = true
StringUtils.containsAny("abc", "d", "abc")  = true
StringUtils.containsAny("abc", "D", "ABC")  = true
StringUtils.containsAny("ABC", "d", "abc")  = true

Parameters:

cs – The CharSequence to check, may be null.
searchCharSequences – The array of CharSequences to search for, may be null. Individual CharSequences may be null as well.

Returns:

true if any of the search CharSequences are found, false otherwise

Since:

3.12.0

@Deprecated public static boolean containsIgnoreCase(CharSequence str, CharSequence searchStr)[source]¶

Deprecated: Use Strings.CI.contains(CharSequence, CharSequence).

Tests if CharSequence contains a search CharSequence irrespective of case, handling null. Case-insensitivity is defined as by String#equalsIgnoreCase(String).

A null CharSequence will return false.

StringUtils.containsIgnoreCase(null, *)    = false
StringUtils.containsIgnoreCase(*, null)    = false
StringUtils.containsIgnoreCase("", "")     = true
StringUtils.containsIgnoreCase("abc", "")  = true
StringUtils.containsIgnoreCase("abc", "a") = true
StringUtils.containsIgnoreCase("abc", "z") = false
StringUtils.containsIgnoreCase("abc", "A") = true
StringUtils.containsIgnoreCase("abc", "Z") = false

Parameters:

str – The CharSequence to check, may be null.
searchStr – The CharSequence to find, may be null.

Returns:

true if the CharSequence contains the search CharSequence irrespective of case or false if not or null string input.

Since:

3.0 Changed signature from containsIgnoreCase(String, String) to containsIgnoreCase(CharSequence, CharSequence).

public static boolean containsNone(CharSequence cs, char... searchChars)[source]¶

Tests that the CharSequence does not contain certain characters.

A null CharSequence will return true. A null invalid character array will return true. An empty CharSequence (length()=0) always returns true.

StringUtils.containsNone(null, *)               = true
StringUtils.containsNone(*, null)               = true
StringUtils.containsNone("", *)                 = true
StringUtils.containsNone("ab", '')              = true
StringUtils.containsNone("abab", 'x', 'y', 'z') = true
StringUtils.containsNone("ab1", 'x', 'y', 'z')  = true
StringUtils.containsNone("abz", 'x', 'y', 'z')  = false

Parameters:

cs – The CharSequence to check, may be null.
searchChars – An array of invalid chars, may be null.

Returns:

true if it contains none of the invalid chars, or is null.

Since:

3.0 Changed signature from containsNone(String, char[]) to containsNone(CharSequence, char…)

public static boolean containsNone(CharSequence cs, String invalidChars)[source]¶

Tests that the CharSequence does not contain certain characters.

A null CharSequence 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:

cs – The CharSequence 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:

3.0 Changed signature from containsNone(String, String) to containsNone(CharSequence, String)

public static boolean containsOnly(CharSequence cs, char... valid)[source]¶

Tests if the CharSequence contains only certain characters.

A null CharSequence will return false. A null valid character array will return false. An empty CharSequence (length()=0) always returns true.

StringUtils.containsOnly(null, *)               = false
StringUtils.containsOnly(*, null)               = false
StringUtils.containsOnly("", *)                 = true
StringUtils.containsOnly("ab", '')              = false
StringUtils.containsOnly("abab", 'a', 'b', 'c') = true
StringUtils.containsOnly("ab1", 'a', 'b', 'c')  = false
StringUtils.containsOnly("abz", 'a', 'b', 'c')  = false

Parameters:

cs – 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.

Since:

3.0 Changed signature from containsOnly(String, char[]) to containsOnly(CharSequence, char…)

public static boolean containsOnly(CharSequence cs, String validChars)[source]¶

Tests if the CharSequence contains only certain characters.

A null CharSequence will return false. A null valid character String will return false. An empty String (length()=0) 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:

cs – The CharSequence 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:

3.0 Changed signature from containsOnly(String, String) to containsOnly(CharSequence, String)

public static boolean containsWhitespace(CharSequence seq)[source]¶

Tests whether the given CharSequence contains any whitespace characters.

Whitespace is defined by Character#isWhitespace(char).

StringUtils.containsWhitespace(null)       = false
StringUtils.containsWhitespace("")         = false
StringUtils.containsWhitespace("ab")       = false
StringUtils.containsWhitespace(" ab")      = true
StringUtils.containsWhitespace("a b")      = true
StringUtils.containsWhitespace("ab ")      = true

Parameters:: seq – The CharSequence to check (may be null).
Returns:: true if the CharSequence is not empty and contains at least 1 (breaking) whitespace character.
Since:: 3.0

public static int countMatches(CharSequence str, char ch)[source]¶

Counts how many times the char appears in the given string.

A null or empty (“”) String input returns 0.

StringUtils.countMatches(null, *)     = 0
StringUtils.countMatches("", *)       = 0
StringUtils.countMatches("abba", 0)   = 0
StringUtils.countMatches("abba", 'a') = 2
StringUtils.countMatches("abba", 'b') = 2
StringUtils.countMatches("abba", 'x') = 0

Parameters:

str – The CharSequence to check, may be null.
ch – The char to count.

Returns:

The number of occurrences, 0 if the CharSequence is null.

Since:

3.4

public static int countMatches(CharSequence str, CharSequence sub)[source]¶

Counts how many times the substring appears in the larger string. Note that the code only counts non-overlapping matches.

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
StringUtils.countMatches("ababa", "aba") = 1

Parameters:

str – The CharSequence to check, may be null.
sub – The substring to count, may be null.

Returns:

The number of occurrences, 0 if either CharSequence is null.

Since:

3.0 Changed signature from countMatches(String, String) to countMatches(CharSequence, CharSequence)

public static <T extends CharSequence> T defaultIfBlank(T str, T defaultStr)[source]¶

Returns either the passed in CharSequence, or if the CharSequence is blank (whitespaces, empty (""), or null), the value of defaultStr.

Whitespace is defined by Character#isWhitespace(char).

StringUtils.defaultIfBlank(null, "NULL")  = "NULL"
StringUtils.defaultIfBlank("", "NULL")    = "NULL"
StringUtils.defaultIfBlank(" ", "NULL")   = "NULL"
StringUtils.defaultIfBlank("bat", "NULL") = "bat"
StringUtils.defaultIfBlank("", null)      = null

Type parameters:

<T> – the specific kind of CharSequence.

Parameters:

str – The CharSequence to check, may be null.
defaultStr – The default CharSequence to return if str is blank (whitespaces, empty (""), or null); may be null.

Returns:

The passed in CharSequence, or the default.

See also:

StringUtils#defaultString(String, String)
#isBlank(CharSequence)

public static <T extends CharSequence> T defaultIfEmpty(T str, T defaultStr)[source]¶

Returns either the passed in CharSequence, or if the CharSequence is empty or null, the value of defaultStr.

StringUtils.defaultIfEmpty(null, "NULL")  = "NULL"
StringUtils.defaultIfEmpty("", "NULL")    = "NULL"
StringUtils.defaultIfEmpty(" ", "NULL")   = " "
StringUtils.defaultIfEmpty("bat", "NULL") = "bat"
StringUtils.defaultIfEmpty("", null)      = null

Type parameters:

<T> – the specific kind of CharSequence.

Parameters:

str – The CharSequence to check, may be null.
defaultStr – The default CharSequence to return if the input is empty (“”) or null, may be null.

Returns:

The passed in CharSequence, or the default.

public static String defaultString(String str)[source]¶

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:

@Deprecated public static String defaultString(String str, String nullDefault)[source]¶

Deprecated: Use Objects#toString(Object, String).

Returns either the given String, or if the String is null, nullDefault.

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

Since this is now provided by Java, instead call Objects#toString(Object, String):

Objects.toString(null, "NULL")  = "NULL"
Objects.toString("", "NULL")    = ""
Objects.toString("bat", "NULL") = "bat"

Parameters:

str – The String to check, may be null.
nullDefault – 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:

public static String deleteWhitespace(String str)[source]¶

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.

public static String difference(String str1, String str2)[source]¶

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. This means that the difference between “abc” and “ab” is the empty String and not “c”.

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

@Deprecated public static boolean endsWith(CharSequence str, CharSequence suffix)[source]¶

Deprecated: Use Strings.CS.endsWith(CharSequence, CharSequence).

Tests if a CharSequence 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, "def")     = false
StringUtils.endsWith("abcdef", null)  = false
StringUtils.endsWith("abcdef", "def") = true
StringUtils.endsWith("ABCDEF", "def") = false
StringUtils.endsWith("ABCDEF", "cde") = false
StringUtils.endsWith("ABCDEF", "")    = true

Parameters:

str – The CharSequence to check, may be null.
suffix – The suffix to find, may be null.

Returns:

true if the CharSequence ends with the suffix, case-sensitive, or both null.

See also:

String#endsWith(String)

Since:

3.0 Changed signature from endsWith(String, String) to endsWith(CharSequence, CharSequence)

@Deprecated public static boolean endsWithAny(CharSequence sequence, CharSequence... searchStrings)[source]¶

Deprecated: Use Strings.CS.endsWithAny(CharSequence, CharSequence...).

Tests if a CharSequence ends with any of the provided case-sensitive suffixes.

StringUtils.endsWithAny(null, null)                  = false
StringUtils.endsWithAny(null, new String[] {"abc"})  = false
StringUtils.endsWithAny("abcxyz", null)              = false
StringUtils.endsWithAny("abcxyz", new String[] {""}) = true
StringUtils.endsWithAny("abcxyz", new String[] {"xyz"}) = true
StringUtils.endsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
StringUtils.endsWithAny("abcXYZ", "def", "XYZ")      = true
StringUtils.endsWithAny("abcXYZ", "def", "xyz")      = false

Parameters:

sequence – The CharSequence to check, may be null.
searchStrings – The case-sensitive CharSequences to find, may be empty or contain null.

Returns:

true if the input sequence is null AND no searchStrings are provided, or the input sequence ends in any of the provided case-sensitive searchStrings.

Since:

3.0

@Deprecated public static boolean endsWithIgnoreCase(CharSequence str, CharSequence suffix)[source]¶

Deprecated: Use Strings.CI.endsWith(CharSequence, CharSequence).

Case-insensitive check if a CharSequence 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, "def")     = false
StringUtils.endsWithIgnoreCase("abcdef", null)  = false
StringUtils.endsWithIgnoreCase("abcdef", "def") = true
StringUtils.endsWithIgnoreCase("ABCDEF", "def") = true
StringUtils.endsWithIgnoreCase("ABCDEF", "cde") = false

Parameters:

str – The CharSequence to check, may be null
suffix – The suffix to find, may be null

Returns:

true if the CharSequence ends with the suffix, case-insensitive, or both null

See also:

String#endsWith(String)

Since:

3.0 Changed signature from endsWithIgnoreCase(String, String) to endsWithIgnoreCase(CharSequence, CharSequence)

@Deprecated public static boolean equals(CharSequence cs1, CharSequence cs2)[source]¶

Deprecated: Use Strings.CS.equals(CharSequence, CharSequence).

Compares two CharSequences, returning true if they represent equal sequences of characters.

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:

cs1 – The first CharSequence, may be null.
cs2 – The second CharSequence, may be null.

Returns:

true if the CharSequences are equal (case-sensitive), or both null.

Since:

3.0 Changed signature from equals(String, String) to equals(CharSequence, CharSequence)

See also:

Object#equals(Object)
#equalsIgnoreCase(CharSequence, CharSequence)

@Deprecated public static boolean equalsAny(CharSequence string, CharSequence... searchStrings)[source]¶

Deprecated: Use Strings.CS.equalsAny(CharSequence, CharSequence...).

Compares given string to a CharSequences vararg of searchStrings, returning true if the string is equal to any of the searchStrings.

StringUtils.equalsAny(null, (CharSequence[]) null) = false
StringUtils.equalsAny(null, null, null)    = true
StringUtils.equalsAny(null, "abc", "def")  = false
StringUtils.equalsAny("abc", null, "def")  = false
StringUtils.equalsAny("abc", "abc", "def") = true
StringUtils.equalsAny("abc", "ABC", "DEF") = false

Parameters:

string – to compare, may be null.
searchStrings – A vararg of strings, may be null.

Returns:

true if the string is equal (case-sensitive) to any other element of searchStrings; false if searchStrings is null or contains no matches.

Since:

3.5

@Deprecated public static boolean equalsAnyIgnoreCase(CharSequence string, CharSequence... searchStrings)[source]¶

Deprecated: Use Strings.CI.equalsAny(CharSequence, CharSequence...).

Compares given string to a CharSequences vararg of searchStrings, returning true if the string is equal to any of the searchStrings, ignoring case.

StringUtils.equalsAnyIgnoreCase(null, (CharSequence[]) null) = false
StringUtils.equalsAnyIgnoreCase(null, null, null)    = true
StringUtils.equalsAnyIgnoreCase(null, "abc", "def")  = false
StringUtils.equalsAnyIgnoreCase("abc", null, "def")  = false
StringUtils.equalsAnyIgnoreCase("abc", "abc", "def") = true
StringUtils.equalsAnyIgnoreCase("abc", "ABC", "DEF") = true

Parameters:

string – to compare, may be null.
searchStrings – A vararg of strings, may be null.

Returns:

true if the string is equal (case-insensitive) to any other element of searchStrings; false if searchStrings is null or contains no matches.

Since:

3.5

@Deprecated public static boolean equalsIgnoreCase(CharSequence cs1, CharSequence cs2)[source]¶

Deprecated: Use Strings.CI.equals(CharSequence, CharSequence).

Compares two CharSequences, returning true if they represent equal sequences of characters, ignoring case.

nulls are handled without exceptions. Two null references are considered equal. The 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:

cs1 – The first CharSequence, may be null.
cs2 – The second CharSequence, may be null.

Returns:

true if the CharSequences are equal (case-insensitive), or both null.

Since:

3.0 Changed signature from equalsIgnoreCase(String, String) to equalsIgnoreCase(CharSequence, CharSequence)

See also:

#equals(CharSequence, CharSequence)

@SafeVarargs public static <T extends CharSequence> T firstNonBlank(T... values)[source]¶

Returns the first value in the array which is not empty (“”), null or whitespace only.

Whitespace is defined by Character#isWhitespace(char).

If all values are blank or the array is null or empty then null is returned.

StringUtils.firstNonBlank(null, null, null)     = null
StringUtils.firstNonBlank(null, "", " ")        = null
StringUtils.firstNonBlank("abc")                = "abc"
StringUtils.firstNonBlank(null, "xyz")          = "xyz"
StringUtils.firstNonBlank(null, "", " ", "xyz") = "xyz"
StringUtils.firstNonBlank(null, "xyz", "abc")   = "xyz"
StringUtils.firstNonBlank()                     = null

Type parameters:: <T> – the specific kind of CharSequence.
Parameters:: values – The values to test, may be null or empty.
Returns:: The first value from values which is not blank, or null if there are no non-blank values.
Since:: 3.8

@SafeVarargs public static <T extends CharSequence> T firstNonEmpty(T... values)[source]¶

Returns the first value in the array which is not empty.

If all values are empty or the array is null or empty then null is returned.

StringUtils.firstNonEmpty(null, null, null)   = null
StringUtils.firstNonEmpty(null, null, "")     = null
StringUtils.firstNonEmpty(null, "", " ")      = " "
StringUtils.firstNonEmpty("abc")              = "abc"
StringUtils.firstNonEmpty(null, "xyz")        = "xyz"
StringUtils.firstNonEmpty("", "xyz")          = "xyz"
StringUtils.firstNonEmpty(null, "xyz", "abc") = "xyz"
StringUtils.firstNonEmpty()                   = null

Type parameters:: <T> – the specific kind of CharSequence.
Parameters:: values – The values to test, may be null or empty.
Returns:: The first value from values which is not empty, or null if there are no non-empty values.
Since:: 3.8

public static byte[] getBytes(String string, String charset) throws UnsupportedEncodingException [source]¶

Gets the bytes of the string using String#getBytes(String), handling null safely.

Parameters:

string – input string.
charset – The Charset name to encode the String. If null, then use the default Charset.

Returns:

The empty byte[] if string is null, the result of String#getBytes(String) otherwise.

Throws:

java.io.UnsupportedEncodingException – Thrown when the named charset is not supported.

See also:

String#getBytes(String)

Since:

3.10

public static byte[] getBytes(String string, Charset charset)[source]¶

Gets the bytes of the string using String#getBytes(Charset), handling null safely.

Parameters:

string – input string.
charset – The Charset to encode the String. If null, then use the default Charset.

Returns:

The empty byte[] if string is null, the result of String#getBytes(Charset) otherwise.

See also:

String#getBytes(Charset)

Since:

3.10

public static String getCommonPrefix(String... strs)[source]¶

Gets the initial sequence of characters common to all strings in the array.

For example, getCommonPrefix("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

public static String getDigits(String str)[source]¶

Gets the Unicode digits in str, concatenated in their original order.

An empty (“”) String will be returned if no digits are found in str.

StringUtils.getDigits(null)                 = null
StringUtils.getDigits("")                   = ""
StringUtils.getDigits("abc")                = ""
StringUtils.getDigits("1000$")              = "1000"
StringUtils.getDigits("1123~45")            = "112345"
StringUtils.getDigits("(541) 754-3010")     = "5417543010"
StringUtils.getDigits("१२३") = "१२३"

Parameters:: str – The String to extract digits from, may be null.
Returns:: String with only digits, or an empty (“”) String if no digits are found, or null String if str is null.
Since:: 3.6

@Deprecated public static int getFuzzyDistance(CharSequence term, CharSequence query, Locale locale)[source]¶

Deprecated: As of 3.6, use Apache Commons Text FuzzyScore instead.

Gets the Fuzzy Distance which indicates the similarity score between two Strings.

This string matching algorithm is similar to the algorithms of editors such as Sublime Text, TextMate, Atom and others. One point is given for every matched character. Subsequent matches yield two bonus points. A higher score indicates a higher similarity.

StringUtils.getFuzzyDistance(null, null, null)                                    = Throws IllegalArgumentException
StringUtils.getFuzzyDistance("", "", Locale.ENGLISH)                              = 0
StringUtils.getFuzzyDistance("Workshop", "b", Locale.ENGLISH)                     = 0
StringUtils.getFuzzyDistance("Room", "o", Locale.ENGLISH)                         = 1
StringUtils.getFuzzyDistance("Workshop", "w", Locale.ENGLISH)                     = 1
StringUtils.getFuzzyDistance("Workshop", "ws", Locale.ENGLISH)                    = 2
StringUtils.getFuzzyDistance("Workshop", "wo", Locale.ENGLISH)                    = 4
StringUtils.getFuzzyDistance("Apache Software Foundation", "asf", Locale.ENGLISH) = 3

Parameters:

term – A full term that should be matched against, must not be null.
query – The query that will be matched against a term, must not be null.
locale – This string matching logic is case-insensitive. A locale is necessary to normalize both Strings to lower case.

Returns:

result score.

Throws:

java.lang.IllegalArgumentException – Thrown if either String input null or Locale input null.

Since:

3.4

public static <T extends CharSequence> T getIfBlank(T str, Supplier<T> defaultSupplier)[source]¶

Gets either the passed in CharSequence, or if the CharSequence is blank (whitespaces, empty (""), or null), the value supplied by defaultStrSupplier.

Whitespace is defined by Character#isWhitespace(char).

The caller is responsible for thread safety and exception handling for the default value supplier.

StringUtils.getIfBlank(null, () -> "NULL")   = "NULL"
StringUtils.getIfBlank("", () -> "NULL")     = "NULL"
StringUtils.getIfBlank(" ", () -> "NULL")    = "NULL"
StringUtils.getIfBlank("bat", () -> "NULL")  = "bat"
StringUtils.getIfBlank("", () -> null)       = null
StringUtils.getIfBlank("", null)             = null

Type parameters:

<T> – the specific kind of CharSequence.

Parameters:

str – The CharSequence to check, may be null.
defaultSupplier – The supplier of default CharSequence to return if the input is blank (whitespaces, empty (""), or null); may be null.

Returns:

The passed in CharSequence, or the default

See also:

StringUtils#defaultString(String, String)
#isBlank(CharSequence)

Since:

3.10

public static <T extends CharSequence> T getIfEmpty(T str, Supplier<T> defaultSupplier)[source]¶

Gets either the passed in CharSequence, or if the CharSequence is empty or null, the value supplied by defaultStrSupplier.

The caller is responsible for thread safety and exception handling for the default value supplier.

StringUtils.getIfEmpty(null, () -> "NULL")    = "NULL"
StringUtils.getIfEmpty("", () -> "NULL")      = "NULL"
StringUtils.getIfEmpty(" ", () -> "NULL")     = " "
StringUtils.getIfEmpty("bat", () -> "NULL")   = "bat"
StringUtils.getIfEmpty("", () -> null)        = null
StringUtils.getIfEmpty("", null)              = null

Type parameters:

<T> – the specific kind of CharSequence.

Parameters:

str – The CharSequence to check, may be null.
defaultSupplier – The supplier of default CharSequence to return if the input is empty (“”) or null, may be null.

Returns:

The passed in CharSequence, or the default.

Since:

3.10

@Deprecated public static double getJaroWinklerDistance(CharSequence first, CharSequence second)[source]¶

Deprecated: As of 3.6, use Apache Commons Text JaroWinklerDistance instead.

Gets the Jaro Winkler Distance which indicates the similarity score between two Strings.

The Jaro measure is the weighted sum of percentage of matched characters from each file and transposed characters. Winkler increased this measure for matching initial characters.

This implementation is based on the Jaro Winkler similarity algorithm from https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance.

StringUtils.getJaroWinklerDistance(null, null)          = Throws IllegalArgumentException
StringUtils.getJaroWinklerDistance("", "")              = 0.0
StringUtils.getJaroWinklerDistance("", "a")             = 0.0
StringUtils.getJaroWinklerDistance("aaapppp", "")       = 0.0
StringUtils.getJaroWinklerDistance("frog", "fog")       = 0.93
StringUtils.getJaroWinklerDistance("fly", "ant")        = 0.0
StringUtils.getJaroWinklerDistance("elephant", "hippo") = 0.44
StringUtils.getJaroWinklerDistance("hippo", "elephant") = 0.44
StringUtils.getJaroWinklerDistance("hippo", "zzzzzzzz") = 0.0
StringUtils.getJaroWinklerDistance("hello", "hallo")    = 0.88
StringUtils.getJaroWinklerDistance("ABC Corporation", "ABC Corp") = 0.93
StringUtils.getJaroWinklerDistance("D N H Enterprises Inc", "D & H Enterprises, Inc.") = 0.95
StringUtils.getJaroWinklerDistance("My Gym Children's Fitness Center", "My Gym. Childrens Fitness") = 0.92
StringUtils.getJaroWinklerDistance("PENNSYLVANIA", "PENNCISYLVNIA") = 0.88

Parameters:

first – The first String, must not be null.
second – The second String, must not be null.

Returns:

result distance.

Throws:

java.lang.IllegalArgumentException – Thrown if either String input null.

Since:

3.3

@Deprecated public static int getLevenshteinDistance(CharSequence s, CharSequence t)[source]¶

Deprecated: As of 3.6, use Apache Commons Text LevenshteinDistance instead.

Gets 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 implementation uses a single-dimensional array of length s.length() + 1. See https://blog.softwx.net/2014/12/optimizing-levenshtein-algorithm-in-c.html for details.

StringUtils.getLevenshteinDistance(null, *)             = Throws IllegalArgumentException
StringUtils.getLevenshteinDistance(*, null)             = Throws 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:

java.lang.IllegalArgumentException – Thrown if either String input null.

Since:

3.0 Changed signature from getLevenshteinDistance(String, String) to getLevenshteinDistance(CharSequence, CharSequence)

@Deprecated public static int getLevenshteinDistance(CharSequence s, CharSequence t, int threshold)[source]¶

Deprecated: As of 3.6, use Apache Commons Text LevenshteinDistance instead.

Gets the Levenshtein distance between two Strings if it’s less than or equal to a given threshold.

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

This implementation follows from Algorithms on Strings, Trees and Sequences by Dan Gusfield and Chas Emerick’s implementation of the Levenshtein distance algorithm.

StringUtils.getLevenshteinDistance(null, *, *)             = Throws IllegalArgumentException
StringUtils.getLevenshteinDistance(*, null, *)             = Throws IllegalArgumentException
StringUtils.getLevenshteinDistance(*, *, -1)               = Throws IllegalArgumentException
StringUtils.getLevenshteinDistance("", "", 0)              = 0
StringUtils.getLevenshteinDistance("aaapppp", "", 8)       = 7
StringUtils.getLevenshteinDistance("aaapppp", "", 7)       = 7
StringUtils.getLevenshteinDistance("aaapppp", "", 6))      = -1
StringUtils.getLevenshteinDistance("elephant", "hippo", 7) = 7
StringUtils.getLevenshteinDistance("elephant", "hippo", 6) = -1
StringUtils.getLevenshteinDistance("hippo", "elephant", 7) = 7
StringUtils.getLevenshteinDistance("hippo", "elephant", 6) = -1

Parameters:

s – The first String, must not be null.
t – The second String, must not be null.
threshold – The target threshold, must not be negative.

Returns:

result distance, or -1 if the distance would be greater than the threshold.

Throws:

java.lang.IllegalArgumentException – Thrown if either String input null or negative threshold.

public static int indexOf(CharSequence seq, int searchChar)[source]¶

Returns the index within seq of the first occurrence of the specified character. If a character with value searchChar occurs in the character sequence represented by seq CharSequence object, then the index (in Unicode code units) of the first such occurrence is returned. For values of searchChar in the range from 0 to 0xFFFF (inclusive), this is the smallest value k such that:

this.charAt(k) == searchChar

is true. For other values of searchChar, it is the smallest value k such that:

this.codePointAt(k) == searchChar

is true. In either case, if no such character occurs in seq, then INDEX_NOT_FOUND (-1) is returned.

Furthermore, a null or empty (“”) CharSequence will return INDEX_NOT_FOUND (-1).

StringUtils.indexOf(null, *)         = -1
StringUtils.indexOf("", *)           = -1
StringUtils.indexOf("aabaabaa", 'a') = 0
StringUtils.indexOf("aabaabaa", 'b') = 2
StringUtils.indexOf("aaaaaaaa", 'Z') = -1

Parameters:

seq – The CharSequence 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:

3.6 Updated CharSequenceUtils call to behave more like String

public static int indexOf(CharSequence seq, int searchChar, int startPos)[source]¶

Returns the index within seq of the first occurrence of the specified character, starting the search at the specified index.

If a character with value searchChar occurs in the character sequence represented by the seq CharSequence object at an index no smaller than startPos, then the index of the first such occurrence is returned. For values of searchChar in the range from 0 to 0xFFFF (inclusive), this is the smallest value k such that:

(this.charAt(k) == searchChar) && (k >= startPos)

is true. For other values of searchChar, it is the smallest value k such that:

(this.codePointAt(k) == searchChar) && (k >= startPos)

is true. In either case, if no such character occurs in seq at or after position startPos, then -1 is returned.

There is no restriction on the value of startPos. If it is negative, it has the same effect as if it were zero: this entire string may be searched. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string: (INDEX_NOT_FOUND) -1 is returned. Furthermore, a null or empty (“”) CharSequence will return (INDEX_NOT_FOUND) -1.

All indices are specified in char values (Unicode code units).

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:

seq – The CharSequence 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 (always ≥ startPos), -1 if no match or null string input.

Since:

3.6 Updated CharSequenceUtils call to behave more like String

@Deprecated public static int indexOf(CharSequence seq, CharSequence searchSeq)[source]¶

Deprecated: Use Strings.CS.indexOf(CharSequence, CharSequence).

Finds the first index within a CharSequence, handling null. This method uses String#indexOf(String, int) if possible.

A null CharSequence will return -1.

StringUtils.indexOf(null, *)          = -1
StringUtils.indexOf(*, null)          = -1
StringUtils.indexOf("", "")           = 0
StringUtils.indexOf("", *)            = -1 (except when * = "")
StringUtils.indexOf("aabaabaa", "a")  = 0
StringUtils.indexOf("aabaabaa", "b")  = 2
StringUtils.indexOf("aabaabaa", "ab") = 1
StringUtils.indexOf("aabaabaa", "")   = 0

Parameters:

seq – The CharSequence to check, may be null.
searchSeq – The CharSequence to find, may be null.

Returns:

The first index of the search CharSequence, -1 if no match or null string input.

Since:

3.0 Changed signature from indexOf(String, String) to indexOf(CharSequence, CharSequence)

@Deprecated public static int indexOf(CharSequence seq, CharSequence searchSeq, int startPos)[source]¶

Deprecated: Use Strings.CS.indexOf(CharSequence, CharSequence, int).

Finds the first index within a CharSequence, handling null. This method uses String#indexOf(String, int) if possible.

A null CharSequence will return -1. A negative start position is treated as zero. An empty (“”) search CharSequence always matches. A start position greater than the string length only matches an empty search CharSequence.

StringUtils.indexOf(null, *, *)          = -1
StringUtils.indexOf(*, null, *)          = -1
StringUtils.indexOf("", "", 0)           = 0
StringUtils.indexOf("", *, 0)            = -1 (except when * = "")
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:

seq – The CharSequence to check, may be null.
searchSeq – The CharSequence to find, may be null.
startPos – The start position, negative treated as zero.

Returns:

The first index of the search CharSequence (always ≥ startPos), -1 if no match or null string input.

Since:

3.0 Changed signature from indexOf(String, String, int) to indexOf(CharSequence, CharSequence, int)

public static int indexOfAny(CharSequence cs, char... searchChars)[source]¶

Search a CharSequence 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:

cs – The CharSequence 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:

3.0 Changed signature from indexOfAny(String, char[]) to indexOfAny(CharSequence, char…)

public static int indexOfAny(CharSequence cs, int csStart, char... searchChars)[source]¶

Search a CharSequence 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.

The following is the same as indexOfAny(cs, 0, searchChars).

StringUtils.indexOfAny(null, 0, *)                  = -1
StringUtils.indexOfAny("", 0, *)                    = -1
StringUtils.indexOfAny(*, 0, null)                  = -1
StringUtils.indexOfAny(*, 0, [])                    = -1
StringUtils.indexOfAny("zzabyycdxx", 0, ['z', 'a']) = 0
StringUtils.indexOfAny("zzabyycdxx", 0, ['b', 'y']) = 3
StringUtils.indexOfAny("aba", 0, ['z'])             = -1

Parameters:

cs – The CharSequence to check, may be null.
csStart – Start searching the input cs at this index.
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:

3.0 Changed signature from indexOfAny(String, char[]) to indexOfAny(CharSequence, char…)

public static int indexOfAny(CharSequence str, CharSequence... searchStrs)[source]¶

Find the first index of any of a set of potential substrings.

A null CharSequence 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) if possible.

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 CharSequence to check, may be null.
searchStrs – The CharSequences to search for, may be null.

Returns:

The first index of any of the searchStrs in str, -1 if no match.

Since:

3.0 Changed signature from indexOfAny(String, String[]) to indexOfAny(CharSequence, CharSequence…)

public static int indexOfAny(CharSequence cs, String searchChars)[source]¶

Search a CharSequence 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:

cs – The CharSequence 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:

3.0 Changed signature from indexOfAny(String, String) to indexOfAny(CharSequence, String)

public static int indexOfAnyBut(CharSequence cs, char... searchChars)[source]¶

Searches a CharSequence to find the first index of any character not in the given set of characters, i.e., find index i of first char in cs such that (cs.codePointAt(i) ∉ { x ∈ codepoints(searchChars) })

A null CharSequence 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", new char[] {'z', 'a'} ) = 3
StringUtils.indexOfAnyBut("aba", new char[] {'z'} )             = 0
StringUtils.indexOfAnyBut("aba", new char[] {'a', 'b'} )        = -1

Parameters:

cs – The CharSequence 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:

3.0 Changed signature from indexOfAnyBut(String, char[]) to indexOfAnyBut(CharSequence, char…)

public static int indexOfAnyBut(CharSequence seq, CharSequence searchChars)[source]¶

Search a CharSequence to find the first index of any character not in the given set of characters, i.e., find index i of first char in seq such that (seq.codePointAt(i) ∉ { x ∈ codepoints(searchChars) })

A null CharSequence will return -1. A null or empty 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", "")   = -1
StringUtils.indexOfAnyBut("aba", "ab")        = -1

Parameters:

seq – The CharSequence 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:

3.0 Changed signature from indexOfAnyBut(String, String) to indexOfAnyBut(CharSequence, CharSequence)

public static int indexOfDifference(CharSequence cs1, CharSequence cs2)[source]¶

Compares two CharSequences, and returns the index at which the CharSequences 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:

cs1 – The first CharSequence, may be null.
cs2 – The second CharSequence, may be null.

Returns:

The index where cs1 and cs2 begin to differ; -1 if they are equal.

Since:

3.0 Changed signature from indexOfDifference(String, String) to indexOfDifference(CharSequence, CharSequence)

public static int indexOfDifference(CharSequence... css)[source]¶

Compares all CharSequences in an array and returns the index at which the CharSequences 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:: css – array of CharSequences, entries may be null.
Returns:: The index where the strings begin to differ; -1 if they are all equal.
Since:: 3.0 Changed signature from indexOfDifference(String…) to indexOfDifference(CharSequence…)

@Deprecated public static int indexOfIgnoreCase(CharSequence str, CharSequence searchStr)[source]¶

Deprecated: Use Strings.CI.indexOf(CharSequence, CharSequence).

Case insensitive find of the first index within a CharSequence.

StringUtils.indexOfIgnoreCase(null, *)          = -1
StringUtils.indexOfIgnoreCase(*, null)          = -1
StringUtils.indexOfIgnoreCase("", "")           = 0
StringUtils.indexOfIgnoreCase(" ", " ")         = 0
StringUtils.indexOfIgnoreCase("aabaabaa", "a")  = 0
StringUtils.indexOfIgnoreCase("aabaabaa", "b")  = 2
StringUtils.indexOfIgnoreCase("aabaabaa", "ab") = 1

Parameters:

str – The CharSequence to check, may be null.
searchStr – The CharSequence to find, may be null.

Returns:

The first index of the search CharSequence, -1 if no match or null string input.

Since:

3.0 Changed signature from indexOfIgnoreCase(String, String) to indexOfIgnoreCase(CharSequence, CharSequence)

@Deprecated public static int indexOfIgnoreCase(CharSequence str, CharSequence searchStr, int startPos)[source]¶

Deprecated: Use Strings.CI.indexOf(CharSequence, CharSequence, int).

Case insensitive find of the first index within a CharSequence from the specified position.

StringUtils.indexOfIgnoreCase(null, *, *)          = -1
StringUtils.indexOfIgnoreCase(*, null, *)          = -1
StringUtils.indexOfIgnoreCase("", "", 0)           = 0
StringUtils.indexOfIgnoreCase("aabaabaa", "A", 0)  = 0
StringUtils.indexOfIgnoreCase("aabaabaa", "B", 0)  = 2
StringUtils.indexOfIgnoreCase("aabaabaa", "AB", 0) = 1
StringUtils.indexOfIgnoreCase("aabaabaa", "B", 3)  = 5
StringUtils.indexOfIgnoreCase("aabaabaa", "B", 9)  = -1
StringUtils.indexOfIgnoreCase("aabaabaa", "B", -1) = 2
StringUtils.indexOfIgnoreCase("aabaabaa", "", 2)   = 2
StringUtils.indexOfIgnoreCase("abc", "", 9)        = -1

Parameters:

str – The CharSequence to check, may be null.
searchStr – The CharSequence to find, may be null.
startPos – The start position, negative treated as zero.

Returns:

The first index of the search CharSequence (always ≥ startPos), -1 if no match or null string input.

Since:

3.0 Changed signature from indexOfIgnoreCase(String, String, int) to indexOfIgnoreCase(CharSequence, CharSequence, int)

public static boolean isAllBlank(CharSequence... css)[source]¶

Tests if all of the CharSequences are empty (“”), null or whitespace only.

Whitespace is defined by Character#isWhitespace(char).

StringUtils.isAllBlank(null)             = true
StringUtils.isAllBlank(null, "foo")      = false
StringUtils.isAllBlank(null, null)       = true
StringUtils.isAllBlank("", "bar")        = false
StringUtils.isAllBlank("bob", "")        = false
StringUtils.isAllBlank("  bob  ", null)  = false
StringUtils.isAllBlank(" ", "bar")       = false
StringUtils.isAllBlank("foo", "bar")     = false
StringUtils.isAllBlank(new String[] {})  = true

Parameters:: css – The CharSequences to check, may be null or empty.
Returns:: true if all of the CharSequences are empty or null or whitespace only.
Since:: 3.6

public static boolean isAllEmpty(CharSequence... css)[source]¶

Tests if all of the CharSequences are empty (“”) or null.

StringUtils.isAllEmpty(null)             = true
StringUtils.isAllEmpty(null, "")         = true
StringUtils.isAllEmpty(new String[] {})  = true
StringUtils.isAllEmpty(null, "foo")      = false
StringUtils.isAllEmpty("", "bar")        = false
StringUtils.isAllEmpty("bob", "")        = false
StringUtils.isAllEmpty("  bob  ", null)  = false
StringUtils.isAllEmpty(" ", "bar")       = false
StringUtils.isAllEmpty("foo", "bar")     = false

Parameters:: css – The CharSequences to check, may be null or empty.
Returns:: true if all of the CharSequences are empty or null.
Since:: 3.6

public static boolean isAllLowerCase(CharSequence cs)[source]¶

Tests if the CharSequence contains only lowercase characters.

null will return false. An empty CharSequence (length()=0) will return false.

StringUtils.isAllLowerCase(null)   = false
StringUtils.isAllLowerCase("")     = false
StringUtils.isAllLowerCase("  ")   = false
StringUtils.isAllLowerCase("abc")  = true
StringUtils.isAllLowerCase("abC")  = false
StringUtils.isAllLowerCase("ab c") = false
StringUtils.isAllLowerCase("ab1c") = false
StringUtils.isAllLowerCase("ab/c") = false

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if only contains lowercase characters, and is non-null.
Since:: 3.0 Changed signature from isAllLowerCase(String) to isAllLowerCase(CharSequence)

public static boolean isAllUpperCase(CharSequence cs)[source]¶

Tests if the CharSequence contains only uppercase characters.

null will return false. An empty String (length()=0) will return false.

StringUtils.isAllUpperCase(null)   = false
StringUtils.isAllUpperCase("")     = false
StringUtils.isAllUpperCase("  ")   = false
StringUtils.isAllUpperCase("ABC")  = true
StringUtils.isAllUpperCase("aBC")  = false
StringUtils.isAllUpperCase("A C")  = false
StringUtils.isAllUpperCase("A1C")  = false
StringUtils.isAllUpperCase("A/C")  = false

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if only contains uppercase characters, and is non-null.
Since:: 3.0 Changed signature from isAllUpperCase(String) to isAllUpperCase(CharSequence)

public static boolean isAlpha(CharSequence cs)[source]¶

Tests if the CharSequence contains only Unicode letters.

null will return false. An empty CharSequence (length()=0) will return false.

StringUtils.isAlpha(null)   = false
StringUtils.isAlpha("")     = false
StringUtils.isAlpha("  ")   = false
StringUtils.isAlpha("abc")  = true
StringUtils.isAlpha("ab2c") = false
StringUtils.isAlpha("ab-c") = false

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if only contains letters, and is non-null.
Since:: 3.0 Changed “” to return false and not true

public static boolean isAlphaSpace(CharSequence cs)[source]¶

Tests if the CharSequence contains only Unicode letters and space (’ ‘).

null will return false An empty CharSequence (length()=0) 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:: cs – The CharSequence to check, may be null.
Returns:: true if only contains letters and space, and is non-null.
Since:: 3.0 Changed signature from isAlphaSpace(String) to isAlphaSpace(CharSequence)

public static boolean isAlphanumeric(CharSequence cs)[source]¶

Tests if the CharSequence contains only Unicode letters or digits.

null will return false. An empty CharSequence (length()=0) will return false.

StringUtils.isAlphanumeric(null)   = false
StringUtils.isAlphanumeric("")     = false
StringUtils.isAlphanumeric("  ")   = false
StringUtils.isAlphanumeric("abc")  = true
StringUtils.isAlphanumeric("ab c") = false
StringUtils.isAlphanumeric("ab2c") = true
StringUtils.isAlphanumeric("ab-c") = false

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if only contains letters or digits, and is non-null.
Since:: 3.0 Changed “” to return false and not true

public static boolean isAlphanumericSpace(CharSequence cs)[source]¶

Tests if the CharSequence contains only Unicode letters, digits or space (' ').

null will return false. An empty CharSequence (length()=0) will return true.

StringUtils.isAlphanumericSpace(null)   = false
StringUtils.isAlphanumericSpace("")     = true
StringUtils.isAlphanumericSpace("  ")   = true
StringUtils.isAlphanumericSpace("abc")  = true
StringUtils.isAlphanumericSpace("ab c") = true
StringUtils.isAlphanumericSpace("ab2c") = true
StringUtils.isAlphanumericSpace("ab-c") = false

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if only contains letters, digits or space, and is non-null.
Since:: 3.0 Changed signature from isAlphanumericSpace(String) to isAlphanumericSpace(CharSequence)

public static boolean isAnyBlank(CharSequence... css)[source]¶

Tests if any of the CharSequences are blank (whitespaces, empty (""), or null).

Whitespace is defined by Character#isWhitespace(char).

StringUtils.isAnyBlank((String) null)    = true
StringUtils.isAnyBlank((String[]) null)  = false
StringUtils.isAnyBlank(null, "foo")      = true
StringUtils.isAnyBlank(null, null)       = true
StringUtils.isAnyBlank("", "bar")        = true
StringUtils.isAnyBlank("bob", "")        = true
StringUtils.isAnyBlank("  bob  ", null)  = true
StringUtils.isAnyBlank(" ", "bar")       = true
StringUtils.isAnyBlank(new String[] {})  = false
StringUtils.isAnyBlank(new String[]{""}) = true
StringUtils.isAnyBlank("foo", "bar")     = false

Parameters:: css – The CharSequences to check, may be null or empty.
Returns:: true if any of the CharSequences are blank (whitespaces, empty (""), or null).
See also:: #isBlank(CharSequence)
Since:: 3.2

public static boolean isAnyEmpty(CharSequence... css)[source]¶

Tests if any of the CharSequences are empty (“”) or null.

StringUtils.isAnyEmpty((String) null)    = true
StringUtils.isAnyEmpty((String[]) null)  = false
StringUtils.isAnyEmpty(null, "foo")      = true
StringUtils.isAnyEmpty("", "bar")        = true
StringUtils.isAnyEmpty("bob", "")        = true
StringUtils.isAnyEmpty("  bob  ", null)  = true
StringUtils.isAnyEmpty(" ", "bar")       = false
StringUtils.isAnyEmpty("foo", "bar")     = false
StringUtils.isAnyEmpty(new String[]{})   = false
StringUtils.isAnyEmpty(new String[]{""}) = true

Parameters:: css – The CharSequences to check, may be null or empty.
Returns:: true if any of the CharSequences are empty or null.
Since:: 3.2

public static boolean isAsciiPrintable(CharSequence cs)[source]¶

Tests if the CharSequence contains only ASCII printable characters.

null will return false. An empty CharSequence (length()=0) 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:: cs – The CharSequence to check, may be null.
Returns:: true if every character is in the range 32 through 126.
Since:: 3.0 Changed signature from isAsciiPrintable(String) to isAsciiPrintable(CharSequence)

public static boolean isBlank(CharSequence cs)[source]¶

Tests if a CharSequence is empty (""), null, or contains only whitespace as defined by Character#isWhitespace(char).

StringUtils.isBlank(null)      = true
StringUtils.isBlank("")        = true
StringUtils.isBlank(" ")       = true
StringUtils.isBlank("bob")     = false
StringUtils.isBlank("  bob  ") = false

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if the CharSequence is null, empty or whitespace only.
Since:: 3.0 Changed signature from isBlank(String) to isBlank(CharSequence)

public static boolean isEmpty(CharSequence cs)[source]¶

Tests if a CharSequence 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 CharSequence. That functionality is available in isBlank().

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if the CharSequence is empty or null.
Since:: 3.0 Changed signature from isEmpty(String) to isEmpty(CharSequence)

public static boolean isMixedCase(CharSequence cs)[source]¶

Tests if the CharSequence contains mixed casing of both uppercase and lowercase characters.

null will return false. An empty CharSequence (length()=0) will return false.

StringUtils.isMixedCase(null)    = false
StringUtils.isMixedCase("")      = false
StringUtils.isMixedCase(" ")     = false
StringUtils.isMixedCase("ABC")   = false
StringUtils.isMixedCase("abc")   = false
StringUtils.isMixedCase("aBc")   = true
StringUtils.isMixedCase("A c")   = true
StringUtils.isMixedCase("A1c")   = true
StringUtils.isMixedCase("a/C")   = true
StringUtils.isMixedCase("aC\t")  = true

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if the CharSequence contains both uppercase and lowercase characters.
Since:: 3.5

public static boolean isNoneBlank(CharSequence... css)[source]¶

Tests if none of the CharSequences are empty (“”), null or whitespace only.

Whitespace is defined by Character#isWhitespace(char).

StringUtils.isNoneBlank((String) null)    = false
StringUtils.isNoneBlank((String[]) null)  = true
StringUtils.isNoneBlank(null, "foo")      = false
StringUtils.isNoneBlank(null, null)       = false
StringUtils.isNoneBlank("", "bar")        = false
StringUtils.isNoneBlank("bob", "")        = false
StringUtils.isNoneBlank("  bob  ", null)  = false
StringUtils.isNoneBlank(" ", "bar")       = false
StringUtils.isNoneBlank(new String[] {})  = true
StringUtils.isNoneBlank(new String[]{""}) = false
StringUtils.isNoneBlank("foo", "bar")     = true

Parameters:: css – The CharSequences to check, may be null or empty.
Returns:: true if none of the CharSequences are empty or null or whitespace only.
Since:: 3.2

public static boolean isNoneEmpty(CharSequence... css)[source]¶

Tests if none of the CharSequences are empty (“”) or null.

StringUtils.isNoneEmpty((String) null)    = false
StringUtils.isNoneEmpty((String[]) null)  = true
StringUtils.isNoneEmpty(null, "foo")      = false
StringUtils.isNoneEmpty("", "bar")        = false
StringUtils.isNoneEmpty("bob", "")        = false
StringUtils.isNoneEmpty("  bob  ", null)  = false
StringUtils.isNoneEmpty(new String[] {})  = true
StringUtils.isNoneEmpty(new String[]{""}) = false
StringUtils.isNoneEmpty(" ", "bar")       = true
StringUtils.isNoneEmpty("foo", "bar")     = true

Parameters:: css – The CharSequences to check, may be null or empty.
Returns:: true if none of the CharSequences are empty or null.
Since:: 3.2

public static boolean isNotBlank(CharSequence cs)[source]¶

Tests if a CharSequence is not blank (whitespaces, empty (""), or null).

Whitespace is defined by Character#isWhitespace(char).

StringUtils.isNotBlank(null)      = false
StringUtils.isNotBlank("")        = false
StringUtils.isNotBlank(" ")       = false
StringUtils.isNotBlank("bob")     = true
StringUtils.isNotBlank("  bob  ") = true

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if the CharSequence is not blank (whitespaces, empty (""), or null).
See also:: #isBlank(CharSequence)
Since:: 3.0 Changed signature from isNotBlank(String) to isNotBlank(CharSequence)

public static boolean isNotEmpty(CharSequence cs)[source]¶

Tests if a CharSequence 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:: cs – The CharSequence to check, may be null.
Returns:: true if the CharSequence is not empty and not null.
Since:: 3.0 Changed signature from isNotEmpty(String) to isNotEmpty(CharSequence)

public static boolean isNumeric(CharSequence cs)[source]¶

Tests if the CharSequence contains only Unicode digits. A decimal point is not a Unicode digit and returns false.

null will return false. An empty CharSequence (length()=0) will return false.

Note that the method does not allow for a leading sign, either positive or negative. Also, if a String passes the numeric test, it may still generate a NumberFormatException when parsed by Integer.parseInt or Long.parseLong, e.g. if the value is outside the range for int or long respectively.

StringUtils.isNumeric(null)   = false
StringUtils.isNumeric("")     = false
StringUtils.isNumeric("  ")   = false
StringUtils.isNumeric("123")  = true
StringUtils.isNumeric("१२३")  = true
StringUtils.isNumeric("12 3") = false
StringUtils.isNumeric("ab2c") = false
StringUtils.isNumeric("12-3") = false
StringUtils.isNumeric("12.3") = false
StringUtils.isNumeric("-123") = false
StringUtils.isNumeric("+123") = false

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if only contains digits, and is non-null.
Since:: 3.0 Changed “” to return false and not true

public static boolean isNumericSpace(CharSequence cs)[source]¶

Tests if the CharSequence contains only Unicode digits or space (' '). A decimal point is not a Unicode digit and returns false.

null will return false. An empty CharSequence (length()=0) will return true.

StringUtils.isNumericSpace(null)   = false
StringUtils.isNumericSpace("")     = true
StringUtils.isNumericSpace("  ")   = true
StringUtils.isNumericSpace("123")  = true
StringUtils.isNumericSpace("12 3") = true
StringUtils.isNumericSpace("१२३")   = true
StringUtils.isNumericSpace("१२ ३")  = true
StringUtils.isNumericSpace("ab2c") = false
StringUtils.isNumericSpace("12-3") = false
StringUtils.isNumericSpace("12.3") = false

Parameters:: cs – The CharSequence to check, may be null.
Returns:: true if only contains digits or space, and is non-null.
Since:: 3.0 Changed signature from isNumericSpace(String) to isNumericSpace(CharSequence)

public static boolean isWhitespace(CharSequence cs)[source]¶

Tests if the CharSequence contains only whitespace.

Whitespace is defined by Character#isWhitespace(char).

null will return false. An empty CharSequence (length()=0) 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:: cs – The CharSequence to check, may be null.
Returns:: true if only contains whitespace, and is non-null.
Since:: 3.0 Changed signature from isWhitespace(String) to isWhitespace(CharSequence)

public static String join(boolean[] array, char delimiter)[source]¶

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

Parameters:

array – The array of values to join together, may be null.
delimiter – The separator character to use.

Returns:

The joined String, null if null array input.

Since:

3.12.0

public static String join(boolean[] array, char delimiter, int startIndex, int endIndex)[source]¶

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([true, false, true], ';') = "true;false;true"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.
startIndex – the first index to start joining from. It is an error to pass in a start 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:

3.12.0

public static String join(byte[] array, char delimiter)[source]¶

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([1, 2, 3], ';')  = "1;2;3"
StringUtils.join([1, 2, 3], null) = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.

Returns:

The joined String, null if null array input.

Since:

3.2

public static String join(byte[] array, char delimiter, int startIndex, int endIndex)[source]¶

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([1, 2, 3], ';')  = "1;2;3"
StringUtils.join([1, 2, 3], null) = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.
startIndex – the first index to start joining from. It is an error to pass in a start 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:

3.2

public static String join(char[] array, char delimiter)[source]¶

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([1, 2, 3], ';')  = "1;2;3"
StringUtils.join([1, 2, 3], null) = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.

Returns:

The joined String, null if null array input.

Since:

3.2

public static String join(char[] array, char delimiter, int startIndex, int endIndex)[source]¶

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([1, 2, 3], ';')  = "1;2;3"
StringUtils.join([1, 2, 3], null) = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.
startIndex – the first index to start joining from. It is an error to pass in a start 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:

3.2

public static String join(double[] array, char delimiter)[source]¶

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([1, 2, 3], ';')   = "1;2;3"
StringUtils.join([1, 2, 3], null)  = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.

Returns:

The joined String, null if null array input.

Since:

3.2

public static String join(double[] array, char delimiter, int startIndex, int endIndex)[source]¶

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([1, 2, 3], ';')   = "1;2;3"
StringUtils.join([1, 2, 3], null)  = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.
startIndex – the first index to start joining from. It is an error to pass in a start 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:

3.2

public static String join(float[] array, char delimiter)[source]¶

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([1, 2, 3], ';')   = "1;2;3"
StringUtils.join([1, 2, 3], null)  = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.

Returns:

The joined String, null if null array input

Since:

3.2

public static String join(float[] array, char delimiter, int startIndex, int endIndex)[source]¶

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([1, 2, 3], ';')   = "1;2;3"
StringUtils.join([1, 2, 3], null)  = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.
startIndex – the first index to start joining from. It is an error to pass in a start 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:

3.2

public static String join(int[] array, char separator)[source]¶

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([1, 2, 3], ';')   = "1;2;3"
StringUtils.join([1, 2, 3], null)  = "123"

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:

3.2

public static String join(int[] array, char delimiter, int startIndex, int endIndex)[source]¶

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([1, 2, 3], ';')   = "1;2;3"
StringUtils.join([1, 2, 3], null)  = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.
startIndex – the first index to start joining from. It is an error to pass in a start 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:

3.2

public static String join(Iterable<?> iterable, char separator)[source]¶

Joins the elements of the provided Iterable 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: #join(Object[],char).

Parameters:

iterable – The Iterable providing the 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

public static String join(Iterable<?> iterable, String separator)[source]¶

Joins the elements of the provided Iterable 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: #join(Object[],String).

Parameters:

iterable – The Iterable providing the 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

@SafeVarargs public static <T> String join(T... elements)[source]¶

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"

Type parameters:: <T> – the specific type of values to join together.
Parameters:: elements – The values to join together, may be null.
Returns:: The joined String, null if null array input.
Since:: 3.0 Changed signature to use varargs

public static String join(Object[] array, char delimiter)[source]¶

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.
delimiter – The separator character to use.

Returns:

The joined String, null if null array input.

Since:

2.0

public static String join(Object[] array, char delimiter, int startIndex, int endIndex)[source]¶

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.
delimiter – The separator character to use.
startIndex – The first index to start joining from. It is an error to pass in a start 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

public static String join(Object[] array, String delimiter)[source]¶

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.
delimiter – The separator character to use, null treated as “”.

Returns:

The joined String, null if null array input.

public static String join(Object[] array, String delimiter, int startIndex, int endIndex)[source]¶

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"], "--", 0, 3)  = "a--b--c"
StringUtils.join(["a", "b", "c"], "--", 1, 3)  = "b--c"
StringUtils.join(["a", "b", "c"], "--", 2, 3)  = "c"
StringUtils.join(["a", "b", "c"], "--", 2, 2)  = ""
StringUtils.join(["a", "b", "c"], null, 0, 3)  = "abc"
StringUtils.join(["a", "b", "c"], "", 0, 3)    = "abc"
StringUtils.join([null, "", "a"], ',', 0, 3)   = ",,a"

Parameters:

array – The array of values to join together, may be null.
delimiter – The separator character to use, null treated as “”.
startIndex – The first index to start joining from.
endIndex – The index to stop joining from (exclusive).

Returns:

The joined String, null if null array input; or the empty string if endIndex - startIndex <= 0. The number of joined entries is given by endIndex - startIndex.

Throws:

java.lang.ArrayIndexOutOfBoundsException

Thrown if
 startIndex < 0 or 
 startIndex >= array.length() or 
 endIndex < 0 or 
 endIndex > array.length().

public static String join(Iterator<?> iterator, char separator)[source]¶

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: #join(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

public static String join(Iterator<?> iterator, String separator)[source]¶

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: #join(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.

public static String join(List<?> list, char separator, int startIndex, int endIndex)[source]¶

Joins the elements of the provided List 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:

list – The List 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 a start index past the end of the list.
endIndex – The index to stop joining from (exclusive). It is an error to pass in an end index past the end of the list.

Returns:

The joined String, null if null list input.

Since:

3.8

public static String join(List<?> list, String separator, int startIndex, int endIndex)[source]¶

Joins the elements of the provided List 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:

list – The List 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 a start index past the end of the list.
endIndex – The index to stop joining from (exclusive). It is an error to pass in an end index past the end of the list.

Returns:

The joined String, null if null list input.

Since:

3.8

public static String join(long[] array, char separator)[source]¶

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([1, 2, 3], ';')  = "1;2;3"
StringUtils.join([1, 2, 3], null) = "123"

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:

3.2

public static String join(long[] array, char delimiter, int startIndex, int endIndex)[source]¶

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([1, 2, 3], ';')  = "1;2;3"
StringUtils.join([1, 2, 3], null) = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.
startIndex – the first index to start joining from. It is an error to pass in a start 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:

3.2

public static String join(short[] array, char delimiter)[source]¶

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([1, 2, 3], ';')   = "1;2;3"
StringUtils.join([1, 2, 3], null)  = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.

Returns:

The joined String, null if null array input.

Since:

3.2

public static String join(short[] array, char delimiter, int startIndex, int endIndex)[source]¶

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([1, 2, 3], ';')   = "1;2;3"
StringUtils.join([1, 2, 3], null)  = "123"

Parameters:

array – the array of values to join together, may be null.
delimiter – the separator character to use.
startIndex – the first index to start joining from. It is an error to pass in a start 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:

3.2

public static String joinWith(String delimiter, Object... array)[source]¶

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

No delimiter is added before or after the list. null elements and separator are treated as empty Strings (“”).

StringUtils.joinWith(",", "a", "b")        = "a,b"
StringUtils.joinWith(",", "a", "b","")     = "a,b,"
StringUtils.joinWith(",", "a", null, "b")  = "a,,b"
StringUtils.joinWith(null, "a", "b")       = "ab"

Parameters:

delimiter – The separator character to use, null treated as “”.
array – The varargs providing the values to join together. null elements are treated as “”.

Returns:

The joined String.

Throws:

java.lang.IllegalArgumentException – Thrown if a null varargs is provided.

Since:

3.5

public static int lastIndexOf(CharSequence seq, int searchChar)[source]¶

Returns the index within seq of the last occurrence of the specified character. For values of searchChar in the range from 0 to 0xFFFF (inclusive), the index (in Unicode code units) returned is the largest value k such that:

this.charAt(k) == searchChar

is true. For other values of searchChar, it is the largest value k such that:

this.codePointAt(k) == searchChar

is true. In either case, if no such character occurs in this string, then -1 is returned. Furthermore, a null or empty (“”) CharSequence will return -1. The seq CharSequence object is searched backwards starting at the last character.

StringUtils.lastIndexOf(null, *)         = -1
StringUtils.lastIndexOf("", *)           = -1
StringUtils.lastIndexOf("aabaabaa", 'a') = 7
StringUtils.lastIndexOf("aabaabaa", 'b') = 5

Parameters:

seq – The CharSequence 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:

3.6 Updated CharSequenceUtils call to behave more like String

public static int lastIndexOf(CharSequence seq, int searchChar, int startPos)[source]¶

Returns the index within seq of the last occurrence of the specified character, searching backward starting at the specified index. For values of searchChar in the range from 0 to 0xFFFF (inclusive), the index returned is the largest value k such that:

(this.charAt(k) == searchChar) && (k <= startPos)

is true. For other values of searchChar, it is the largest value k such that:

(this.codePointAt(k) == searchChar) && (k <= startPos)

is true. In either case, if no such character occurs in seq at or before position startPos, then -1 is returned. Furthermore, a null or empty (“”) CharSequence will return -1. A start position greater than the string length searches the whole string. The search starts at the startPos and works backwards; matches starting after the start position are ignored.

All indices are specified in char values (Unicode code units).

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:

seq – The CharSequence to check, may be null.
searchChar – The character to find.
startPos – The start position.

Returns:

The last index of the search character (always ≤ startPos), -1 if no match or null string input.

Since:

3.0 Changed signature from lastIndexOf(String, int, int) to lastIndexOf(CharSequence, int, int)

@Deprecated public static int lastIndexOf(CharSequence seq, CharSequence searchSeq)[source]¶

Deprecated: Use Strings.CS.lastIndexOf(CharSequence, CharSequence).

Finds the last index within a CharSequence, handling null. This method uses String#lastIndexOf(String) if possible.

A null CharSequence will return -1.

StringUtils.lastIndexOf(null, *)          = -1
StringUtils.lastIndexOf(*, null)          = -1
StringUtils.lastIndexOf("", "")           = 0
StringUtils.lastIndexOf("aabaabaa", "a")  = 7
StringUtils.lastIndexOf("aabaabaa", "b")  = 5
StringUtils.lastIndexOf("aabaabaa", "ab") = 4
StringUtils.lastIndexOf("aabaabaa", "")   = 8

Parameters:

seq – The CharSequence to check, may be null.
searchSeq – The CharSequence to find, may be null.

Returns:

The last index of the search String, -1 if no match or null string input.

Since:

3.0 Changed signature from lastIndexOf(String, String) to lastIndexOf(CharSequence, CharSequence)

@Deprecated public static int lastIndexOf(CharSequence seq, CharSequence searchSeq, int startPos)[source]¶

Deprecated: Use Strings.CS.lastIndexOf(CharSequence, CharSequence, int).

Finds the last index within a CharSequence, handling null. This method uses String#lastIndexOf(String, int) if possible.

A null CharSequence will return -1. A negative start position returns -1. An empty (“”) search CharSequence always matches unless the start position is negative. A start position greater than the string length searches the whole string. The search starts at the startPos and works backwards; matches starting after the start position are ignored.

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
StringUtils.lastIndexOf("aabaabaa", "b", 1)  = -1
StringUtils.lastIndexOf("aabaabaa", "b", 2)  = 2
StringUtils.lastIndexOf("aabaabaa", "ba", 2)  = 2

Parameters:

seq – The CharSequence to check, may be null.
searchSeq – The CharSequence to find, may be null.
startPos – The start position, negative treated as zero.

Returns:

The last index of the search CharSequence (always ≤ startPos), -1 if no match or null string input.

Since:

3.0 Changed signature from lastIndexOf(String, String, int) to lastIndexOf(CharSequence, CharSequence, int)

public static int lastIndexOfAny(CharSequence str, CharSequence... searchStrs)[source]¶

Finds the latest index of any substring in a set of potential substrings.

A null CharSequence 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) if possible

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 CharSequence to check, may be null.
searchStrs – The CharSequences to search for, may be null.

Returns:

The last index of any of the CharSequences, -1 if no match.

Since:

3.0 Changed signature from lastIndexOfAny(String, String[]) to lastIndexOfAny(CharSequence, CharSequence)

@Deprecated public static int lastIndexOfIgnoreCase(CharSequence str, CharSequence searchStr)[source]¶

Deprecated: Use Strings.CI.lastIndexOf(CharSequence, CharSequence).

Case insensitive find of the last index within a CharSequence.

StringUtils.lastIndexOfIgnoreCase(null, *)          = -1
StringUtils.lastIndexOfIgnoreCase(*, null)          = -1
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A")  = 7
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B")  = 5
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "AB") = 4

Parameters:

str – The CharSequence to check, may be null.
searchStr – The CharSequence to find, may be null.

Returns:

The first index of the search CharSequence, -1 if no match or null string input.

Since:

3.0 Changed signature from lastIndexOfIgnoreCase(String, String) to lastIndexOfIgnoreCase(CharSequence, CharSequence)

@Deprecated public static int lastIndexOfIgnoreCase(CharSequence str, CharSequence searchStr, int startPos)[source]¶

Deprecated: Use Strings.CI.lastIndexOf(CharSequence, CharSequence, int).

Case insensitive find of the last index within a CharSequence from the specified position.

StringUtils.lastIndexOfIgnoreCase(null, *, *)          = -1
StringUtils.lastIndexOfIgnoreCase(*, null, *)          = -1
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A", 8)  = 7
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 8)  = 5
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "AB", 8) = 4
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 9)  = 5
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", -1) = -1
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A", 0)  = 0
StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 0)  = -1

Parameters:

str – The CharSequence to check, may be null.
searchStr – The CharSequence to find, may be null.
startPos – The start position.

Returns:

The last index of the search CharSequence (always ≤ startPos), -1 if no match or null input.

Since:

3.0 Changed signature from lastIndexOfIgnoreCase(String, String, int) to lastIndexOfIgnoreCase(CharSequence, CharSequence, int)

public static int lastOrdinalIndexOf(CharSequence str, CharSequence searchStr, int ordinal)[source]¶

Finds the n-th last index within a String, handling null. This method uses String#lastIndexOf(String).

A null String will return -1.

StringUtils.lastOrdinalIndexOf(null, *, *)          = -1
StringUtils.lastOrdinalIndexOf(*, null, *)          = -1
StringUtils.lastOrdinalIndexOf("", "", *)           = 0
StringUtils.lastOrdinalIndexOf("aabaabaa", "a", 1)  = 7
StringUtils.lastOrdinalIndexOf("aabaabaa", "a", 2)  = 6
StringUtils.lastOrdinalIndexOf("aabaabaa", "b", 1)  = 5
StringUtils.lastOrdinalIndexOf("aabaabaa", "b", 2)  = 2
StringUtils.lastOrdinalIndexOf("aabaabaa", "ab", 1) = 4
StringUtils.lastOrdinalIndexOf("aabaabaa", "ab", 2) = 1
StringUtils.lastOrdinalIndexOf("aabaabaa", "", 1)   = 8
StringUtils.lastOrdinalIndexOf("aabaabaa", "", 2)   = 8

Note that ‘tail(CharSequence str, int n)’ may be implemented as:

str.substring(lastOrdinalIndexOf(str, "\n", n) + 1)

Parameters:

str – The CharSequence to check, may be null.
searchStr – The CharSequence to find, may be null.
ordinal – The n-th last searchStr to find.

Returns:

The n-th last index of the search CharSequence, -1 (INDEX_NOT_FOUND) if no match or null string input.

Since:

3.0 Changed signature from lastOrdinalIndexOf(String, String, int) to lastOrdinalIndexOf(CharSequence, CharSequence, int)

public static String left(String str, int len)[source]¶

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 empty String is returned 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.

Returns:

The leftmost characters, null if null String input.

public static String leftPad(String str, int size)[source]¶

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.

public static String leftPad(String str, int size, char padChar)[source]¶

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

public static String leftPad(String str, int size, String padStr)[source]¶

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.

public static int length(CharSequence cs)[source]¶

Gets a CharSequence length or 0 if the CharSequence is null.

Parameters:: cs – A CharSequence or null.
Returns:: CharSequence length or 0 if the CharSequence is null.
Since:: 3.0 Changed signature from length(String) to length(CharSequence)

public static String lowerCase(String str)[source]¶

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"

Note: As described in the documentation for String#toLowerCase(), the result of this method is affected by the current locale. For platform-independent case transformations, the method #lowerCase(String, Locale) should be used with a specific locale (e.g. Locale#ENGLISH).

Parameters:: str – The String to lower case, may be null.
Returns:: The lower cased String, null if null String input.

public static String lowerCase(String str, Locale locale)[source]¶

Converts a String to lower case as per String#toLowerCase(Locale).

A null input String returns null.

StringUtils.lowerCase(null, Locale.ENGLISH)  = null
StringUtils.lowerCase("", Locale.ENGLISH)    = ""
StringUtils.lowerCase("aBc", Locale.ENGLISH) = "abc"

Parameters:

str – The String to lower case, may be null.
locale – The locale that defines the case transformation rules, must not be null.

Returns:

The lower cased String, null if null String input.

Since:

2.5

public static String mid(String str, int pos, int len)[source]¶

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 empty String is returned if len is negative or exceeds the length of str.

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.

Returns:

The middle characters, null if null String input.

public static String normalizeSpace(String str)[source]¶

This function returns the argument string with whitespace normalized by using {@link #trim(String)} to remove leading and trailing whitespace and then replacing sequences of whitespace characters by a single space.

In XML, whitespace characters are the same as those allowed by the S production, which is S ::= (#x20 | #x9 | #xD | #xA)+

Java’s regexp pattern \s defines whitespace as [ \t\n\x0B\f\r]

For reference:

\x0B = vertical tab
\f = #xC = form feed
#x20 = space
#x9 = \t
#xA = \n
#xD = \r

The difference is that Java’s whitespace includes vertical tab and form feed, which this function will also normalize. Additionally {@link #trim(String)} removes control characters (char <= 32) from both ends of this String.

Parameters:

str – The source String to normalize whitespaces from, may be null.

Returns:

The modified string with whitespace normalized, null if null String input.

See also:

Since:

3.0

public static int ordinalIndexOf(CharSequence str, CharSequence searchStr, int ordinal)[source]¶

Finds the n-th index within a CharSequence, handling null. This method uses String#indexOf(String) if possible.

Note: The code starts looking for a match at the start of the target, incrementing the starting index by one after each successful match (unless searchStr is an empty string, in which case the position is never incremented and 0 is returned immediately). This means that matches may overlap.

A null CharSequence 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

Matches may overlap:

StringUtils.ordinalIndexOf("ababab", "aba", 1)   = 0
StringUtils.ordinalIndexOf("ababab", "aba", 2)   = 2
StringUtils.ordinalIndexOf("ababab", "aba", 3)   = -1

StringUtils.ordinalIndexOf("abababab", "abab", 1) = 0
StringUtils.ordinalIndexOf("abababab", "abab", 2) = 2
StringUtils.ordinalIndexOf("abababab", "abab", 3) = 4
StringUtils.ordinalIndexOf("abababab", "abab", 4) = -1

Note that ‘head(CharSequence str, int n)’ may be implemented as:

str.substring(0, lastOrdinalIndexOf(str, "\n", n))

Parameters:

str – The CharSequence to check, may be null.
searchStr – The CharSequence to find, may be null.
ordinal – The n-th searchStr to find.

Returns:

The n-th index of the search CharSequence, -1 (INDEX_NOT_FOUND) if no match or null string input.

Since:

3.0 Changed signature from ordinalIndexOf(String, String, int) to ordinalIndexOf(CharSequence, CharSequence, int)

public static String overlay(String str, String overlay, int start, int end)[source]¶

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:

overlaid String, null if null String input.

Since:

2.0

@Deprecated public static String prependIfMissing(String str, CharSequence prefix, CharSequence... prefixes)[source]¶

Deprecated: Use Strings.CS.prependIfMissing(String, CharSequence, CharSequence...).

Prepends the prefix to the start of the string if the string does not already start with any of the prefixes.

StringUtils.prependIfMissing(null, null) = null
StringUtils.prependIfMissing("abc", null) = "abc"
StringUtils.prependIfMissing("", "xyz") = "xyz"
StringUtils.prependIfMissing("abc", "xyz") = "xyzabc"
StringUtils.prependIfMissing("xyzabc", "xyz") = "xyzabc"
StringUtils.prependIfMissing("XYZabc", "xyz") = "xyzXYZabc"

With additional prefixes,

StringUtils.prependIfMissing(null, null, null) = null
StringUtils.prependIfMissing("abc", null, null) = "abc"
StringUtils.prependIfMissing("", "xyz", null) = "xyz"
StringUtils.prependIfMissing("abc", "xyz", new CharSequence[]{null}) = "xyzabc"
StringUtils.prependIfMissing("abc", "xyz", "") = "abc"
StringUtils.prependIfMissing("abc", "xyz", "mno") = "xyzabc"
StringUtils.prependIfMissing("xyzabc", "xyz", "mno") = "xyzabc"
StringUtils.prependIfMissing("mnoabc", "xyz", "mno") = "mnoabc"
StringUtils.prependIfMissing("XYZabc", "xyz", "mno") = "xyzXYZabc"
StringUtils.prependIfMissing("MNOabc", "xyz", "mno") = "xyzMNOabc"

Parameters:

str – The string.
prefix – The prefix to prepend to the start of the string.
prefixes – Additional prefixes that are valid.

Returns:

A new String if prefix was prepended, the same string otherwise.

Since:

3.2

@Deprecated public static String prependIfMissingIgnoreCase(String str, CharSequence prefix, CharSequence... prefixes)[source]¶

Deprecated: Use Strings.CI.prependIfMissing(String, CharSequence, CharSequence...).

Prepends the prefix to the start of the string if the string does not already start, case-insensitive, with any of the prefixes.

StringUtils.prependIfMissingIgnoreCase(null, null) = null
StringUtils.prependIfMissingIgnoreCase("abc", null) = "abc"
StringUtils.prependIfMissingIgnoreCase("", "xyz") = "xyz"
StringUtils.prependIfMissingIgnoreCase("abc", "xyz") = "xyzabc"
StringUtils.prependIfMissingIgnoreCase("xyzabc", "xyz") = "xyzabc"
StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz") = "XYZabc"

With additional prefixes,

StringUtils.prependIfMissingIgnoreCase(null, null, null) = null
StringUtils.prependIfMissingIgnoreCase("abc", null, null) = "abc"
StringUtils.prependIfMissingIgnoreCase("", "xyz", null) = "xyz"
StringUtils.prependIfMissingIgnoreCase("abc", "xyz", new CharSequence[]{null}) = "xyzabc"
StringUtils.prependIfMissingIgnoreCase("abc", "xyz", "") = "abc"
StringUtils.prependIfMissingIgnoreCase("abc", "xyz", "mno") = "xyzabc"
StringUtils.prependIfMissingIgnoreCase("xyzabc", "xyz", "mno") = "xyzabc"
StringUtils.prependIfMissingIgnoreCase("mnoabc", "xyz", "mno") = "mnoabc"
StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz", "mno") = "XYZabc"
StringUtils.prependIfMissingIgnoreCase("MNOabc", "xyz", "mno") = "MNOabc"

Parameters:

str – The string.
prefix – The prefix to prepend to the start of the string.
prefixes – Additional prefixes that are valid (optional).

Returns:

A new String if prefix was prepended, the same string otherwise.

Since:

3.2

public static String remove(String str, char remove)[source]¶

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

@Deprecated public static String remove(String str, String remove)[source]¶

Deprecated: Use Strings.CS.remove(String, String).

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

@Deprecated public static String removeAll(String text, String regex)[source]¶

Deprecated: Use RegExUtils#removeAll(String, String).

Removes each substring of the text String that matches the given regular expression. This method is a null safe equivalent to:

text.replaceAll(regex, StringUtils.EMPTY)
Pattern.compile(regex).matcher(text).replaceAll(StringUtils.EMPTY)

A null reference passed to this method is a no-op.

Unlike in the #removePattern(String, String) method, the Pattern#DOTALL option is NOT automatically added. To use the DOTALL option prepend "(?s)" to the regex. DOTALL is also known as single-line mode in Perl.

StringUtils.removeAll(null, *)      = null
StringUtils.removeAll("any", (String) null)  = "any"
StringUtils.removeAll("any", "")    = "any"
StringUtils.removeAll("any", ".*")  = ""
StringUtils.removeAll("any", ".+")  = ""
StringUtils.removeAll("abc", ".?")  = ""
StringUtils.removeAll("A<__>\n<__>B", "<.*>")      = "A\nB"
StringUtils.removeAll("A<__>\n<__>B", "(?s)<.*>")  = "AB"
StringUtils.removeAll("ABCabc123abc", "[a-z]")     = "ABC123"

Parameters:

text – text to remove from, may be null.
regex – The regular expression to which this string is to be matched.

Returns:

The text with any removes processed, null if null String input.

Throws:

java.util.regex.PatternSyntaxException – Thrown if the regular expression’s syntax is invalid.

See also:

Since:

3.5

@Deprecated public static String removeEnd(String str, String remove)[source]¶

Deprecated: Use Strings.CS.removeEnd(String, CharSequence).

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

@Deprecated public static String removeEndIgnoreCase(String str, String remove)[source]¶

Deprecated: Use Strings.CI.removeEnd(String, CharSequence).

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.removeEndIgnoreCase(null, *)      = null
StringUtils.removeEndIgnoreCase("", *)        = ""
StringUtils.removeEndIgnoreCase(*, null)      = *
StringUtils.removeEndIgnoreCase("www.domain.com", ".com.")  = "www.domain.com"
StringUtils.removeEndIgnoreCase("www.domain.com", ".com")   = "www.domain"
StringUtils.removeEndIgnoreCase("www.domain.com", "domain") = "www.domain.com"
StringUtils.removeEndIgnoreCase("abc", "")    = "abc"
StringUtils.removeEndIgnoreCase("www.domain.com", ".COM") = "www.domain"
StringUtils.removeEndIgnoreCase("www.domain.COM", ".com") = "www.domain"

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

@Deprecated public static String removeFirst(String text, String regex)[source]¶

Deprecated: Use RegExUtils.replaceFirst(String, String, EMPTY).

Removes the first substring of the text string that matches the given regular expression. This method is a null safe equivalent to:

text.replaceFirst(regex, StringUtils.EMPTY)
Pattern.compile(regex).matcher(text).replaceFirst(StringUtils.EMPTY)

A null reference passed to this method is a no-op.

The Pattern#DOTALL option is NOT automatically added. To use the DOTALL option prepend "(?s)" to the regex. DOTALL is also known as single-line mode in Perl.

StringUtils.removeFirst(null, *)      = null
StringUtils.removeFirst("any", (String) null)  = "any"
StringUtils.removeFirst("any", "")    = "any"
StringUtils.removeFirst("any", ".*")  = ""
StringUtils.removeFirst("any", ".+")  = ""
StringUtils.removeFirst("abc", ".?")  = "bc"
StringUtils.removeFirst("A<__>\n<__>B", "<.*>")      = "A\n<__>B"
StringUtils.removeFirst("A<__>\n<__>B", "(?s)<.*>")  = "AB"
StringUtils.removeFirst("ABCabc123", "[a-z]")          = "ABCbc123"
StringUtils.removeFirst("ABCabc123abc", "[a-z]+")      = "ABC123abc"

Parameters:

text – text to remove from, may be null.
regex – The regular expression to which this string is to be matched.

Returns:

The text with the first replacement processed, null if null String input.

Throws:

java.util.regex.PatternSyntaxException – Thrown if the regular expression’s syntax is invalid.

See also:

Since:

3.5

@Deprecated public static String removeIgnoreCase(String str, String remove)[source]¶

Deprecated: Use Strings.CI.remove(String, String).

Case-insensitive removal of all occurrences of a substring from within the source string.

StringUtils.removeIgnoreCase(null, *)        = null
StringUtils.removeIgnoreCase("", *)          = ""
StringUtils.removeIgnoreCase(*, null)        = *
StringUtils.removeIgnoreCase(*, "")          = *
StringUtils.removeIgnoreCase("queued", "ue") = "qd"
StringUtils.removeIgnoreCase("queued", "zz") = "queued"
StringUtils.removeIgnoreCase("quEUed", "UE") = "qd"
StringUtils.removeIgnoreCase("queued", "zZ") = "queued"

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:

3.5

@Deprecated public static String removePattern(String source, String regex)[source]¶

Deprecated: Use RegExUtils#removePattern(CharSequence, String).

Removes each substring of the source String that matches the given regular expression using the DOTALL option. This call is a null safe equivalent to:

source.replaceAll("(?s)" + regex, StringUtils.EMPTY)
Pattern.compile(regex, Pattern.DOTALL).matcher(source).replaceAll(StringUtils.EMPTY)

A null reference passed to this method is a no-op.

StringUtils.removePattern(null, *)       = null
StringUtils.removePattern("any", (String) null)   = "any"
StringUtils.removePattern("A<__>\n<__>B", "<.*>")  = "AB"
StringUtils.removePattern("ABCabc123", "[a-z]")    = "ABC123"

Parameters:

source – The source string.
regex – The regular expression to which this string is to be matched.

Returns:

The resulting String.

See also:

Since:

3.5 Changed null reference passed to this method is a no-op.

public static String removeStart(String str, char remove)[source]¶

Removes a char only if it is at the beginning 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 char will return the source string.

StringUtils.removeStart(null, *)      = null
StringUtils.removeStart("", *)        = ""
StringUtils.removeStart(*, null)      = *
StringUtils.removeStart("/path", '/') = "path"
StringUtils.removeStart("path", '/')  = "path"
StringUtils.removeStart("path", 0)    = "path"

Parameters:

str – The source String to search, may be null.
remove – The char to search for and remove.

Returns:

The substring with the char removed if found, null if null String input.

Since:

3.13.0

@Deprecated public static String removeStart(String str, String remove)[source]¶

Deprecated: Use Strings.CS.removeStart(String, CharSequence).

Removes a substring only if it is at the beginning 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

@Deprecated public static String removeStartIgnoreCase(String str, String remove)[source]¶

Deprecated: Use Strings.CI.removeStart(String, CharSequence).

Case-insensitive removal of a substring if it is at the beginning 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

public static String repeat(char repeat, int count)[source]¶

Returns padding using the specified delimiter repeated to a given length.

StringUtils.repeat('e', 0)  = ""
StringUtils.repeat('e', 3)  = "eee"
StringUtils.repeat('e', -2) = ""

Note: this method does not support padding with Unicode Supplementary Characters as they require a pair of chars to be represented. If you are needing to support full I18N of your applications consider using #repeat(String, int) instead.

Parameters:

repeat – character to repeat.
count – number of times to repeat char, negative treated as zero.

Returns:

String with repeated character.

See also:

#repeat(String, int)

public static String repeat(String repeat, int count)[source]¶

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

repeat – The String to repeat, may be null.
count – 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.

public static String repeat(String repeat, String separator, int count)[source]¶

Repeats a String repeat times to form a new String, with a String separator injected each time.

StringUtils.repeat(null, null, 2) = null
StringUtils.repeat(null, "x", 2)  = null
StringUtils.repeat("", null, 0)   = ""
StringUtils.repeat("", "", 2)     = ""
StringUtils.repeat("", "x", 3)    = "xx"
StringUtils.repeat("?", ", ", 3)  = "?, ?, ?"

Parameters:

repeat – The String to repeat, may be null.
separator – The String to inject, may be null.
count – 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.

Since:

2.5

@Deprecated public static String replace(String text, String searchString, String replacement)[source]¶

Deprecated: Use Strings.CS.replace(String, String, String).

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.

@Deprecated public static String replace(String text, String searchString, String replacement, int max)[source]¶

Deprecated: Use Strings.CS.replace(String, String, String, int).

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.

@Deprecated public static String replaceAll(String text, String regex, String replacement)[source]¶

Deprecated: Use RegExUtils#replaceAll(String, String, String).

Replaces each substring of the text String that matches the given regular expression with the given replacement. This method is a null safe equivalent to:

text.replaceAll(regex, replacement)
Pattern.compile(regex).matcher(text).replaceAll(replacement)

A null reference passed to this method is a no-op.

Unlike in the #replacePattern(String, String, String) method, the Pattern#DOTALL option is NOT automatically added. To use the DOTALL option prepend "(?s)" to the regex. DOTALL is also known as single-line mode in Perl.

StringUtils.replaceAll(null, *, *)                                         = null
StringUtils.replaceAll("any", (String) null, *)                            = "any"
StringUtils.replaceAll("any", *, null)                                     = "any"
StringUtils.replaceAll("", "", "zzz")                                      = "zzz"
StringUtils.replaceAll("", ".*", "zzz")                                    = "zzz"
StringUtils.replaceAll("", ".+", "zzz")                                    = ""
StringUtils.replaceAll("abc", "", "ZZ")                                    = "ZZaZZbZZcZZ"
StringUtils.replaceAll("<__>\n<__>", "<.*>", "z")                          = "z\nz"
StringUtils.replaceAll("<__>\n<__>", "(?s)<.*>", "z")                      = "z"
StringUtils.replaceAll("ABCabc123", "[a-z]", "_")                          = "ABC___123"
StringUtils.replaceAll("ABCabc123", "[^A-Z0-9]+", "_")                     = "ABC_123"
StringUtils.replaceAll("ABCabc123", "[^A-Z0-9]+", "")                      = "ABC123"
StringUtils.replaceAll("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum_dolor_sit"

Parameters:

text – text to search and replace in, may be null.
regex – The regular expression to which this string is to be matched.
replacement – The string to be substituted for each match.

Returns:

The text with any replacements processed, null if null String input.

Throws:

java.util.regex.PatternSyntaxException – Thrown if the regular expression’s syntax is invalid.

See also:

Since:

3.5

public static String replaceChars(String str, char searchChar, char replaceChar)[source]¶

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

public static String replaceChars(String str, String searchChars, String replaceChars)[source]¶

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

public static String replaceEach(String text, String[] searchList, String[] replacementList)[source]¶

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:

java.lang.IllegalArgumentException – Thrown if the lengths of the arrays are not the same (null is ok, and/or size 0).

Since:

2.4

public static String replaceEachRepeatedly(String text, String[] searchList, String[] replacementList)[source]¶

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.

 StringUtils.replaceEachRepeatedly(null, *, *)                                                = null
 StringUtils.replaceEachRepeatedly("", *, *)                                                  = ""
 StringUtils.replaceEachRepeatedly("aba", null, null)                                         = "aba"
 StringUtils.replaceEachRepeatedly("aba", new String[0], null)                                = "aba"
 StringUtils.replaceEachRepeatedly("aba", null, new String[0])                                = "aba"
 StringUtils.replaceEachRepeatedly("aba", new String[]{"a"}, null)                            = "aba"
 StringUtils.replaceEachRepeatedly("aba", new String[]{"a"}, new String[]{""})                = "b"
 StringUtils.replaceEachRepeatedly("aba", new String[]{null}, new String[]{"a"})              = "aba"
 StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"})  = "wcte"
 (example of how it repeats)
 StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"})  = "tcte"
 StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}) = Throws IllegalStateException

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:

java.lang.IllegalStateException – Thrown if the search is repeating and there is an endless loop due to outputs of one being inputs to another.
java.lang.IllegalArgumentException – Thrown if the lengths of the arrays are not the same (null is ok, and/or size 0).

Since:

2.4

@Deprecated public static String replaceFirst(String text, String regex, String replacement)[source]¶

Deprecated: Use RegExUtils#replaceFirst(String, String, String).

Replaces the first substring of the text string that matches the given regular expression with the given replacement. This method is a null safe equivalent to:

text.replaceFirst(regex, replacement)
Pattern.compile(regex).matcher(text).replaceFirst(replacement)

A null reference passed to this method is a no-op.

The Pattern#DOTALL option is NOT automatically added. To use the DOTALL option prepend "(?s)" to the regex. DOTALL is also known as single-line mode in Perl.

StringUtils.replaceFirst(null, *, *)       = null
StringUtils.replaceFirst("any", (String) null, *)   = "any"
StringUtils.replaceFirst("any", *, null)   = "any"
StringUtils.replaceFirst("", "", "zzz")    = "zzz"
StringUtils.replaceFirst("", ".*", "zzz")  = "zzz"
StringUtils.replaceFirst("", ".+", "zzz")  = ""
StringUtils.replaceFirst("abc", "", "ZZ")  = "ZZabc"
StringUtils.replaceFirst("<__>\n<__>", "<.*>", "z")      = "z\n<__>"
StringUtils.replaceFirst("<__>\n<__>", "(?s)<.*>", "z")  = "z"
StringUtils.replaceFirst("ABCabc123", "[a-z]", "_")          = "ABC_bc123"
StringUtils.replaceFirst("ABCabc123abc", "[^A-Z0-9]+", "_")  = "ABC_123abc"
StringUtils.replaceFirst("ABCabc123abc", "[^A-Z0-9]+", "")   = "ABC123abc"
StringUtils.replaceFirst("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum  dolor   sit"

Parameters:

text – text to search and replace in, may be null.
regex – The regular expression to which this string is to be matched.
replacement – The string to be substituted for the first match.

Returns:

The text with the first replacement processed, null if null String input.

Throws:

java.util.regex.PatternSyntaxException – Thrown if the regular expression’s syntax is invalid.

See also:

Since:

3.5

@Deprecated public static String replaceIgnoreCase(String text, String searchString, String replacement)[source]¶

Deprecated: Use Strings.CI.replace(String, String, String).

Case insensitively replaces all occurrences of a String within another String.

A null reference passed to this method is a no-op.

StringUtils.replaceIgnoreCase(null, *, *)        = null
StringUtils.replaceIgnoreCase("", *, *)          = ""
StringUtils.replaceIgnoreCase("any", null, *)    = "any"
StringUtils.replaceIgnoreCase("any", *, null)    = "any"
StringUtils.replaceIgnoreCase("any", "", *)      = "any"
StringUtils.replaceIgnoreCase("aba", "a", null)  = "aba"
StringUtils.replaceIgnoreCase("abA", "A", "")    = "b"
StringUtils.replaceIgnoreCase("aba", "A", "z")   = "zbz"

Parameters:

text – text to search and replace in, may be null.
searchString – The String to search for (case-insensitive), 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.

Since:

3.5

@Deprecated public static String replaceIgnoreCase(String text, String searchString, String replacement, int max)[source]¶

Deprecated: Use Strings.CI.replace(String, String, String, int).

Case insensitively 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.replaceIgnoreCase(null, *, *, *)         = null
StringUtils.replaceIgnoreCase("", *, *, *)           = ""
StringUtils.replaceIgnoreCase("any", null, *, *)     = "any"
StringUtils.replaceIgnoreCase("any", *, null, *)     = "any"
StringUtils.replaceIgnoreCase("any", "", *, *)       = "any"
StringUtils.replaceIgnoreCase("any", *, *, 0)        = "any"
StringUtils.replaceIgnoreCase("abaa", "a", null, -1) = "abaa"
StringUtils.replaceIgnoreCase("abaa", "a", "", -1)   = "b"
StringUtils.replaceIgnoreCase("abaa", "a", "z", 0)   = "abaa"
StringUtils.replaceIgnoreCase("abaa", "A", "z", 1)   = "zbaa"
StringUtils.replaceIgnoreCase("abAa", "a", "z", 2)   = "zbza"
StringUtils.replaceIgnoreCase("abAa", "a", "z", -1)  = "zbzz"

Parameters:

text – text to search and replace in, may be null.
searchString – The String to search for (case-insensitive), 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.

Since:

3.5

@Deprecated public static String replaceOnce(String text, String searchString, String replacement)[source]¶

Deprecated: Use Strings.CS.replaceOnce(String, String, String).

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.

@Deprecated public static String replaceOnceIgnoreCase(String text, String searchString, String replacement)[source]¶

Deprecated: Use Strings.CI.replaceOnce(String, String, String).

Case insensitively replaces a String with another String inside a larger String, once.

A null reference passed to this method is a no-op.

StringUtils.replaceOnceIgnoreCase(null, *, *)        = null
StringUtils.replaceOnceIgnoreCase("", *, *)          = ""
StringUtils.replaceOnceIgnoreCase("any", null, *)    = "any"
StringUtils.replaceOnceIgnoreCase("any", *, null)    = "any"
StringUtils.replaceOnceIgnoreCase("any", "", *)      = "any"
StringUtils.replaceOnceIgnoreCase("aba", "a", null)  = "aba"
StringUtils.replaceOnceIgnoreCase("aba", "a", "")    = "ba"
StringUtils.replaceOnceIgnoreCase("aba", "a", "z")   = "zba"
StringUtils.replaceOnceIgnoreCase("FoOFoofoo", "foo", "") = "Foofoo"

Parameters:

text – text to search and replace in, may be null.
searchString – The String to search for (case-insensitive), may be null.
replacement – The String to replace with, may be null.

Returns:

The text with any replacements processed, null if null String input.

Since:

3.5

@Deprecated public static String replacePattern(String source, String regex, String replacement)[source]¶

Deprecated: Use RegExUtils#replacePattern(CharSequence, String, String).

Replaces each substring of the source String that matches the given regular expression with the given replacement using the Pattern#DOTALL option. DOTALL is also known as single-line mode in Perl. This call is a null safe equivalent to:

source.replaceAll("(?s)" + regex, replacement)
Pattern.compile(regex, Pattern.DOTALL).matcher(source).replaceAll(replacement)

A null reference passed to this method is a no-op.

StringUtils.replacePattern(null, *, *)                                         = null
StringUtils.replacePattern("any", (String) null, *)                            = "any"
StringUtils.replacePattern("any", *, null)                                     = "any"
StringUtils.replacePattern("", "", "zzz")                                      = "zzz"
StringUtils.replacePattern("", ".*", "zzz")                                    = "zzz"
StringUtils.replacePattern("", ".+", "zzz")                                    = ""
StringUtils.replacePattern("<__>\n<__>", "<.*>", "z")                          = "z"
StringUtils.replacePattern("ABCabc123", "[a-z]", "_")                          = "ABC___123"
StringUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", "_")                     = "ABC_123"
StringUtils.replacePattern("ABCabc123", "[^A-Z0-9]+", "")                      = "ABC123"
StringUtils.replacePattern("Lorem ipsum  dolor   sit", "( +)([a-z]+)", "_$2")  = "Lorem_ipsum_dolor_sit"

Parameters:

source – The source string.
regex – The regular expression to which this string is to be matched.
replacement – The string to be substituted for each match.

Returns:

The resulting String.

See also:

Since:

3.5 Changed null reference passed to this method is a no-op.

public static String reverse(String str)[source]¶

Reverses a String as per StringBuilder#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.

public static String reverseDelimited(String str, char separatorChar)[source]¶

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

public static String right(String str, int len)[source]¶

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 exception. An empty String is returned 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.

Returns:

The rightmost characters, null if null String input.

public static String rightPad(String str, int size)[source]¶

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.

public static String rightPad(String str, int size, char padChar)[source]¶

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

public static String rightPad(String str, int size, String padStr)[source]¶

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.

public static String rotate(String str, int shift)[source]¶

Rotate (circular shift) a String of shift characters.

If shift > 0, right circular shift (ex : ABCDEF => FABCDE)
If shift < 0, left circular shift (ex : ABCDEF => BCDEFA)

StringUtils.rotate(null, *)        = null
StringUtils.rotate("", *)          = ""
StringUtils.rotate("abcdefg", 0)   = "abcdefg"
StringUtils.rotate("abcdefg", 2)   = "fgabcde"
StringUtils.rotate("abcdefg", -2)  = "cdefgab"
StringUtils.rotate("abcdefg", 7)   = "abcdefg"
StringUtils.rotate("abcdefg", -7)  = "abcdefg"
StringUtils.rotate("abcdefg", 9)   = "fgabcde"
StringUtils.rotate("abcdefg", -9)  = "cdefgab"

Parameters:

str – The String to rotate, may be null.
shift – number of time to shift (positive : right shift, negative : left shift).

Returns:

The rotated String, or the original String if shift == 0, or null if null String input.

Since:

3.5

public static String[] split(String str)[source]¶

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.

public static String[] split(String str, char separatorChar)[source]¶

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

public static String[] split(String str, String separatorChars)[source]¶

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.

public static String[] split(String str, String separatorChars, int max)[source]¶

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 cd ef", null, 0)   = ["ab", "cd", "ef"]
StringUtils.split("ab   cd ef", 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.

public static String[] splitByCharacterType(String str)[source]¶

Splits a String by Character type as returned by Character#getType(int). 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.
See also:: Character#getType(int)
Since:: 2.4

public static String[] splitByCharacterTypeCamelCase(String str)[source]¶

Splits a String by Character type as returned by Character#getType(int). 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.
See also:: Character#getType(int)
Since:: 2.4

public static String[] splitByWholeSeparator(String str, String separator)[source]¶

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.

public static String[] splitByWholeSeparator(String str, String separator, int max)[source]¶

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.

public static String[] splitByWholeSeparatorPreserveAllTokens(String str, String separator)[source]¶

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

public static String[] splitByWholeSeparatorPreserveAllTokens(String str, String separator, int max)[source]¶

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

public static String[] splitPreserveAllTokens(String str)[source]¶

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

public static String[] splitPreserveAllTokens(String str, char separatorChar)[source]¶

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

public static String[] splitPreserveAllTokens(String str, String separatorChars)[source]¶

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

public static String[] splitPreserveAllTokens(String str, String separatorChars, int max)[source]¶

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", "de", "fg"]
StringUtils.splitPreserveAllTokens("ab   de fg", null, 0) = ["ab", "", "", "de", "fg"]
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

@Deprecated public static boolean startsWith(CharSequence str, CharSequence prefix)[source]¶

Deprecated: Use Strings.CS.startsWith(CharSequence, CharSequence).

Tests if a CharSequence 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, "abc")     = false
StringUtils.startsWith("abcdef", null)  = false
StringUtils.startsWith("abcdef", "abc") = true
StringUtils.startsWith("ABCDEF", "abc") = false

Parameters:

str – The CharSequence to check, may be null.
prefix – The prefix to find, may be null.

Returns:

true if the CharSequence starts with the prefix, case-sensitive, or both null.

See also:

String#startsWith(String)

Since:

3.0 Changed signature from startsWith(String, String) to startsWith(CharSequence, CharSequence)

@Deprecated public static boolean startsWithAny(CharSequence sequence, CharSequence... searchStrings)[source]¶

Deprecated: Use Strings.CS.startsWithAny(CharSequence, CharSequence...).

Tests if a CharSequence starts with any of the provided case-sensitive prefixes.

StringUtils.startsWithAny(null, null)      = false
StringUtils.startsWithAny(null, new String[] {"abc"})  = false
StringUtils.startsWithAny("abcxyz", null)     = false
StringUtils.startsWithAny("abcxyz", new String[] {""}) = true
StringUtils.startsWithAny("abcxyz", new String[] {"abc"}) = true
StringUtils.startsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
StringUtils.startsWithAny("abcxyz", null, "xyz", "ABCX") = false
StringUtils.startsWithAny("ABCXYZ", null, "xyz", "abc") = false

Parameters:

sequence – The CharSequence to check, may be null.
searchStrings – The case-sensitive CharSequence prefixes, may be empty or contain null.

Returns:

true if the input sequence is null AND no searchStrings are provided, or the input sequence begins with any of the provided case-sensitive searchStrings.

Since:

3.0 Changed signature from startsWithAny(String, String[]) to startsWithAny(CharSequence, CharSequence…)

@Deprecated public static boolean startsWithIgnoreCase(CharSequence str, CharSequence prefix)[source]¶

Deprecated: Use Strings.CI.startsWith(CharSequence, CharSequence).

Case-insensitive check if a CharSequence 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, "abc")     = false
StringUtils.startsWithIgnoreCase("abcdef", null)  = false
StringUtils.startsWithIgnoreCase("abcdef", "abc") = true
StringUtils.startsWithIgnoreCase("ABCDEF", "abc") = true

Parameters:

str – The CharSequence to check, may be null.
prefix – The prefix to find, may be null.

Returns:

true if the CharSequence starts with the prefix, case-insensitive, or both null.

See also:

String#startsWith(String)

Since:

3.0 Changed signature from startsWithIgnoreCase(String, String) to startsWithIgnoreCase(CharSequence, CharSequence)

public static String strip(String str)[source]¶

Strips whitespace from the start and end of a String.

This is similar to #trim(String) but removes whitespace. Whitespace is defined by Character#isWhitespace(char).

A null input String returns null.

StringUtils.strip(null)     = null
StringUtils.strip("")       = ""
StringUtils.strip("   ")    = ""
StringUtils.strip("abc")    = "abc"
StringUtils.strip("  abc")  = "abc"
StringUtils.strip("abc  ")  = "abc"
StringUtils.strip(" abc ")  = "abc"
StringUtils.strip(" ab c ") = "ab c"

Parameters:: str – The String to remove whitespace from, may be null.
Returns:: The stripped String, null if null String input.

public static String strip(String str, String stripChars)[source]¶

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

StringUtils.strip(null, *)          = null
StringUtils.strip("", *)            = ""
StringUtils.strip("abc", null)      = "abc"
StringUtils.strip("  abc", null)    = "abc"
StringUtils.strip("abc  ", null)    = "abc"
StringUtils.strip(" abc ", null)    = "abc"
StringUtils.strip("  abcyx", "xyz") = "  abc"

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.

public static String stripAccents(String input)[source]¶

Removes diacritics (~= accents) from a string. The case will not be altered.

For instance, ‘à’ will be replaced by ‘a’.

Decomposes ligatures and digraphs per the KD column in the Unicode Normalization Chart.

Be aware that this NFKD compatibility decomposition can map non-letter compatibility forms (fullwidth, small-form, math-symbol variants of <, >, /, and so on) to their ASCII counterparts.

StringUtils.stripAccents(null)         = null
StringUtils.stripAccents("")           = ""
StringUtils.stripAccents("control")    = "control"
StringUtils.stripAccents("éclair")     = "eclair"
StringUtils.stripAccents("ᵃᵇᶜ¹²³")     = "abc123"
StringUtils.stripAccents("¼ ½ ¾")      = "1⁄4 1⁄2 3⁄4"

Parameters:: input – String to be stripped.
Returns:: input text with diacritics removed.
Since:: 3.0

public static String[] stripAll(String... strs)[source]¶

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.

public static String[] stripAll(String[] strs, String stripChars)[source]¶

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.

public static String stripEnd(String str, String stripChars)[source]¶

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"
StringUtils.stripEnd("120.00", ".0")   = "12"

Parameters:

str – The String to remove characters from, may be null.
stripChars – The set of characters to remove, null treated as whitespace.

Returns:

The stripped String, null if null String input.

public static String stripStart(String str, String stripChars)[source]¶

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.

public static String stripToEmpty(String str)[source]¶

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

This is similar to #trimToEmpty(String) but removes whitespace. Whitespace is defined by Character#isWhitespace(char).

StringUtils.stripToEmpty(null)     = ""
StringUtils.stripToEmpty("")       = ""
StringUtils.stripToEmpty("   ")    = ""
StringUtils.stripToEmpty("abc")    = "abc"
StringUtils.stripToEmpty("  abc")  = "abc"
StringUtils.stripToEmpty("abc  ")  = "abc"
StringUtils.stripToEmpty(" abc ")  = "abc"
StringUtils.stripToEmpty(" ab c ") = "ab c"

Parameters:: str – The String to be stripped, may be null.
Returns:: The trimmed String, or an empty String if null input.
Since:: 2.0

public static String stripToNull(String str)[source]¶

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(String) but removes whitespace. Whitespace is defined by Character#isWhitespace(char).

StringUtils.stripToNull(null)     = null
StringUtils.stripToNull("")       = null
StringUtils.stripToNull("   ")    = null
StringUtils.stripToNull("abc")    = "abc"
StringUtils.stripToNull("  abc")  = "abc"
StringUtils.stripToNull("abc  ")  = "abc"
StringUtils.stripToNull(" abc ")  = "abc"
StringUtils.stripToNull(" ab c ") = "ab c"

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

public static String substring(String str, int start)[source]¶

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.

public static String substring(String str, int start, int end)[source]¶

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 position, null if null String input.

public static String substringAfter(String str, int find)[source]¶

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.

If nothing is found, the empty string is returned.

StringUtils.substringAfter(null, *)      = null
StringUtils.substringAfter("", *)        = ""
StringUtils.substringAfter("abc", 'a')   = "bc"
StringUtils.substringAfter("abcba", 'b') = "cba"
StringUtils.substringAfter("abc", 'c')   = ""
StringUtils.substringAfter("abc", 'd')   = ""
StringUtils.substringAfter(" abc", 32)   = "abc"

Parameters:

str – The String to get a substring from, may be null.
find – The character (Unicode code point) to find.

Returns:

The substring after the first occurrence of the specified character, null if null String input.

Since:

3.11

public static String substringAfter(String str, String find)[source]¶

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.

If nothing is found, the empty string is returned.

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.
find – The String to find, may be null.

Returns:

The substring after the first occurrence of the specified string, null if null String input.

Since:

2.0

public static String substringAfterLast(String str, int find)[source]¶

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.

If nothing is found, the empty string is returned.

StringUtils.substringAfterLast(null, *)      = null
StringUtils.substringAfterLast("", *)        = ""
StringUtils.substringAfterLast("abc", 'a')   = "bc"
StringUtils.substringAfterLast(" bc", 32)    = "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.
find – The character (Unicode code point) to find.

Returns:

The substring after the last occurrence of the specified character, null if null String input.

Since:

3.11

public static String substringAfterLast(String str, String find)[source]¶

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.

If nothing is found, the empty string is returned.

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.
find – The String to find, may be null.

Returns:

The substring after the last occurrence of the specified string, null if null String input.

Since:

2.0

public static String substringBefore(String str, int find)[source]¶

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.

If nothing is found, the string input is returned.

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"

Parameters:

str – The String to get a substring from, may be null.
find – The character (Unicode code point) to find.

Returns:

The substring before the first occurrence of the specified character, null if null String input.

Since:

3.12.0

public static String substringBefore(String str, String find)[source]¶

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.

If nothing is found, the string input is returned.

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.
find – The String to find, may be null.

Returns:

The substring before the first occurrence of the specified string, null if null String input.

Since:

2.0

public static String substringBeforeLast(String str, String find)[source]¶

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.

If nothing is found, the string input is returned.

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.
find – The String to find, may be null.

Returns:

The substring before the last occurrence of the specified string, null if null String input.

Since:

2.0

public static String substringBetween(String str, String tag)[source]¶

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

public static String substringBetween(String str, String open, String close)[source]¶

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

public static String[] substringsBetween(String str, String open, String close)[source]¶

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

public static String swapCase(String str)[source]¶

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 org.apache.commons.text.WordUtils#swapCase(String). A null input String returns null.

StringUtils.swapCase(null)                 = null
StringUtils.swapCase("")                   = ""
StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"

NOTE: This method changed in Lang version 2.0. It no longer performs a word based algorithm. If you only use ASCII, you will notice no change. That functionality is available in org.apache.commons.lang3.text.WordUtils.

Parameters:: str – The String to swap case, may be null.
Returns:: The changed String, null if null String input.

public static int[] toCodePoints(CharSequence cs)[source]¶

Converts a CharSequence into an array of code points.

Valid pairs of surrogate code units will be converted into a single supplementary code point. Isolated surrogate code units (i.e. a high surrogate not followed by a low surrogate or a low surrogate not preceded by a high surrogate) will be returned as-is.

StringUtils.toCodePoints(null)   =  null
StringUtils.toCodePoints("")     =  []  // empty array

Parameters:: cs – The character sequence to convert.
Returns:: An array of code points.
Since:: 3.6

public static String toEncodedString(byte[] bytes, Charset charset)[source]¶

Converts a byte[] to a String using the specified character encoding.

Parameters:

bytes – The byte array to read from.
charset – The encoding to use, if null then use the platform default.

Returns:

A new String.

Throws:

java.lang.NullPointerException – Thrown if bytes is null.

Since:

3.3 No longer throws UnsupportedEncodingException.

public static String toRootLowerCase(String source)[source]¶

Converts the given source String as a lower-case using the Locale#ROOT locale in a null-safe manner.

Parameters:: source – A source String or null.
Returns:: The given source String as a lower-case using the Locale#ROOT locale or null.
Since:: 3.10

public static String toRootUpperCase(String source)[source]¶

Converts the given source String as an upper-case using the Locale#ROOT locale in a null-safe manner.

Parameters:: source – A source String or null.
Returns:: The given source String as an upper-case using the Locale#ROOT locale or null.
Since:: 3.10

@Deprecated public static String toString(byte[] bytes, String charsetName)[source]¶

Deprecated: Use StringUtils#toEncodedString(byte[], Charset) instead of String constants in your code.

Converts a byte[] to a String using the specified character encoding.

Parameters:

bytes – The byte array to read from.
charsetName – The encoding to use, if null then use the platform default.

Returns:

A new String.

Throws:

java.lang.NullPointerException – Thrown if the input is null.

Since:

3.1

public static String trim(String str)[source]¶

Removes control characters plus space (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(String).

To trim your choice of characters, use the #strip(String, String) 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.

public static String trimAsciiControl(String str)[source]¶

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

To trim your choice of characters, use the #strip(String, String) methods.

StringUtils.trimAsciiControl(null)          = null
StringUtils.trimAsciiControl("")            = ""
StringUtils.trimAsciiControl("abc\u0000")   = "abc"
StringUtils.trimAsciiControl("abc")         = "abc"
StringUtils.trimAsciiControl(" abc ")       = " abc "

Parameters:: str – The String to be trimmed, may be null.
Returns:: The trimmed string, null if null String input.
Since:: 3.21.0

public static String trimToEmpty(String str)[source]¶

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

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

public static String trimToNull(String str)[source]¶

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

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

public static String truncate(String str, int maxWidth)[source]¶

Truncates a String. 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 truncate it to substring(str, 0, maxWidth).
If maxWidth is less than 0, throw an IllegalArgumentException.
In no case will it return a String of length greater than maxWidth.

StringUtils.truncate(null, 0)       = null
StringUtils.truncate(null, 2)       = null
StringUtils.truncate("", 4)         = ""
StringUtils.truncate("abcdefg", 4)  = "abcd"
StringUtils.truncate("abcdefg", 6)  = "abcdef"
StringUtils.truncate("abcdefg", 7)  = "abcdefg"
StringUtils.truncate("abcdefg", 8)  = "abcdefg"
StringUtils.truncate("abcdefg", -1) = throws an IllegalArgumentException

Parameters:

str – The String to truncate, may be null.
maxWidth – maximum length of result String, must be non-negative.

Returns:

truncated String, null if null String input.

Throws:

java.lang.IllegalArgumentException – Thrown if maxWidth is less than 0.

Since:

3.5

public static String truncate(String str, int offset, int maxWidth)[source]¶

Truncates a String. This will turn “Now is the time for all good men” into “is the time for all”.

Works like truncate(String, int), but allows you to specify a “left edge” offset.

Specifically:

If str is less than maxWidth characters long, return it.
Else truncate it to substring(str, offset, maxWidth).
If maxWidth is less than 0, throw an IllegalArgumentException.
If offset is less than 0, throw an IllegalArgumentException.
In no case will it return a String of length greater than maxWidth.

StringUtils.truncate(null, 0, 0) = null
StringUtils.truncate(null, 2, 4) = null
StringUtils.truncate("", 0, 10) = ""
StringUtils.truncate("", 2, 10) = ""
StringUtils.truncate("abcdefghij", 0, 3) = "abc"
StringUtils.truncate("abcdefghij", 5, 6) = "fghij"
StringUtils.truncate("raspberry peach", 10, 15) = "peach"
StringUtils.truncate("abcdefghijklmno", 0, 10) = "abcdefghij"
StringUtils.truncate("abcdefghijklmno", -1, 10) = throws an IllegalArgumentException
StringUtils.truncate("abcdefghijklmno", Integer.MIN_VALUE, 10) = throws an IllegalArgumentException
StringUtils.truncate("abcdefghijklmno", Integer.MIN_VALUE, Integer.MAX_VALUE) = throws an IllegalArgumentException
StringUtils.truncate("abcdefghijklmno", 0, Integer.MAX_VALUE) = "abcdefghijklmno"
StringUtils.truncate("abcdefghijklmno", 1, 10) = "bcdefghijk"
StringUtils.truncate("abcdefghijklmno", 2, 10) = "cdefghijkl"
StringUtils.truncate("abcdefghijklmno", 3, 10) = "defghijklm"
StringUtils.truncate("abcdefghijklmno", 4, 10) = "efghijklmn"
StringUtils.truncate("abcdefghijklmno", 5, 10) = "fghijklmno"
StringUtils.truncate("abcdefghijklmno", 5, 5) = "fghij"
StringUtils.truncate("abcdefghijklmno", 5, 3) = "fgh"
StringUtils.truncate("abcdefghijklmno", 10, 3) = "klm"
StringUtils.truncate("abcdefghijklmno", 10, Integer.MAX_VALUE) = "klmno"
StringUtils.truncate("abcdefghijklmno", 13, 1) = "n"
StringUtils.truncate("abcdefghijklmno", 13, Integer.MAX_VALUE) = "no"
StringUtils.truncate("abcdefghijklmno", 14, 1) = "o"
StringUtils.truncate("abcdefghijklmno", 14, Integer.MAX_VALUE) = "o"
StringUtils.truncate("abcdefghijklmno", 15, 1) = ""
StringUtils.truncate("abcdefghijklmno", 15, Integer.MAX_VALUE) = ""
StringUtils.truncate("abcdefghijklmno", Integer.MAX_VALUE, Integer.MAX_VALUE) = ""
StringUtils.truncate("abcdefghij", 3, -1) = throws an IllegalArgumentException
StringUtils.truncate("abcdefghij", -2, 4) = throws an IllegalArgumentException

Parameters:

str – The String to truncate, may be null.
offset – left edge of source String.
maxWidth – maximum length of result String, must be non-negative.

Returns:

truncated String, null if null String input.

Throws:

java.lang.IllegalArgumentException – Thrown if offset or maxWidth is less than 0.

Since:

3.5

public static String uncapitalize(String str)[source]¶

Uncapitalizes a String, changing the first character to lower case as per Character#toLowerCase(int). No other characters are changed.

For a word based algorithm, see org.apache.commons.text.WordUtils#uncapitalize(String). A null input String returns null.

StringUtils.uncapitalize(null)  = null
StringUtils.uncapitalize("")    = ""
StringUtils.uncapitalize("cat") = "cat"
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.

See also:

org.apache.commons.text.WordUtils#uncapitalize(String)
#capitalize(String)

Since:

2.0

public static String unwrap(String str, char wrapChar)[source]¶

Unwraps a given string from a character.

StringUtils.unwrap(null, null)         = null
StringUtils.unwrap(null, '\0')         = null
StringUtils.unwrap(null, '1')          = null
StringUtils.unwrap("a", 'a')           = "a"
StringUtils.unwrap("aa", 'a')           = ""
StringUtils.unwrap("\'abc\'", '\'')    = "abc"
StringUtils.unwrap("AABabcBAA", 'A')   = "ABabcBA"
StringUtils.unwrap("A", '#')           = "A"
StringUtils.unwrap("#A", '#')          = "#A"
StringUtils.unwrap("A#", '#')          = "A#"

Parameters:

str – The String to be unwrapped, can be null.
wrapChar – The character used to unwrap.

Returns:

unwrapped String or the original string if it is not quoted properly with the wrapChar.

Since:

3.6

public static String unwrap(String str, String wrapToken)[source]¶

Unwraps a given string from another string.

StringUtils.unwrap(null, null)         = null
StringUtils.unwrap(null, "")           = null
StringUtils.unwrap(null, "1")          = null
StringUtils.unwrap("a", "a")           = "a"
StringUtils.unwrap("aa", "a")          = ""
StringUtils.unwrap("\'abc\'", "\'")    = "abc"
StringUtils.unwrap("\"abc\"", "\"")    = "abc"
StringUtils.unwrap("AABabcBAA", "AA")  = "BabcB"
StringUtils.unwrap("A", "#")           = "A"
StringUtils.unwrap("#A", "#")          = "#A"
StringUtils.unwrap("A#", "#")          = "A#"

Parameters:

str – The String to be unwrapped, can be null.
wrapToken – The String used to unwrap.

Returns:

unwrapped String or the original string if it is not quoted properly with the wrapToken.

Since:

3.6

public static String upperCase(String str)[source]¶

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"

Note: As described in the documentation for String#toUpperCase(), the result of this method is affected by the current locale. For platform-independent case transformations, the method #upperCase(String, Locale) should be used with a specific locale (e.g. Locale#ENGLISH).

Parameters:: str – The String to upper case, may be null.
Returns:: The upper-cased String, null if null String input.

public static String upperCase(String str, Locale locale)[source]¶

Converts a String to upper case as per String#toUpperCase(Locale).

A null input String returns null.

StringUtils.upperCase(null, Locale.ENGLISH)  = null
StringUtils.upperCase("", Locale.ENGLISH)    = ""
StringUtils.upperCase("aBc", Locale.ENGLISH) = "ABC"

Parameters:

str – The String to upper case, may be null.
locale – The locale that defines the case transformation rules, must not be null.

Returns:

The upper-cased String, null if null String input.

Since:

2.5

public static String valueOf(char[] value)[source]¶

Returns the string representation of the char array or null.

Parameters:: value – The character array.
Returns:: A String or null.
See also:: String#valueOf(char[])
Since:: 3.9

public static String wrap(String str, char wrapWith)[source]¶

Wraps a string with a char.

StringUtils.wrap(null, *)        = null
StringUtils.wrap("", *)          = ""
StringUtils.wrap("ab", '\0')     = "ab"
StringUtils.wrap("ab", 'x')      = "xabx"
StringUtils.wrap("ab", '\'')     = "'ab'"
StringUtils.wrap("\"ab\"", '\"') = "\"\"ab\"\""

Parameters:

str – The string to be wrapped, may be null.
wrapWith – The char that will wrap str.

Returns:

The wrapped string, or null if str == null.

Since:

3.4

public static String wrap(String str, String wrapWith)[source]¶

Wraps a String with another String.

A null input String returns null.

StringUtils.wrap(null, *)         = null
StringUtils.wrap("", *)           = ""
StringUtils.wrap("ab", null)      = "ab"
StringUtils.wrap("ab", "x")       = "xabx"
StringUtils.wrap("ab", "\"")      = "\"ab\""
StringUtils.wrap("\"ab\"", "\"")  = "\"\"ab\"\""
StringUtils.wrap("ab", "'")       = "'ab'"
StringUtils.wrap("'abcd'", "'")   = "''abcd''"
StringUtils.wrap("\"abcd\"", "'") = "'\"abcd\"'"
StringUtils.wrap("'abcd'", "\"")  = "\"'abcd'\""

Parameters:

str – The String to be wrapper, may be null.
wrapWith – The String that will wrap str.

Returns:

wrapped String, null if null String input.

Since:

3.4

public static String wrapIfMissing(String str, char wrapWith)[source]¶

Wraps a string with a char if that char is missing from the start or end of the given string.

A new String will not be created if str is already wrapped.

StringUtils.wrapIfMissing(null, *)        = null
StringUtils.wrapIfMissing("", *)          = ""
StringUtils.wrapIfMissing("ab", '\0')     = "ab"
StringUtils.wrapIfMissing("ab", 'x')      = "xabx"
StringUtils.wrapIfMissing("ab", '\'')     = "'ab'"
StringUtils.wrapIfMissing("\"ab\"", '\"') = "\"ab\""
StringUtils.wrapIfMissing("/", '/')  = "/"
StringUtils.wrapIfMissing("a/b/c", '/')  = "/a/b/c/"
StringUtils.wrapIfMissing("/a/b/c", '/')  = "/a/b/c/"
StringUtils.wrapIfMissing("a/b/c/", '/')  = "/a/b/c/"

Parameters:

str – The string to be wrapped, may be null.
wrapWith – The char that will wrap str.

Returns:

The wrapped string, or null if str == null.

Since:

3.5

public static String wrapIfMissing(String str, String wrapWith)[source]¶

Wraps a string with a string if that string is missing from the start or end of the given string.

A new String will not be created if str is already wrapped.

StringUtils.wrapIfMissing(null, *)         = null
StringUtils.wrapIfMissing("", *)           = ""
StringUtils.wrapIfMissing("ab", null)      = "ab"
StringUtils.wrapIfMissing("ab", "x")       = "xabx"
StringUtils.wrapIfMissing("ab", "\"")      = "\"ab\""
StringUtils.wrapIfMissing("\"ab\"", "\"")  = "\"ab\""
StringUtils.wrapIfMissing("ab", "'")       = "'ab'"
StringUtils.wrapIfMissing("'abcd'", "'")   = "'abcd'"
StringUtils.wrapIfMissing("\"abcd\"", "'") = "'\"abcd\"'"
StringUtils.wrapIfMissing("'abcd'", "\"")  = "\"'abcd'\""
StringUtils.wrapIfMissing("/", "/")  = "/"
StringUtils.wrapIfMissing("a/b/c", "/")  = "/a/b/c/"
StringUtils.wrapIfMissing("/a/b/c", "/")  = "/a/b/c/"
StringUtils.wrapIfMissing("a/b/c/", "/")  = "/a/b/c/"

Parameters:

str – The string to be wrapped, may be null.
wrapWith – The string that will wrap str.

Returns:

The wrapped string, or null if str == null.

Since:

3.5