Package org.apache.commons.lang3

## Class StringUtils

- java.lang.Object
- - org.apache.commons.lang3.StringUtils

    public class StringUtils
    extends java.lang.Object

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#

Since:
  1.0
See Also:
  `String`

### Field Summary

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

### Constructor Summary

Constructors
`StringUtils()` `StringUtils` instances should NOT be constructed in standard programming.

### Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
`static java.lang.String` `abbreviate​(java.lang.String str, int maxWidth)` Abbreviates a String using ellipses.
`static java.lang.String` `abbreviate​(java.lang.String str, int offset, int maxWidth)` Abbreviates a String using ellipses.
`static java.lang.String` `abbreviate​(java.lang.String str, java.lang.String abbrevMarker, int maxWidth)` Abbreviates a String using another given String as replacement marker.
`static java.lang.String` `abbreviate​(java.lang.String str, java.lang.String abbrevMarker, int offset, int maxWidth)` Abbreviates a String using a given replacement marker.
`static java.lang.String` `abbreviateMiddle​(java.lang.String str, java.lang.String middle, int length)` Abbreviates a String to the length passed, replacing the middle characters with the supplied replacement String.
`static java.lang.String` `appendIfMissing​(java.lang.String str, java.lang.CharSequence suffix, java.lang.CharSequence... suffixes)` Appends the suffix to the end of the string if the string does not already end with any of the suffixes.
`static java.lang.String` `appendIfMissingIgnoreCase​(java.lang.String str, java.lang.CharSequence suffix, java.lang.CharSequence... suffixes)` Appends the suffix to the end of the string if the string does not already end, case insensitive, with any of the suffixes.
`static java.lang.String` `capitalize​(java.lang.String str)` Capitalizes a String changing the first character to title case as per `Character.toTitleCase(int)`.
`static java.lang.String` `center​(java.lang.String str, int size)` Centers a String in a larger String of size `size` using the space character (' ').
`static java.lang.String` `center​(java.lang.String str, int size, char padChar)` Centers a String in a larger String of size `size`.
`static java.lang.String` `center​(java.lang.String str, int size, java.lang.String padStr)` Centers a String in a larger String of size `size`.
`static java.lang.String` `chomp​(java.lang.String str)` Removes one newline from end of a String if it's there, otherwise leave it alone.
`static java.lang.String` `chomp​(java.lang.String str, java.lang.String separator)` Deprecated. This feature will be removed in Lang 4.0, use `removeEnd(String, String)` instead
`static java.lang.String` `chop​(java.lang.String str)` Remove the last character from a String.
`static int` `compare​(java.lang.String str1, java.lang.String str2)` Compare two Strings lexicographically, as per `String.compareTo(String)`, returning :
`static int` `compare​(java.lang.String str1, java.lang.String str2, boolean nullIsLess)` Compare two Strings lexicographically, as per `String.compareTo(String)`, returning :
`static int` `compareIgnoreCase​(java.lang.String str1, java.lang.String str2)` Compare two Strings lexicographically, ignoring case differences, as per `String.compareToIgnoreCase(String)`, returning :
`static int` `compareIgnoreCase​(java.lang.String str1, java.lang.String str2, boolean nullIsLess)` Compare two Strings lexicographically, ignoring case differences, as per `String.compareToIgnoreCase(String)`, returning :
`static boolean` `contains​(java.lang.CharSequence seq, int searchChar)` Checks if CharSequence contains a search character, handling `null`.
`static boolean` `contains​(java.lang.CharSequence seq, java.lang.CharSequence searchSeq)` Checks if CharSequence contains a search CharSequence, handling `null`.
`static boolean` `containsAny​(java.lang.CharSequence cs, char... searchChars)` Checks if the CharSequence contains any character in the given set of characters.
`static boolean` `containsAny​(java.lang.CharSequence cs, java.lang.CharSequence searchChars)` Checks if the CharSequence contains any character in the given set of characters.
`static boolean` `containsAny​(java.lang.CharSequence cs, java.lang.CharSequence... searchCharSequences)` Checks if the CharSequence contains any of the CharSequences in the given array.
`static boolean` `containsIgnoreCase​(java.lang.CharSequence str, java.lang.CharSequence searchStr)` Checks if CharSequence contains a search CharSequence irrespective of case, handling `null`.
`static boolean` `containsNone​(java.lang.CharSequence cs, char... searchChars)` Checks that the CharSequence does not contain certain characters.
`static boolean` `containsNone​(java.lang.CharSequence cs, java.lang.String invalidChars)` Checks that the CharSequence does not contain certain characters.
`static boolean` `containsOnly​(java.lang.CharSequence cs, char... valid)` Checks if the CharSequence contains only certain characters.
`static boolean` `containsOnly​(java.lang.CharSequence cs, java.lang.String validChars)` Checks if the CharSequence contains only certain characters.
`static boolean` `containsWhitespace​(java.lang.CharSequence seq)` Check whether the given CharSequence contains any whitespace characters.
`static int` `countMatches​(java.lang.CharSequence str, char ch)` Counts how many times the char appears in the given string.
`static int` `countMatches​(java.lang.CharSequence str, java.lang.CharSequence sub)` Counts how many times the substring appears in the larger string.
`static <T extends java.lang.CharSequence> T` `defaultIfBlank​(T str, T defaultStr)` Returns either the passed in CharSequence, or if the CharSequence is whitespace, empty ("") or `null`, the value of `defaultStr`.
`static <T extends java.lang.CharSequence> T` `defaultIfEmpty​(T str, T defaultStr)` Returns either the passed in CharSequence, or if the CharSequence is empty or `null`, the value of `defaultStr`.
`static java.lang.String` `defaultString​(java.lang.String str)` Returns either the passed in String, or if the String is `null`, an empty String ("").
`static java.lang.String` `defaultString​(java.lang.String str, java.lang.String defaultStr)` Returns either the passed in String, or if the String is `null`, the value of `defaultStr`.
`static java.lang.String` `deleteWhitespace​(java.lang.String str)` Deletes all whitespaces from a String as defined by `Character.isWhitespace(char)`.
`static java.lang.String` `difference​(java.lang.String str1, java.lang.String str2)` Compares two Strings, and returns the portion where they differ.
`static boolean` `endsWith​(java.lang.CharSequence str, java.lang.CharSequence suffix)` Check if a CharSequence ends with a specified suffix.
`static boolean` `endsWithAny​(java.lang.CharSequence sequence, java.lang.CharSequence... searchStrings)` Check if a CharSequence ends with any of the provided case-sensitive suffixes.
`static boolean` `endsWithIgnoreCase​(java.lang.CharSequence str, java.lang.CharSequence suffix)` Case insensitive check if a CharSequence ends with a specified suffix.
`static boolean` `equals​(java.lang.CharSequence cs1, java.lang.CharSequence cs2)` Compares two CharSequences, returning `true` if they represent equal sequences of characters.
`static boolean` `equalsAny​(java.lang.CharSequence string, java.lang.CharSequence... searchStrings)` Compares given `string` to a CharSequences vararg of `searchStrings`, returning `true` if the `string` is equal to any of the `searchStrings`.
`static boolean` `equalsAnyIgnoreCase​(java.lang.CharSequence string, java.lang.CharSequence... searchStrings)` Compares given `string` to a CharSequences vararg of `searchStrings`, returning `true` if the `string` is equal to any of the `searchStrings`, ignoring case.
`static boolean` `equalsIgnoreCase​(java.lang.CharSequence cs1, java.lang.CharSequence cs2)` Compares two CharSequences, returning `true` if they represent equal sequences of characters, ignoring case.
`static <T extends java.lang.CharSequence> T` `firstNonBlank​(T... values)` Returns the first value in the array which is not empty (""), `null` or whitespace only.
`static <T extends java.lang.CharSequence> T` `firstNonEmpty​(T... values)` Returns the first value in the array which is not empty.
`static byte[]` `getBytes​(java.lang.String string, java.lang.String charset)` Calls `String.getBytes(String)` in a null-safe manner.
`static byte[]` `getBytes​(java.lang.String string, java.nio.charset.Charset charset)` Calls `String.getBytes(Charset)` in a null-safe manner.
`static java.lang.String` `getCommonPrefix​(java.lang.String... strs)` Compares all Strings in an array and returns the initial sequence of characters that is common to all of them.
`static java.lang.String` `getDigits​(java.lang.String str)` Checks if a String `str` contains Unicode digits, if yes then concatenate all the digits in `str` and return it as a String.
`static int` `getFuzzyDistance​(java.lang.CharSequence term, java.lang.CharSequence query, java.util.Locale locale)` Deprecated. as of 3.6, use commons-text FuzzyScore instead
`static <T extends java.lang.CharSequence> T` `getIfBlank​(T str, java.util.function.Supplier<T> defaultSupplier)` Returns either the passed in CharSequence, or if the CharSequence is whitespace, empty ("") or `null`, the value supplied by `defaultStrSupplier`.
`static <T extends java.lang.CharSequence> T` `getIfEmpty​(T str, java.util.function.Supplier<T> defaultSupplier)` Returns either the passed in CharSequence, or if the CharSequence is empty or `null`, the value supplied by `defaultStrSupplier`.
`static double` `getJaroWinklerDistance​(java.lang.CharSequence first, java.lang.CharSequence second)` Deprecated. as of 3.6, use commons-text JaroWinklerDistance instead
`static int` `getLevenshteinDistance​(java.lang.CharSequence s, java.lang.CharSequence t)` Deprecated. as of 3.6, use commons-text LevenshteinDistance instead
`static int` `getLevenshteinDistance​(java.lang.CharSequence s, java.lang.CharSequence t, int threshold)` Deprecated. as of 3.6, use commons-text LevenshteinDistance instead
`static int` `indexOf​(java.lang.CharSequence seq, int searchChar)` Returns the index within `seq` of the first occurrence of the specified character.
`static int` `indexOf​(java.lang.CharSequence seq, int searchChar, int startPos)` Returns the index within `seq` of the first occurrence of the specified character, starting the search at the specified index.
`static int` `indexOf​(java.lang.CharSequence seq, java.lang.CharSequence searchSeq)` Finds the first index within a CharSequence, handling `null`.
`static int` `indexOf​(java.lang.CharSequence seq, java.lang.CharSequence searchSeq, int startPos)` Finds the first index within a CharSequence, handling `null`.
`static int` `indexOfAny​(java.lang.CharSequence cs, char... searchChars)` Search a CharSequence to find the first index of any character in the given set of characters.
`static int` `indexOfAny​(java.lang.CharSequence str, java.lang.CharSequence... searchStrs)` Find the first index of any of a set of potential substrings.
`static int` `indexOfAny​(java.lang.CharSequence cs, java.lang.String searchChars)` Search a CharSequence to find the first index of any character in the given set of characters.
`static int` `indexOfAnyBut​(java.lang.CharSequence cs, char... searchChars)` Searches a CharSequence to find the first index of any character not in the given set of characters.
`static int` `indexOfAnyBut​(java.lang.CharSequence seq, java.lang.CharSequence searchChars)` Search a CharSequence to find the first index of any character not in the given set of characters.
`static int` `indexOfDifference​(java.lang.CharSequence... css)` Compares all CharSequences in an array and returns the index at which the CharSequences begin to differ.
`static int` `indexOfDifference​(java.lang.CharSequence cs1, java.lang.CharSequence cs2)` Compares two CharSequences, and returns the index at which the CharSequences begin to differ.
`static int` `indexOfIgnoreCase​(java.lang.CharSequence str, java.lang.CharSequence searchStr)` Case in-sensitive find of the first index within a CharSequence.
`static int` `indexOfIgnoreCase​(java.lang.CharSequence str, java.lang.CharSequence searchStr, int startPos)` Case in-sensitive find of the first index within a CharSequence from the specified position.
`static boolean` `isAllBlank​(java.lang.CharSequence... css)` Checks if all of the CharSequences are empty (""), null or whitespace only.
`static boolean` `isAllEmpty​(java.lang.CharSequence... css)` Checks if all of the CharSequences are empty ("") or null.
`static boolean` `isAllLowerCase​(java.lang.CharSequence cs)` Checks if the CharSequence contains only lowercase characters.
`static boolean` `isAllUpperCase​(java.lang.CharSequence cs)` Checks if the CharSequence contains only uppercase characters.
`static boolean` `isAlpha​(java.lang.CharSequence cs)` Checks if the CharSequence contains only Unicode letters.
`static boolean` `isAlphanumeric​(java.lang.CharSequence cs)` Checks if the CharSequence contains only Unicode letters or digits.
`static boolean` `isAlphanumericSpace​(java.lang.CharSequence cs)` Checks if the CharSequence contains only Unicode letters, digits or space (`' '`).
`static boolean` `isAlphaSpace​(java.lang.CharSequence cs)` Checks if the CharSequence contains only Unicode letters and space (' ').
`static boolean` `isAnyBlank​(java.lang.CharSequence... css)` Checks if any of the CharSequences are empty ("") or null or whitespace only.
`static boolean` `isAnyEmpty​(java.lang.CharSequence... css)` Checks if any of the CharSequences are empty ("") or null.
`static boolean` `isAsciiPrintable​(java.lang.CharSequence cs)` Checks if the CharSequence contains only ASCII printable characters.
`static boolean` `isBlank​(java.lang.CharSequence cs)` Checks if a CharSequence is empty (""), null or whitespace only.
`static boolean` `isEmpty​(java.lang.CharSequence cs)` Checks if a CharSequence is empty ("") or null.
`static boolean` `isMixedCase​(java.lang.CharSequence cs)` Checks if the CharSequence contains mixed casing of both uppercase and lowercase characters.
`static boolean` `isNoneBlank​(java.lang.CharSequence... css)` Checks if none of the CharSequences are empty (""), null or whitespace only.
`static boolean` `isNoneEmpty​(java.lang.CharSequence... css)` Checks if none of the CharSequences are empty ("") or null.
`static boolean` `isNotBlank​(java.lang.CharSequence cs)` Checks if a CharSequence is not empty (""), not null and not whitespace only.
`static boolean` `isNotEmpty​(java.lang.CharSequence cs)` Checks if a CharSequence is not empty ("") and not null.
`static boolean` `isNumeric​(java.lang.CharSequence cs)` Checks if the CharSequence contains only Unicode digits.
`static boolean` `isNumericSpace​(java.lang.CharSequence cs)` Checks if the CharSequence contains only Unicode digits or space (`' '`).
`static boolean` `isWhitespace​(java.lang.CharSequence cs)` Checks if the CharSequence contains only whitespace.
`static java.lang.String` `join​(byte[] array, char separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(byte[] array, char separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(char[] array, char separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(char[] array, char separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(double[] array, char separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(double[] array, char separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(float[] array, char separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(float[] array, char separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(int[] array, char separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(int[] array, char separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(long[] array, char separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(long[] array, char separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(short[] array, char separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(short[] array, char separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(java.lang.Iterable<?> iterable, char separator)` Joins the elements of the provided `Iterable` into a single String containing the provided elements.
`static java.lang.String` `join​(java.lang.Iterable<?> iterable, java.lang.String separator)` Joins the elements of the provided `Iterable` into a single String containing the provided elements.
`static java.lang.String` `join​(java.lang.Object[] array, char separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(java.lang.Object[] array, char separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(java.lang.Object[] array, java.lang.String separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(java.lang.Object[] array, java.lang.String separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `join​(java.util.Iterator<?> iterator, char separator)` Joins the elements of the provided `Iterator` into a single String containing the provided elements.
`static java.lang.String` `join​(java.util.Iterator<?> iterator, java.lang.String separator)` Joins the elements of the provided `Iterator` into a single String containing the provided elements.
`static java.lang.String` `join​(java.util.List<?> list, char separator, int startIndex, int endIndex)` Joins the elements of the provided `List` into a single String containing the provided list of elements.
`static java.lang.String` `join​(java.util.List<?> list, java.lang.String separator, int startIndex, int endIndex)` Joins the elements of the provided `List` into a single String containing the provided list of elements.
`static <T> java.lang.String` `join​(T... elements)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static java.lang.String` `joinWith​(java.lang.String separator, java.lang.Object... objects)` Joins the elements of the provided varargs into a single String containing the provided elements.
`static int` `lastIndexOf​(java.lang.CharSequence seq, int searchChar)` Returns the index within `seq` of the last occurrence of the specified character.
`static int` `lastIndexOf​(java.lang.CharSequence seq, int searchChar, int startPos)` Returns the index within `seq` of the last occurrence of the specified character, searching backward starting at the specified index.
`static int` `lastIndexOf​(java.lang.CharSequence seq, java.lang.CharSequence searchSeq)` Finds the last index within a CharSequence, handling `null`.
`static int` `lastIndexOf​(java.lang.CharSequence seq, java.lang.CharSequence searchSeq, int startPos)` Finds the last index within a CharSequence, handling `null`.
`static int` `lastIndexOfAny​(java.lang.CharSequence str, java.lang.CharSequence... searchStrs)` Find the latest index of any substring in a set of potential substrings.
`static int` `lastIndexOfIgnoreCase​(java.lang.CharSequence str, java.lang.CharSequence searchStr)` Case in-sensitive find of the last index within a CharSequence.
`static int` `lastIndexOfIgnoreCase​(java.lang.CharSequence str, java.lang.CharSequence searchStr, int startPos)` Case in-sensitive find of the last index within a CharSequence from the specified position.
`static int` `lastOrdinalIndexOf​(java.lang.CharSequence str, java.lang.CharSequence searchStr, int ordinal)` Finds the n-th last index within a String, handling `null`.
`static java.lang.String` `left​(java.lang.String str, int len)` Gets the leftmost `len` characters of a String.
`static java.lang.String` `leftPad​(java.lang.String str, int size)` Left pad a String with spaces (' ').
`static java.lang.String` `leftPad​(java.lang.String str, int size, char padChar)` Left pad a String with a specified character.
`static java.lang.String` `leftPad​(java.lang.String str, int size, java.lang.String padStr)` Left pad a String with a specified String.
`static int` `length​(java.lang.CharSequence cs)` Gets a CharSequence length or `0` if the CharSequence is `null`.
`static java.lang.String` `lowerCase​(java.lang.String str)` Converts a String to lower case as per `String.toLowerCase()`.
`static java.lang.String` `lowerCase​(java.lang.String str, java.util.Locale locale)` Converts a String to lower case as per `String.toLowerCase(Locale)`.
`static java.lang.String` `mid​(java.lang.String str, int pos, int len)` Gets `len` characters from the middle of a String.
`static java.lang.String` `normalizeSpace​(java.lang.String str)` Similar to http://www.w3.org/TR/xpath/#function-normalize -space
`static int` `ordinalIndexOf​(java.lang.CharSequence str, java.lang.CharSequence searchStr, int ordinal)` Finds the n-th index within a CharSequence, handling `null`.
`static java.lang.String` `overlay​(java.lang.String str, java.lang.String overlay, int start, int end)` Overlays part of a String with another String.
`static java.lang.String` `prependIfMissing​(java.lang.String str, java.lang.CharSequence prefix, java.lang.CharSequence... prefixes)` Prepends the prefix to the start of the string if the string does not already start with any of the prefixes.
`static java.lang.String` `prependIfMissingIgnoreCase​(java.lang.String str, java.lang.CharSequence prefix, java.lang.CharSequence... prefixes)` Prepends the prefix to the start of the string if the string does not already start, case insensitive, with any of the prefixes.
`static java.lang.String` `remove​(java.lang.String str, char remove)` Removes all occurrences of a character from within the source string.
`static java.lang.String` `remove​(java.lang.String str, java.lang.String remove)` Removes all occurrences of a substring from within the source string.
`static java.lang.String` `removeAll​(java.lang.String text, java.lang.String regex)` Deprecated. Moved to RegExUtils.
`static java.lang.String` `removeEnd​(java.lang.String str, java.lang.String remove)` Removes a substring only if it is at the end of a source string, otherwise returns the source string.
`static java.lang.String` `removeEndIgnoreCase​(java.lang.String str, java.lang.String remove)` Case insensitive removal of a substring if it is at the end of a source string, otherwise returns the source string.
`static java.lang.String` `removeFirst​(java.lang.String text, java.lang.String regex)` Deprecated. Moved to RegExUtils.
`static java.lang.String` `removeIgnoreCase​(java.lang.String str, java.lang.String remove)` Case insensitive removal of all occurrences of a substring from within the source string.
`static java.lang.String` `removePattern​(java.lang.String source, java.lang.String regex)` Deprecated. Moved to RegExUtils.
`static java.lang.String` `removeStart​(java.lang.String str, java.lang.String remove)` Removes a substring only if it is at the beginning of a source string, otherwise returns the source string.
`static java.lang.String` `removeStartIgnoreCase​(java.lang.String str, java.lang.String remove)` Case insensitive removal of a substring if it is at the beginning of a source string, otherwise returns the source string.
`static java.lang.String` `repeat​(char ch, int repeat)` Returns padding using the specified delimiter repeated to a given length.
`static java.lang.String` `repeat​(java.lang.String str, int repeat)` Repeat a String `repeat` times to form a new String.
`static java.lang.String` `repeat​(java.lang.String str, java.lang.String separator, int repeat)` Repeat a String `repeat` times to form a new String, with a String separator injected each time.
`static java.lang.String` `replace​(java.lang.String text, java.lang.String searchString, java.lang.String replacement)` Replaces all occurrences of a String within another String.
`static java.lang.String` `replace​(java.lang.String text, java.lang.String searchString, java.lang.String replacement, int max)` Replaces a String with another String inside a larger String, for the first `max` values of the search String.
`static java.lang.String` `replaceAll​(java.lang.String text, java.lang.String regex, java.lang.String replacement)` Deprecated. Moved to RegExUtils.
`static java.lang.String` `replaceChars​(java.lang.String str, char searchChar, char replaceChar)` Replaces all occurrences of a character in a String with another.
`static java.lang.String` `replaceChars​(java.lang.String str, java.lang.String searchChars, java.lang.String replaceChars)` Replaces multiple characters in a String in one go.
`static java.lang.String` `replaceEach​(java.lang.String text, java.lang.String[] searchList, java.lang.String[] replacementList)` Replaces all occurrences of Strings within another String.
`static java.lang.String` `replaceEachRepeatedly​(java.lang.String text, java.lang.String[] searchList, java.lang.String[] replacementList)` Replaces all occurrences of Strings within another String.
`static java.lang.String` `replaceFirst​(java.lang.String text, java.lang.String regex, java.lang.String replacement)` Deprecated. Moved to RegExUtils.
`static java.lang.String` `replaceIgnoreCase​(java.lang.String text, java.lang.String searchString, java.lang.String replacement)` Case insensitively replaces all occurrences of a String within another String.
`static java.lang.String` `replaceIgnoreCase​(java.lang.String text, java.lang.String searchString, java.lang.String replacement, int max)` Case insensitively replaces a String with another String inside a larger String, for the first `max` values of the search String.
`static java.lang.String` `replaceOnce​(java.lang.String text, java.lang.String searchString, java.lang.String replacement)` Replaces a String with another String inside a larger String, once.
`static java.lang.String` `replaceOnceIgnoreCase​(java.lang.String text, java.lang.String searchString, java.lang.String replacement)` Case insensitively replaces a String with another String inside a larger String, once.
`static java.lang.String` `replacePattern​(java.lang.String source, java.lang.String regex, java.lang.String replacement)` Deprecated. Moved to RegExUtils.
`static java.lang.String` `reverse​(java.lang.String str)` Reverses a String as per `StringBuilder.reverse()`.
`static java.lang.String` `reverseDelimited​(java.lang.String str, char separatorChar)` Reverses a String that is delimited by a specific character.
`static java.lang.String` `right​(java.lang.String str, int len)` Gets the rightmost `len` characters of a String.
`static java.lang.String` `rightPad​(java.lang.String str, int size)` Right pad a String with spaces (' ').
`static java.lang.String` `rightPad​(java.lang.String str, int size, char padChar)` Right pad a String with a specified character.
`static java.lang.String` `rightPad​(java.lang.String str, int size, java.lang.String padStr)` Right pad a String with a specified String.
`static java.lang.String` `rotate​(java.lang.String str, int shift)` Rotate (circular shift) a String of `shift` characters.
`static java.lang.String[]` `split​(java.lang.String str)` Splits the provided text into an array, using whitespace as the separator.
`static java.lang.String[]` `split​(java.lang.String str, char separatorChar)` Splits the provided text into an array, separator specified.
`static java.lang.String[]` `split​(java.lang.String str, java.lang.String separatorChars)` Splits the provided text into an array, separators specified.
`static java.lang.String[]` `split​(java.lang.String str, java.lang.String separatorChars, int max)` Splits the provided text into an array with a maximum length, separators specified.
`static java.lang.String[]` `splitByCharacterType​(java.lang.String str)` Splits a String by Character type as returned by `java.lang.Character.getType(char)`.
`static java.lang.String[]` `splitByCharacterTypeCamelCase​(java.lang.String str)` Splits a String by Character type as returned by `java.lang.Character.getType(char)`.
`static java.lang.String[]` `splitByWholeSeparator​(java.lang.String str, java.lang.String separator)` Splits the provided text into an array, separator string specified.
`static java.lang.String[]` `splitByWholeSeparator​(java.lang.String str, java.lang.String separator, int max)` Splits the provided text into an array, separator string specified.
`static java.lang.String[]` `splitByWholeSeparatorPreserveAllTokens​(java.lang.String str, java.lang.String separator)` Splits the provided text into an array, separator string specified.
`static java.lang.String[]` `splitByWholeSeparatorPreserveAllTokens​(java.lang.String str, java.lang.String separator, int max)` Splits the provided text into an array, separator string specified.
`static java.lang.String[]` `splitPreserveAllTokens​(java.lang.String str)` Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators.
`static java.lang.String[]` `splitPreserveAllTokens​(java.lang.String str, char separatorChar)` Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators.
`static java.lang.String[]` `splitPreserveAllTokens​(java.lang.String str, java.lang.String separatorChars)` Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators.
`static java.lang.String[]` `splitPreserveAllTokens​(java.lang.String str, java.lang.String separatorChars, int max)` Splits the provided text into an array with a maximum length, separators specified, preserving all tokens, including empty tokens created by adjacent separators.
`static boolean` `startsWith​(java.lang.CharSequence str, java.lang.CharSequence prefix)` Check if a CharSequence starts with a specified prefix.
`static boolean` `startsWithAny​(java.lang.CharSequence sequence, java.lang.CharSequence... searchStrings)` Check if a CharSequence starts with any of the provided case-sensitive prefixes.
`static boolean` `startsWithIgnoreCase​(java.lang.CharSequence str, java.lang.CharSequence prefix)` Case insensitive check if a CharSequence starts with a specified prefix.
`static java.lang.String` `strip​(java.lang.String str)` Strips whitespace from the start and end of a String.
`static java.lang.String` `strip​(java.lang.String str, java.lang.String stripChars)` Strips any of a set of characters from the start and end of a String.
`static java.lang.String` `stripAccents​(java.lang.String input)` Removes diacritics (~= accents) from a string.
`static java.lang.String[]` `stripAll​(java.lang.String... strs)` Strips whitespace from the start and end of every String in an array.
`static java.lang.String[]` `stripAll​(java.lang.String[] strs, java.lang.String stripChars)` Strips any of a set of characters from the start and end of every String in an array.
`static java.lang.String` `stripEnd​(java.lang.String str, java.lang.String stripChars)` Strips any of a set of characters from the end of a String.
`static java.lang.String` `stripStart​(java.lang.String str, java.lang.String stripChars)` Strips any of a set of characters from the start of a String.
`static java.lang.String` `stripToEmpty​(java.lang.String str)` Strips whitespace from the start and end of a String returning an empty String if `null` input.
`static java.lang.String` `stripToNull​(java.lang.String str)` Strips whitespace from the start and end of a String returning `null` if the String is empty ("") after the strip.
`static java.lang.String` `substring​(java.lang.String str, int start)` Gets a substring from the specified String avoiding exceptions.
`static java.lang.String` `substring​(java.lang.String str, int start, int end)` Gets a substring from the specified String avoiding exceptions.
`static java.lang.String` `substringAfter​(java.lang.String str, int separator)` Gets the substring after the first occurrence of a separator.
`static java.lang.String` `substringAfter​(java.lang.String str, java.lang.String separator)` Gets the substring after the first occurrence of a separator.
`static java.lang.String` `substringAfterLast​(java.lang.String str, int separator)` Gets the substring after the last occurrence of a separator.
`static java.lang.String` `substringAfterLast​(java.lang.String str, java.lang.String separator)` Gets the substring after the last occurrence of a separator.
`static java.lang.String` `substringBefore​(java.lang.String str, java.lang.String separator)` Gets the substring before the first occurrence of a separator.
`static java.lang.String` `substringBeforeLast​(java.lang.String str, java.lang.String separator)` Gets the substring before the last occurrence of a separator.
`static java.lang.String` `substringBetween​(java.lang.String str, java.lang.String tag)` Gets the String that is nested in between two instances of the same String.
`static java.lang.String` `substringBetween​(java.lang.String str, java.lang.String open, java.lang.String close)` Gets the String that is nested in between two Strings.
`static java.lang.String[]` `substringsBetween​(java.lang.String str, java.lang.String open, java.lang.String close)` Searches a String for substrings delimited by a start and end tag, returning all matching substrings in an array.
`static java.lang.String` `swapCase​(java.lang.String str)` Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
`static int[]` `toCodePoints​(java.lang.CharSequence str)` Converts a `CharSequence` into an array of code points.
`static java.lang.String` `toEncodedString​(byte[] bytes, java.nio.charset.Charset charset)` Converts a `byte[]` to a String using the specified character encoding.
`static java.lang.String` `toRootLowerCase​(java.lang.String source)` Converts the given source String as a lower-case using the `Locale.ROOT` locale in a null-safe manner.
`static java.lang.String` `toRootUpperCase​(java.lang.String source)` Converts the given source String as a upper-case using the `Locale.ROOT` locale in a null-safe manner.
`static java.lang.String` `toString​(byte[] bytes, java.lang.String charsetName)` Deprecated. use `toEncodedString(byte[], Charset)` instead of String constants in your code
`static java.lang.String` `trim​(java.lang.String str)` Removes control characters (char <= 32) from both ends of this String, handling `null` by returning `null`.
`static java.lang.String` `trimToEmpty​(java.lang.String str)` Removes control characters (char <= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if it is `null`.
`static java.lang.String` `trimToNull​(java.lang.String str)` Removes control characters (char <= 32) from both ends of this String returning `null` if the String is empty ("") after the trim or if it is `null`.
`static java.lang.String` `truncate​(java.lang.String str, int maxWidth)` Truncates a String.
`static java.lang.String` `truncate​(java.lang.String str, int offset, int maxWidth)` Truncates a String.
`static java.lang.String` `uncapitalize​(java.lang.String str)` Uncapitalizes a String, changing the first character to lower case as per `Character.toLowerCase(int)`.
`static java.lang.String` `unwrap​(java.lang.String str, char wrapChar)` Unwraps a given string from a character.
`static java.lang.String` `unwrap​(java.lang.String str, java.lang.String wrapToken)` Unwraps a given string from anther string.
`static java.lang.String` `upperCase​(java.lang.String str)` Converts a String to upper case as per `String.toUpperCase()`.
`static java.lang.String` `upperCase​(java.lang.String str, java.util.Locale locale)` Converts a String to upper case as per `String.toUpperCase(Locale)`.
`static java.lang.String` `valueOf​(char[] value)` Returns the string representation of the `char` array or null.
`static java.lang.String` `wrap​(java.lang.String str, char wrapWith)` Wraps a string with a char.
`static java.lang.String` `wrap​(java.lang.String str, java.lang.String wrapWith)` Wraps a String with another String.
`static java.lang.String` `wrapIfMissing​(java.lang.String str, char wrapWith)` Wraps a string with a char if that char is missing from the start or end of the given string.
`static java.lang.String` `wrapIfMissing​(java.lang.String str, java.lang.String wrapWith)` Wraps a string with a string if that string is missing from the start or end of the given string.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### SPACE

    public static final java.lang.String SPACE

A String for a space character.

Since:
  3.2
See Also:
  Constant Field Values

#### EMPTY

    public static final java.lang.String EMPTY

The empty String `""`.

Since:
  2.0
See Also:
  Constant Field Values

#### LF

    public static final java.lang.String LF

A String for linefeed LF ("\n").

Since:
  3.2
See Also:
  JLF: Escape Sequences for Character and String Literals, Constant Field Values

#### CR

    public static final java.lang.String CR

A String for carriage return CR ("\r").

Since:
  3.2
See Also:
  JLF: Escape Sequences for Character and String Literals, Constant Field Values

#### INDEX_NOT_FOUND

    public static final int INDEX_NOT_FOUND

Represents a failed index search.

Since:
  2.1
See Also:
  Constant Field Values

### Constructor Detail

#### StringUtils

    public StringUtils()

`StringUtils` instances should NOT be constructed in standard programming. Instead, the class should be used as `StringUtils.trim(" foo ");`.

This constructor is public to permit tools that require a JavaBean instance to operate.

### Method Detail

#### abbreviate

    public static java.lang.String abbreviate​(java.lang.String str,
                                              int maxWidth)

Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "Now is the time for..."

Specifically:

- If 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) = 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` - if the width is too small
Since:
  2.0

#### abbreviate

    public static java.lang.String abbreviate​(java.lang.String str,
                                              int offset,
                                              int maxWidth)

Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "...is the time for..."

Works like `abbreviate(String, int)`, but allows you to specify a "left edge" offset. Note that this left edge is not necessarily going to be the leftmost character in the result, or the first character following the ellipses, but it will appear somewhere in the result.

In no case will it return a String of length greater than `maxWidth`.

     StringUtils.abbreviate(null, *, *)                = null
     StringUtils.abbreviate("", 0, 4)                  = ""
     StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..."
     StringUtils.abbreviate("abcdefghijklmno", 0, 10)  = "abcdefg..."
     StringUtils.abbreviate("abcdefghijklmno", 1, 10)  = "abcdefg..."
     StringUtils.abbreviate("abcdefghijklmno", 4, 10)  = "abcdefg..."
     StringUtils.abbreviate("abcdefghijklmno", 5, 10)  = "...fghi..."
     StringUtils.abbreviate("abcdefghijklmno", 6, 10)  = "...ghij..."
     StringUtils.abbreviate("abcdefghijklmno", 8, 10)  = "...ijklmno"
     StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno"
     StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno"
     StringUtils.abbreviate("abcdefghij", 0, 3)        = IllegalArgumentException
     StringUtils.abbreviate("abcdefghij", 5, 6)        = IllegalArgumentException

Parameters:
  `str` - the String to check, may be null
  `offset` - left edge of source String
  `maxWidth` - maximum length of result String, must be at least 4
Returns:
  abbreviated String, `null` if null String input
Throws:
  `java.lang.IllegalArgumentException` - if the width is too small
Since:
  2.0

#### abbreviate

    public static java.lang.String abbreviate​(java.lang.String str,
                                              java.lang.String abbrevMarker,
                                              int maxWidth)

Abbreviates a String using another given String as replacement marker. This will turn "Now is the time for all good men" into "Now is the time for..." if "..." was defined as 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)  = IllegalArgumentException
     StringUtils.abbreviate("abcdefg", "...", 3) = 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` - if the width is too small
Since:
  3.6

#### abbreviate

    public static java.lang.String abbreviate​(java.lang.String str,
                                              java.lang.String abbrevMarker,
                                              int offset,
                                              int maxWidth)

Abbreviates a String using a given replacement marker. This will turn "Now is the time for all good men" into "...is the time for..." if "..." was defined as 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", "*", 9, 10)    = "*ghijklmno"
     StringUtils.abbreviate("abcdefghijklmno", "'", 10, 10)   = "'ghijklmno"
     StringUtils.abbreviate("abcdefghijklmno", "!", 12, 10)   = "!ghijklmno"
     StringUtils.abbreviate("abcdefghij", "abra", 0, 4)       = IllegalArgumentException
     StringUtils.abbreviate("abcdefghij", "...", 5, 6)        = IllegalArgumentException

Parameters:
  `str` - the String to check, may be null
  `abbrevMarker` - the String used as replacement marker
  `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` - if the width is too small
Since:
  3.6

#### abbreviateMiddle

    public static java.lang.String abbreviateMiddle​(java.lang.String str,
                                                    java.lang.String middle,
                                                    int length)

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

#### appendIfMissing

    public static java.lang.String appendIfMissing​(java.lang.String str,
                                                   java.lang.CharSequence suffix,
                                                   java.lang.CharSequence... suffixes)

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

#### appendIfMissingIgnoreCase

    public static java.lang.String appendIfMissingIgnoreCase​(java.lang.String str,
                                                             java.lang.CharSequence suffix,
                                                             java.lang.CharSequence... suffixes)

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

#### capitalize

    public static java.lang.String capitalize​(java.lang.String str)

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 `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
Since:
  2.0
See Also:
  `WordUtils.capitalize(String)`, `uncapitalize(String)`

#### center

    public static java.lang.String center​(java.lang.String str,
                                          int size)

Centers a String in a larger String of size `size` using the space character (' ').

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

#### center

    public static java.lang.String center​(java.lang.String str,
                                          int size,
                                          char padChar)

Centers a String in a larger String of size `size`. Uses a supplied character as the value to pad the String with.

If the size is less than the String length, the String is returned. A `null` String returns `null`. A negative size is treated as zero.

     StringUtils.center(null, *, *)     = null
     StringUtils.center("", 4, ' ')     = "    "
     StringUtils.center("ab", -1, ' ')  = "ab"
     StringUtils.center("ab", 4, ' ')   = " ab "
     StringUtils.center("abcd", 2, ' ') = "abcd"
     StringUtils.center("a", 4, ' ')    = " a  "
     StringUtils.center("a", 4, 'y')    = "yayy"

Parameters:
  `str` - the String to center, may be null
  `size` - the int size of new String, negative treated as zero
  `padChar` - the character to pad the new String with
Returns:
  centered String, `null` if null String input
Since:
  2.0

#### center

    public static java.lang.String center​(java.lang.String str,
                                          int size,
                                          java.lang.String padStr)

Centers a String in a larger String of size `size`. Uses a supplied String as the value to pad the String with.

If the size is less than the String length, the String is returned. A `null` String returns `null`. A negative size is treated as zero.

     StringUtils.center(null, *, *)     = null
     StringUtils.center("", 4, " ")     = "    "
     StringUtils.center("ab", -1, " ")  = "ab"
     StringUtils.center("ab", 4, " ")   = " ab "
     StringUtils.center("abcd", 2, " ") = "abcd"
     StringUtils.center("a", 4, " ")    = " a  "
     StringUtils.center("a", 4, "yz")   = "yayz"
     StringUtils.center("abc", 7, null) = "  abc  "
     StringUtils.center("abc", 7, "")   = "  abc  "

Parameters:
  `str` - the String to center, may be null
  `size` - the int size of new String, negative treated as zero
  `padStr` - the String to pad the new String with, must not be null or empty
Returns:
  centered String, `null` if null String input
Throws:
  `java.lang.IllegalArgumentException` - if padStr is `null` or empty

#### chomp

    public static java.lang.String chomp​(java.lang.String str)

Removes one newline from end of a String if it's there, otherwise leave it alone. A newline is "`\n`", "`\r`", or "`\r\n`".

NOTE: This method changed in 2.0. It now more closely matches Perl chomp.

     StringUtils.chomp(null)          = null
     StringUtils.chomp("")            = ""
     StringUtils.chomp("abc \r")      = "abc "
     StringUtils.chomp("abc\n")       = "abc"
     StringUtils.chomp("abc\r\n")     = "abc"
     StringUtils.chomp("abc\r\n\r\n") = "abc\r\n"
     StringUtils.chomp("abc\n\r")     = "abc\n"
     StringUtils.chomp("abc\n\rabc")  = "abc\n\rabc"
     StringUtils.chomp("\r")          = ""
     StringUtils.chomp("\n")          = ""
     StringUtils.chomp("\r\n")        = ""

Parameters:
  `str` - the String to chomp a newline from, may be null
Returns:
  String without newline, `null` if null String input

#### chomp

    @Deprecated
    public static java.lang.String chomp​(java.lang.String str,
                                         java.lang.String separator)

Deprecated.
This feature will be removed in Lang 4.0, use `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

#### chop

    public static java.lang.String chop​(java.lang.String str)

Remove the last character from a String.

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

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

Parameters:
  `str` - the String to chop last character from, may be null
Returns:
  String without last character, `null` if null String input

#### compare

    public static int compare​(java.lang.String str1,
                              java.lang.String str2)

Compare 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`
Since:
  3.5
See Also:
  `compare(String, String, boolean)`, `String.compareTo(String)`

#### compare

    public static int compare​(java.lang.String str1,
                              java.lang.String str2,
                              boolean nullIsLess)

Compare 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`
Since:
  3.5
See Also:
  `String.compareTo(String)`

#### compareIgnoreCase

    public static int compareIgnoreCase​(java.lang.String str1,
                                        java.lang.String str2)

Compare 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.
Since:
  3.5
See Also:
  `compareIgnoreCase(String, String, boolean)`, `String.compareToIgnoreCase(String)`

#### compareIgnoreCase

    public static int compareIgnoreCase​(java.lang.String str1,
                                        java.lang.String str2,
                                        boolean nullIsLess)

Compare 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.
Since:
  3.5
See Also:
  `String.compareToIgnoreCase(String)`

#### contains

    public static boolean contains​(java.lang.CharSequence seq,
                                   java.lang.CharSequence searchSeq)

Checks 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:
  2.0, 3.0 Changed signature from contains(String, String) to contains(CharSequence, CharSequence)

#### contains

    public static boolean contains​(java.lang.CharSequence seq,
                                   int searchChar)

Checks 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:
  2.0, 3.0 Changed signature from contains(String, int) to contains(CharSequence, int)

#### containsAny

    public static boolean containsAny​(java.lang.CharSequence cs,
                                      char... searchChars)

Checks 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:
  2.4, 3.0 Changed signature from containsAny(String, char[]) to containsAny(CharSequence, char...)

#### containsAny

    public static boolean containsAny​(java.lang.CharSequence cs,
                                      java.lang.CharSequence searchChars)

Checks 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:
  2.4, 3.0 Changed signature from containsAny(String, String) to containsAny(CharSequence, CharSequence)

#### containsAny

    public static boolean containsAny​(java.lang.CharSequence cs,
                                      java.lang.CharSequence... searchCharSequences)

Checks 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

#### containsIgnoreCase

    public static boolean containsIgnoreCase​(java.lang.CharSequence str,
                                             java.lang.CharSequence searchStr)

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

#### containsNone

    public static boolean containsNone​(java.lang.CharSequence cs,
                                       char... searchChars)

Checks 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", 'xyz') = true
     StringUtils.containsNone("ab1", 'xyz')  = true
     StringUtils.containsNone("abz", 'xyz')  = 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:
  2.0, 3.0 Changed signature from containsNone(String, char[]) to containsNone(CharSequence, char...)

#### containsNone

    public static boolean containsNone​(java.lang.CharSequence cs,
                                       java.lang.String invalidChars)

Checks 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:
  2.0, 3.0 Changed signature from containsNone(String, String) to containsNone(CharSequence, String)

#### containsOnly

    public static boolean containsOnly​(java.lang.CharSequence cs,
                                       char... valid)

Checks 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", 'abc') = true
     StringUtils.containsOnly("ab1", 'abc')  = false
     StringUtils.containsOnly("abz", 'abc')  = 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...)

#### containsOnly

    public static boolean containsOnly​(java.lang.CharSequence cs,
                                       java.lang.String validChars)

Checks 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:
  2.0, 3.0 Changed signature from containsOnly(String, String) to containsOnly(CharSequence, String)

#### containsWhitespace

    public static boolean containsWhitespace​(java.lang.CharSequence seq)

Check whether the given CharSequence contains any whitespace characters.

Whitespace is defined by `Character.isWhitespace(char)`.

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

#### countMatches

    public static int countMatches​(java.lang.CharSequence str,
                                   char ch)

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

#### countMatches

    public static int countMatches​(java.lang.CharSequence str,
                                   java.lang.CharSequence sub)

Counts how many times the substring appears in the larger string.

A `null` or empty ("") String input returns `0`.

     StringUtils.countMatches(null, *)       = 0
     StringUtils.countMatches("", *)         = 0
     StringUtils.countMatches("abba", null)  = 0
     StringUtils.countMatches("abba", "")    = 0
     StringUtils.countMatches("abba", "a")   = 2
     StringUtils.countMatches("abba", "ab")  = 1
     StringUtils.countMatches("abba", "xxx") = 0

Parameters:
  `str` - the 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)

#### defaultIfBlank

    public static <T extends java.lang.CharSequence> T defaultIfBlank​(T str,
                                                                      T defaultStr)

Returns either the passed in CharSequence, or if the CharSequence is whitespace, 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 the input is whitespace, empty ("") or `null`, may be null
Returns:
  the passed in CharSequence, or the default
See Also:
  `defaultString(String, String)`

#### defaultIfEmpty

    public static <T extends java.lang.CharSequence> T defaultIfEmpty​(T str,
                                                                      T defaultStr)

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
See Also:
  `defaultString(String, String)`

#### defaultString

    public static java.lang.String defaultString​(java.lang.String str)

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

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

Parameters:
  `str` - the String to check, may be null
Returns:
  the passed in String, or the empty String if it was `null`
See Also:
  `ObjectUtils.toString(Object)`, `String.valueOf(Object)`

#### defaultString

    public static java.lang.String defaultString​(java.lang.String str,
                                                 java.lang.String defaultStr)

Returns either the passed in String, or if the String is `null`, the value of `defaultStr`.

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

Parameters:
  `str` - the String to check, may be null
  `defaultStr` - the default String to return if the input is `null`, may be null
Returns:
  the passed in String, or the default if it was `null`
See Also:
  `ObjectUtils.toString(Object,String)`, `String.valueOf(Object)`

#### deleteWhitespace

    public static java.lang.String deleteWhitespace​(java.lang.String str)

Deletes all whitespaces from a String as defined by `Character.isWhitespace(char)`.

     StringUtils.deleteWhitespace(null)         = null
     StringUtils.deleteWhitespace("")           = ""
     StringUtils.deleteWhitespace("abc")        = "abc"
     StringUtils.deleteWhitespace("   ab  c  ") = "abc"

Parameters:
  `str` - the String to delete whitespace from, may be null
Returns:
  the String without whitespaces, `null` if null String input

#### difference

    public static java.lang.String difference​(java.lang.String str1,
                                              java.lang.String str2)

Compares two Strings, and returns the portion where they differ. More precisely, return the remainder of the second String, starting from where it's different from the first. 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
See Also:
  `indexOfDifference(CharSequence,CharSequence)`

#### endsWith

    public static boolean endsWith​(java.lang.CharSequence str,
                                   java.lang.CharSequence suffix)

Check if a CharSequence ends with a specified suffix.

`null`s 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`
Since:
  2.4, 3.0 Changed signature from endsWith(String, String) to endsWith(CharSequence, CharSequence)
See Also:
  `String.endsWith(String)`

#### endsWithAny

    public static boolean endsWithAny​(java.lang.CharSequence sequence,
                                      java.lang.CharSequence... searchStrings)

Check 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
See Also:
  `endsWith(CharSequence, CharSequence)`

#### endsWithIgnoreCase

    public static boolean endsWithIgnoreCase​(java.lang.CharSequence str,
                                             java.lang.CharSequence suffix)

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

`null`s 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`
Since:
  2.4, 3.0 Changed signature from endsWithIgnoreCase(String, String) to endsWithIgnoreCase(CharSequence, CharSequence)
See Also:
  `String.endsWith(String)`

#### equals

    public static boolean equals​(java.lang.CharSequence cs1,
                                 java.lang.CharSequence cs2)

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

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

     StringUtils.equals(null, null)   = true
     StringUtils.equals(null, "abc")  = false
     StringUtils.equals("abc", null)  = false
     StringUtils.equals("abc", "abc") = true
     StringUtils.equals("abc", "ABC") = false

Parameters:
  `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)`

#### equalsAny

    public static boolean equalsAny​(java.lang.CharSequence string,
                                    java.lang.CharSequence... searchStrings)

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

#### equalsAnyIgnoreCase

    public static boolean equalsAnyIgnoreCase​(java.lang.CharSequence string,
                                              java.lang.CharSequence... searchStrings)

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

#### equalsIgnoreCase

    public static boolean equalsIgnoreCase​(java.lang.CharSequence cs1,
                                           java.lang.CharSequence cs2)

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

`null`s 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)`

#### firstNonBlank

    @SafeVarargs
    public static <T extends java.lang.CharSequence> T firstNonBlank​(T... values)

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

#### firstNonEmpty

    @SafeVarargs
    public static <T extends java.lang.CharSequence> T firstNonEmpty​(T... values)

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

#### getBytes

    public static byte[] getBytes​(java.lang.String string,
                                  java.nio.charset.Charset charset)

Calls `String.getBytes(Charset)` in a null-safe manner.

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.
Since:
  3.10
See Also:
  `String.getBytes(Charset)`

#### getBytes

    public static byte[] getBytes​(java.lang.String string,
                                  java.lang.String charset)
                           throws java.io.UnsupportedEncodingException

Calls `String.getBytes(String)` in a null-safe manner.

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.
Since:
  3.10
See Also:
  `String.getBytes(String)`

#### getCommonPrefix

    public static java.lang.String getCommonPrefix​(java.lang.String... strs)

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

For example, `getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) -&gt; "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

#### getDigits

    public static java.lang.String getDigits​(java.lang.String str)

Checks if a String `str` contains Unicode digits, if yes then concatenate all the digits in `str` and return it as a String.

An empty ("") String will be returned if no digits 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 found, or `null` String if `str` is null
Since:
  3.6

#### getFuzzyDistance

    @Deprecated
    public static int getFuzzyDistance​(java.lang.CharSequence term,
                                       java.lang.CharSequence query,
                                       java.util.Locale locale)

Deprecated.
as of 3.6, use commons-text FuzzyScore instead

Find 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)                                    = 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` - if either String input `null` or Locale input `null`
Since:
  3.4

#### getIfBlank

    public static <T extends java.lang.CharSequence> T getIfBlank​(T str,
                                                                  java.util.function.Supplier<T> defaultSupplier)

Returns either the passed in CharSequence, or if the CharSequence is whitespace, empty ("") or `null`, the value supplied by `defaultStrSupplier`.

Whitespace is defined by `Character.isWhitespace(char)`.

Caller responsible for thread-safety and exception handling of 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 whitespace, empty ("") or `null`, may be null
Returns:
  the passed in CharSequence, or the default
Since:
  3.10
See Also:
  `defaultString(String, String)`

#### getIfEmpty

    public static <T extends java.lang.CharSequence> T getIfEmpty​(T str,
                                                                  java.util.function.Supplier<T> defaultSupplier)

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

Caller responsible for thread-safety and exception handling of 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
See Also:
  `defaultString(String, String)`

#### getJaroWinklerDistance

    @Deprecated
    public static double getJaroWinklerDistance​(java.lang.CharSequence first,
                                                java.lang.CharSequence second)

Deprecated.
as of 3.6, use commons-text JaroWinklerDistance instead

Find 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 http://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance.

     StringUtils.getJaroWinklerDistance(null, null)          = 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` - if either String input `null`
Since:
  3.3

#### getLevenshteinDistance

    @Deprecated
    public static int getLevenshteinDistance​(java.lang.CharSequence s,
                                             java.lang.CharSequence t)

Deprecated.
as of 3.6, use commons-text LevenshteinDistance instead

Find the Levenshtein distance between two Strings.

This is the number of changes needed to change one String into another, where each change is a single character modification (deletion, insertion or substitution).

The implementation uses a single-dimensional array of length s.length() + 1. See http://blog.softwx.net/2014/12/optimizing-levenshtein-algorithm-in-c.html for details.

     StringUtils.getLevenshteinDistance(null, *)             = IllegalArgumentException
     StringUtils.getLevenshteinDistance(*, null)             = IllegalArgumentException
     StringUtils.getLevenshteinDistance("", "")              = 0
     StringUtils.getLevenshteinDistance("", "a")             = 1
     StringUtils.getLevenshteinDistance("aaapppp", "")       = 7
     StringUtils.getLevenshteinDistance("frog", "fog")       = 1
     StringUtils.getLevenshteinDistance("fly", "ant")        = 3
     StringUtils.getLevenshteinDistance("elephant", "hippo") = 7
     StringUtils.getLevenshteinDistance("hippo", "elephant") = 7
     StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8
     StringUtils.getLevenshteinDistance("hello", "hallo")    = 1

Parameters:
  `s` - the first String, must not be null
  `t` - the second String, must not be null
Returns:
  result distance
Throws:
  `java.lang.IllegalArgumentException` - if either String input `null`
Since:
  3.0 Changed signature from getLevenshteinDistance(String, String) to getLevenshteinDistance(CharSequence, CharSequence)

#### getLevenshteinDistance

    @Deprecated
    public static int getLevenshteinDistance​(java.lang.CharSequence s,
                                             java.lang.CharSequence t,
                                             int threshold)

Deprecated.
as of 3.6, use commons-text LevenshteinDistance instead

Find 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 from http://www.merriampark.com/ld.htm

     StringUtils.getLevenshteinDistance(null, *, *)             = IllegalArgumentException
     StringUtils.getLevenshteinDistance(*, null, *)             = IllegalArgumentException
     StringUtils.getLevenshteinDistance(*, *, -1)               = 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` - if either String input `null` or negative threshold

#### indexOf

    public static int indexOf​(java.lang.CharSequence seq,
                              java.lang.CharSequence searchSeq)

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:
  2.0, 3.0 Changed signature from indexOf(String, String) to indexOf(CharSequence, CharSequence)

#### indexOf

    public static int indexOf​(java.lang.CharSequence seq,
                              java.lang.CharSequence searchSeq,
                              int startPos)

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:
  2.0, 3.0 Changed signature from indexOf(String, String, int) to indexOf(CharSequence, CharSequence, int)

#### indexOf

    public static int indexOf​(java.lang.CharSequence seq,
                              int searchChar)

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

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:
  2.0, 3.0 Changed signature from indexOf(String, int) to indexOf(CharSequence, int), 3.6 Updated `CharSequenceUtils` call to behave more like `String`

#### indexOf

    public static int indexOf​(java.lang.CharSequence seq,
                              int searchChar,
                              int startPos)

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:
  2.0, 3.0 Changed signature from indexOf(String, int, int) to indexOf(CharSequence, int, int), 3.6 Updated `CharSequenceUtils` call to behave more like `String`

#### indexOfAny

    public static int indexOfAny​(java.lang.CharSequence cs,
                                 char... searchChars)

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:
  2.0, 3.0 Changed signature from indexOfAny(String, char[]) to indexOfAny(CharSequence, char...)

#### indexOfAny

    public static int indexOfAny​(java.lang.CharSequence str,
                                 java.lang.CharSequence... searchStrs)

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

#### indexOfAny

    public static int indexOfAny​(java.lang.CharSequence cs,
                                 java.lang.String searchChars)

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:
  2.0, 3.0 Changed signature from indexOfAny(String, String) to indexOfAny(CharSequence, String)

#### indexOfAnyBut

    public static int indexOfAnyBut​(java.lang.CharSequence cs,
                                    char... searchChars)

Searches a CharSequence to find the first index of any character not in the given set of characters.

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:
  2.0, 3.0 Changed signature from indexOfAnyBut(String, char[]) to indexOfAnyBut(CharSequence, char...)

#### indexOfAnyBut

    public static int indexOfAnyBut​(java.lang.CharSequence seq,
                                    java.lang.CharSequence searchChars)

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

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:
  2.0, 3.0 Changed signature from indexOfAnyBut(String, String) to indexOfAnyBut(CharSequence, CharSequence)

#### indexOfDifference

    public static int indexOfDifference​(java.lang.CharSequence... css)

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:
  2.4, 3.0 Changed signature from indexOfDifference(String...) to indexOfDifference(CharSequence...)

#### indexOfDifference

    public static int indexOfDifference​(java.lang.CharSequence cs1,
                                        java.lang.CharSequence cs2)

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:
  2.0, 3.0 Changed signature from indexOfDifference(String, String) to indexOfDifference(CharSequence, CharSequence)

#### indexOfIgnoreCase

    public static int indexOfIgnoreCase​(java.lang.CharSequence str,
                                        java.lang.CharSequence searchStr)

Case in-sensitive find of the first index within a CharSequence.

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.indexOfIgnoreCase(null, *)          = -1
     StringUtils.indexOfIgnoreCase(*, null)          = -1
     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:
  2.5, 3.0 Changed signature from indexOfIgnoreCase(String, String) to indexOfIgnoreCase(CharSequence, CharSequence)

#### indexOfIgnoreCase

    public static int indexOfIgnoreCase​(java.lang.CharSequence str,
                                        java.lang.CharSequence searchStr,
                                        int startPos)

Case in-sensitive find of the first index within a CharSequence from the specified position.

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.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:
  2.5, 3.0 Changed signature from indexOfIgnoreCase(String, String, int) to indexOfIgnoreCase(CharSequence, CharSequence, int)

#### isAllBlank

    public static boolean isAllBlank​(java.lang.CharSequence... css)

Checks 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

#### isAllEmpty

    public static boolean isAllEmpty​(java.lang.CharSequence... css)

Checks 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

#### isAllLowerCase

    public static boolean isAllLowerCase​(java.lang.CharSequence cs)

Checks 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:
  2.5, 3.0 Changed signature from isAllLowerCase(String) to isAllLowerCase(CharSequence)

#### isAllUpperCase

    public static boolean isAllUpperCase​(java.lang.CharSequence cs)

Checks 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:
  2.5, 3.0 Changed signature from isAllUpperCase(String) to isAllUpperCase(CharSequence)

#### isAlpha

    public static boolean isAlpha​(java.lang.CharSequence cs)

Checks 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 signature from isAlpha(String) to isAlpha(CharSequence), 3.0 Changed "" to return false and not true

#### isAlphanumeric

    public static boolean isAlphanumeric​(java.lang.CharSequence cs)

Checks 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 signature from isAlphanumeric(String) to isAlphanumeric(CharSequence), 3.0 Changed "" to return false and not true

#### isAlphanumericSpace

    public static boolean isAlphanumericSpace​(java.lang.CharSequence cs)

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

#### isAlphaSpace

    public static boolean isAlphaSpace​(java.lang.CharSequence cs)

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

#### isAnyBlank

    public static boolean isAnyBlank​(java.lang.CharSequence... css)

Checks if any of the CharSequences are empty ("") or null or whitespace only.

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 empty or null or whitespace only
Since:
  3.2

#### isAnyEmpty

    public static boolean isAnyEmpty​(java.lang.CharSequence... css)

Checks 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

#### isAsciiPrintable

    public static boolean isAsciiPrintable​(java.lang.CharSequence cs)

Checks 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 thru 126
Since:
  2.1, 3.0 Changed signature from isAsciiPrintable(String) to isAsciiPrintable(CharSequence)

#### isBlank

    public static boolean isBlank​(java.lang.CharSequence cs)

Checks if a CharSequence is empty (""), null or whitespace only.

Whitespace is 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:
  2.0, 3.0 Changed signature from isBlank(String) to isBlank(CharSequence)

#### isEmpty

    public static boolean isEmpty​(java.lang.CharSequence cs)

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

#### isMixedCase

    public static boolean isMixedCase​(java.lang.CharSequence cs)

Checks 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("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

#### isNoneBlank

    public static boolean isNoneBlank​(java.lang.CharSequence... css)

Checks 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

#### isNoneEmpty

    public static boolean isNoneEmpty​(java.lang.CharSequence... css)

Checks 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

#### isNotBlank

    public static boolean isNotBlank​(java.lang.CharSequence cs)

Checks if a CharSequence is not empty (""), not null and not whitespace only.

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 empty and not null and not whitespace only
Since:
  2.0, 3.0 Changed signature from isNotBlank(String) to isNotBlank(CharSequence)

#### isNotEmpty

    public static boolean isNotEmpty​(java.lang.CharSequence cs)

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

#### isNumeric

    public static boolean isNumeric​(java.lang.CharSequence cs)

Checks 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 signature from isNumeric(String) to isNumeric(CharSequence), 3.0 Changed "" to return false and not true

#### isNumericSpace

    public static boolean isNumericSpace​(java.lang.CharSequence cs)

Checks 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.isNumeric("१२३")  = true
     StringUtils.isNumeric("१२ ३")  = 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)

#### isWhitespace

    public static boolean isWhitespace​(java.lang.CharSequence cs)

Checks 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:
  2.0, 3.0 Changed signature from isWhitespace(String) to isWhitespace(CharSequence)

#### join

    public static java.lang.String join​(byte[] array,
                                        char separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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

#### join

    public static java.lang.String join​(byte[] array,
                                        char separator,
                                        int startIndex,
                                        int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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
  `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

#### join

    public static java.lang.String join​(char[] array,
                                        char separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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

#### join

    public static java.lang.String join​(char[] array,
                                        char separator,
                                        int startIndex,
                                        int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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
  `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

#### join

    public static java.lang.String join​(double[] array,
                                        char separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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

#### join

    public static java.lang.String join​(double[] array,
                                        char separator,
                                        int startIndex,
                                        int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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
  `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

#### join

    public static java.lang.String join​(float[] array,
                                        char separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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

#### join

    public static java.lang.String join​(float[] array,
                                        char separator,
                                        int startIndex,
                                        int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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
  `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

#### join

    public static java.lang.String join​(int[] array,
                                        char separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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

#### join

    public static java.lang.String join​(int[] array,
                                        char separator,
                                        int startIndex,
                                        int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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
  `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

#### join

    public static java.lang.String join​(java.lang.Iterable<?> iterable,
                                        char separator)

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

#### join

    public static java.lang.String join​(java.lang.Iterable<?> iterable,
                                        java.lang.String separator)

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

#### join

    public static java.lang.String join​(java.util.Iterator<?> iterator,
                                        char separator)

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

No delimiter is added before or after the list. Null objects or empty strings within the iteration are represented by empty strings.

See the examples here: `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

#### join

    public static java.lang.String join​(java.util.Iterator<?> iterator,
                                        java.lang.String separator)

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

No delimiter is added before or after the list. A `null` separator is the same as an empty String ("").

See the examples here: `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

#### join

    public static java.lang.String join​(java.util.List<?> list,
                                        char separator,
                                        int startIndex,
                                        int endIndex)

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

#### join

    public static java.lang.String join​(java.util.List<?> list,
                                        java.lang.String separator,
                                        int startIndex,
                                        int endIndex)

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

#### join

    public static java.lang.String join​(long[] array,
                                        char separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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

#### join

    public static java.lang.String join​(long[] array,
                                        char separator,
                                        int startIndex,
                                        int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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
  `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

#### join

    public static java.lang.String join​(java.lang.Object[] array,
                                        char separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
     StringUtils.join(["a", "b", "c"], null) = "abc"
     StringUtils.join([null, "", "a"], ';')  = ";;a"

Parameters:
  `array` - the array of values to join together, may be null
  `separator` - the separator character to use
Returns:
  the joined String, `null` if null array input
Since:
  2.0

#### join

    public static java.lang.String join​(java.lang.Object[] array,
                                        char separator,
                                        int startIndex,
                                        int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
     StringUtils.join(["a", "b", "c"], null) = "abc"
     StringUtils.join([null, "", "a"], ';')  = ";;a"

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

#### join

    public static java.lang.String join​(java.lang.Object[] array,
                                        java.lang.String separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. A `null` separator is the same as an empty String (""). Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)                = null
     StringUtils.join([], *)                  = ""
     StringUtils.join([null], *)              = ""
     StringUtils.join(["a", "b", "c"], "--")  = "a--b--c"
     StringUtils.join(["a", "b", "c"], null)  = "abc"
     StringUtils.join(["a", "b", "c"], "")    = "abc"
     StringUtils.join([null, "", "a"], ',')   = ",,a"

Parameters:
  `array` - the array of values to join together, may be null
  `separator` - the separator character to use, null treated as ""
Returns:
  the joined String, `null` if null array input

#### join

    public static java.lang.String join​(java.lang.Object[] array,
                                        java.lang.String separator,
                                        int startIndex,
                                        int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. A `null` separator is the same as an empty String (""). Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *, *, *)                = null
     StringUtils.join([], *, *, *)                  = ""
     StringUtils.join([null], *, *, *)              = ""
     StringUtils.join(["a", "b", "c"], "--", 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
  `separator` - 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` - ife
  `startIndex < 0` or
  `startIndex >= array.length()` or
  `endIndex < 0` or
  `endIndex > array.length()`

#### join

    public static java.lang.String join​(short[] array,
                                        char separator)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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

#### join

    public static java.lang.String join​(short[] array,
                                        char separator,
                                        int startIndex,
                                        int endIndex)

Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

     StringUtils.join(null, *)               = null
     StringUtils.join([], *)                 = ""
     StringUtils.join([null], *)             = ""
     StringUtils.join([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
  `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

#### join

    @SafeVarargs
    public static <T> java.lang.String join​(T... elements)

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:
  2.0, 3.0 Changed signature to use varargs

#### joinWith

    public static java.lang.String joinWith​(java.lang.String separator,
                                            java.lang.Object... objects)

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:
  `separator` - the separator character to use, null treated as ""
  `objects` - the varargs providing the values to join together. `null` elements are treated as ""
Returns:
  the joined String.
Throws:
  `java.lang.IllegalArgumentException` - if a null varargs is provided
Since:
  3.5

#### lastIndexOf

    public static int lastIndexOf​(java.lang.CharSequence seq,
                                  java.lang.CharSequence searchSeq)

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:
  2.0, 3.0 Changed signature from lastIndexOf(String, String) to lastIndexOf(CharSequence, CharSequence)

#### lastIndexOf

    public static int lastIndexOf​(java.lang.CharSequence seq,
                                  java.lang.CharSequence searchSeq,
                                  int startPos)

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:
  2.0, 3.0 Changed signature from lastIndexOf(String, String, int) to lastIndexOf(CharSequence, CharSequence, int)

#### lastIndexOf

    public static int lastIndexOf​(java.lang.CharSequence seq,
                                  int searchChar)

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:
  2.0, 3.0 Changed signature from lastIndexOf(String, int) to lastIndexOf(CharSequence, int), 3.6 Updated `CharSequenceUtils` call to behave more like `String`

#### lastIndexOf

    public static int lastIndexOf​(java.lang.CharSequence seq,
                                  int searchChar,
                                  int startPos)

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:
  2.0, 3.0 Changed signature from lastIndexOf(String, int, int) to lastIndexOf(CharSequence, int, int)

#### lastIndexOfAny

    public static int lastIndexOfAny​(java.lang.CharSequence str,
                                     java.lang.CharSequence... searchStrs)

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

#### lastIndexOfIgnoreCase

    public static int lastIndexOfIgnoreCase​(java.lang.CharSequence str,
                                            java.lang.CharSequence searchStr)

Case in-sensitive find of the last index within a CharSequence.

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.

     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:
  2.5, 3.0 Changed signature from lastIndexOfIgnoreCase(String, String) to lastIndexOfIgnoreCase(CharSequence, CharSequence)

#### lastIndexOfIgnoreCase

    public static int lastIndexOfIgnoreCase​(java.lang.CharSequence str,
                                            java.lang.CharSequence searchStr,
                                            int startPos)

Case in-sensitive find of the last index within a CharSequence from the specified position.

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.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:
  2.5, 3.0 Changed signature from lastIndexOfIgnoreCase(String, String, int) to lastIndexOfIgnoreCase(CharSequence, CharSequence, int)

#### lastOrdinalIndexOf

    public static int lastOrdinalIndexOf​(java.lang.CharSequence str,
                                         java.lang.CharSequence searchStr,
                                         int ordinal)

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:
  2.5, 3.0 Changed signature from lastOrdinalIndexOf(String, String, int) to lastOrdinalIndexOf(CharSequence, CharSequence, int)

#### left

    public static java.lang.String left​(java.lang.String str,
                                        int len)

Gets the leftmost `len` characters of a String.

If `len` characters are not available, or the String is `null`, the String will be returned without an exception. An 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

#### leftPad

    public static java.lang.String leftPad​(java.lang.String str,
                                           int size)

Left pad a String with spaces (' ').

The String is padded to the size of `size`.

     StringUtils.leftPad(null, *)   = null
     StringUtils.leftPad("", 3)     = "   "
     StringUtils.leftPad("bat", 3)  = "bat"
     StringUtils.leftPad("bat", 5)  = "  bat"
     StringUtils.leftPad("bat", 1)  = "bat"
     StringUtils.leftPad("bat", -1) = "bat"

Parameters:
  `str` - the String to pad out, may be null
  `size` - the size to pad to
Returns:
  left padded String or original String if no padding is necessary, `null` if null String input

#### leftPad

    public static java.lang.String leftPad​(java.lang.String str,
                                           int size,
                                           char padChar)

Left pad a String with a specified character.

Pad to a size of `size`.

     StringUtils.leftPad(null, *, *)     = null
     StringUtils.leftPad("", 3, 'z')     = "zzz"
     StringUtils.leftPad("bat", 3, 'z')  = "bat"
     StringUtils.leftPad("bat", 5, 'z')  = "zzbat"
     StringUtils.leftPad("bat", 1, 'z')  = "bat"
     StringUtils.leftPad("bat", -1, 'z') = "bat"

Parameters:
  `str` - the String to pad out, may be null
  `size` - the size to pad to
  `padChar` - the character to pad with
Returns:
  left padded String or original String if no padding is necessary, `null` if null String input
Since:
  2.0

#### leftPad

    public static java.lang.String leftPad​(java.lang.String str,
                                           int size,
                                           java.lang.String padStr)

Left pad a String with a specified String.

Pad to a size of `size`.

     StringUtils.leftPad(null, *, *)      = null
     StringUtils.leftPad("", 3, "z")      = "zzz"
     StringUtils.leftPad("bat", 3, "yz")  = "bat"
     StringUtils.leftPad("bat", 5, "yz")  = "yzbat"
     StringUtils.leftPad("bat", 8, "yz")  = "yzyzybat"
     StringUtils.leftPad("bat", 1, "yz")  = "bat"
     StringUtils.leftPad("bat", -1, "yz") = "bat"
     StringUtils.leftPad("bat", 5, null)  = "  bat"
     StringUtils.leftPad("bat", 5, "")    = "  bat"

Parameters:
  `str` - the String to pad out, may be null
  `size` - the size to pad to
  `padStr` - the String to pad with, null or empty treated as single space
Returns:
  left padded String or original String if no padding is necessary, `null` if null String input

#### length

    public static int length​(java.lang.CharSequence cs)

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:
  2.4, 3.0 Changed signature from length(String) to length(CharSequence)

#### lowerCase

    public static java.lang.String lowerCase​(java.lang.String str)

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

A `null` input String returns `null`.

     StringUtils.lowerCase(null)  = null
     StringUtils.lowerCase("")    = ""
     StringUtils.lowerCase("aBc") = "abc"

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

#### lowerCase

    public static java.lang.String lowerCase​(java.lang.String str,
                                             java.util.Locale locale)

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

#### mid

    public static java.lang.String mid​(java.lang.String str,
                                       int pos,
                                       int len)

Gets `len` characters from the middle of a String.

If `len` characters are not available, the remainder of the String will be returned without an exception. If the String is `null`, `null` will be returned. An 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

#### normalizeSpace

    public static java.lang.String normalizeSpace​(java.lang.String str)

Similar to http://www.w3.org/TR/xpath/#function-normalize -space

The 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 functional 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
Since:
  3.0
See Also:
  `Pattern`, `trim(String)`, http://www.w3.org/TR/xpath/#function-normalize-space

#### ordinalIndexOf

    public static int ordinalIndexOf​(java.lang.CharSequence str,
                                     java.lang.CharSequence searchStr,
                                     int ordinal)

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:
  2.1, 3.0 Changed signature from ordinalIndexOf(String, String, int) to ordinalIndexOf(CharSequence, CharSequence, int)

#### overlay

    public static java.lang.String overlay​(java.lang.String str,
                                           java.lang.String overlay,
                                           int start,
                                           int end)

Overlays part of a String with another String.

A `null` string input returns `null`. A negative index is treated as zero. An index greater than the string length is treated as the string length. The start index is always the smaller of the two indices.

     StringUtils.overlay(null, *, *, *)            = null
     StringUtils.overlay("", "abc", 0, 0)          = "abc"
     StringUtils.overlay("abcdef", null, 2, 4)     = "abef"
     StringUtils.overlay("abcdef", "", 2, 4)       = "abef"
     StringUtils.overlay("abcdef", "", 4, 2)       = "abef"
     StringUtils.overlay("abcdef", "zzzz", 2, 4)   = "abzzzzef"
     StringUtils.overlay("abcdef", "zzzz", 4, 2)   = "abzzzzef"
     StringUtils.overlay("abcdef", "zzzz", -1, 4)  = "zzzzef"
     StringUtils.overlay("abcdef", "zzzz", 2, 8)   = "abzzzz"
     StringUtils.overlay("abcdef", "zzzz", -2, -3) = "zzzzabcdef"
     StringUtils.overlay("abcdef", "zzzz", 8, 10)  = "abcdefzzzz"

Parameters:
  `str` - the String to do overlaying in, may be null
  `overlay` - the String to overlay, may be null
  `start` - the position to start overlaying at
  `end` - the position to stop overlaying before
Returns:
  overlayed String, `null` if null String input
Since:
  2.0

#### prependIfMissing

    public static java.lang.String prependIfMissing​(java.lang.String str,
                                                    java.lang.CharSequence prefix,
                                                    java.lang.CharSequence... prefixes)

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

#### prependIfMissingIgnoreCase

    public static java.lang.String prependIfMissingIgnoreCase​(java.lang.String str,
                                                              java.lang.CharSequence prefix,
                                                              java.lang.CharSequence... prefixes)

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

#### remove

    public static java.lang.String remove​(java.lang.String str,
                                          char remove)

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

A `null` source string will return `null`. An empty ("") source string will return the empty string.

     StringUtils.remove(null, *)       = null
     StringUtils.remove("", *)         = ""
     StringUtils.remove("queued", 'u') = "qeed"
     StringUtils.remove("queued", 'z') = "queued"

Parameters:
  `str` - the source String to search, may be null
  `remove` - the char to search for and remove, may be null
Returns:
  the substring with the char removed if found, `null` if null String input
Since:
  2.1

#### remove

    public static java.lang.String remove​(java.lang.String str,
                                          java.lang.String remove)

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

A `null` source string will return `null`. An empty ("") source string will return the empty string. A `null` remove string will return the source string. An empty ("") remove string will return the source string.

     StringUtils.remove(null, *)        = null
     StringUtils.remove("", *)          = ""
     StringUtils.remove(*, null)        = *
     StringUtils.remove(*, "")          = *
     StringUtils.remove("queued", "ue") = "qd"
     StringUtils.remove("queued", "zz") = "queued"

Parameters:
  `str` - the source String to search, may be null
  `remove` - the String to search for and remove, may be null
Returns:
  the substring with the string removed if found, `null` if null String input
Since:
  2.1

#### removeAll

    @Deprecated
    public static java.lang.String removeAll​(java.lang.String text,
                                             java.lang.String regex)

Deprecated.
Moved to RegExUtils.

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` - if the regular expression's syntax is invalid
Since:
  3.5
See Also:
  `replaceAll(String, String, String)`, `removePattern(String, String)`, `String.replaceAll(String, String)`, `Pattern`, `Pattern.DOTALL`

#### removeEnd

    public static java.lang.String removeEnd​(java.lang.String str,
                                             java.lang.String remove)

Removes a substring only if it is at the end of a source string, otherwise returns the source string.

A `null` source string will return `null`. An empty ("") source string will return the empty string. A `null` search string will return the source string.

     StringUtils.removeEnd(null, *)      = null
     StringUtils.removeEnd("", *)        = ""
     StringUtils.removeEnd(*, null)      = *
     StringUtils.removeEnd("www.domain.com", ".com.")  = "www.domain.com"
     StringUtils.removeEnd("www.domain.com", ".com")   = "www.domain"
     StringUtils.removeEnd("www.domain.com", "domain") = "www.domain.com"
     StringUtils.removeEnd("abc", "")    = "abc"

Parameters:
  `str` - the source String to search, may be null
  `remove` - the String to search for and remove, may be null
Returns:
  the substring with the string removed if found, `null` if null String input
Since:
  2.1

#### removeEndIgnoreCase

    public static java.lang.String removeEndIgnoreCase​(java.lang.String str,
                                                       java.lang.String remove)

Case insensitive removal of a substring if it is at the end of a source string, otherwise returns the source string.

A `null` source string will return `null`. An empty ("") source string will return the empty string. A `null` search string will return the source string.

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

#### removeFirst

    @Deprecated
    public static java.lang.String removeFirst​(java.lang.String text,
                                               java.lang.String regex)

Deprecated.
Moved to RegExUtils.

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` - if the regular expression's syntax is invalid
Since:
  3.5
See Also:
  `replaceFirst(String, String, String)`, `String.replaceFirst(String, String)`, `Pattern`, `Pattern.DOTALL`

#### removeIgnoreCase

    public static java.lang.String removeIgnoreCase​(java.lang.String str,
                                                    java.lang.String remove)

Case insensitive removal of 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.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

#### removePattern

    @Deprecated
    public static java.lang.String removePattern​(java.lang.String source,
                                                 java.lang.String regex)

Deprecated.
Moved to RegExUtils.

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(&quot;(?s)&quot; + 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`
Since:
  3.2, 3.5 Changed `null` reference passed to this method is a no-op.
See Also:
  `replacePattern(String, String, String)`, `String.replaceAll(String, String)`, `Pattern.DOTALL`

#### removeStart

    public static java.lang.String removeStart​(java.lang.String str,
                                               java.lang.String remove)

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

#### removeStartIgnoreCase

    public static java.lang.String removeStartIgnoreCase​(java.lang.String str,
                                                         java.lang.String remove)

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

#### repeat

    public static java.lang.String repeat​(char ch,
                                          int repeat)

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 `char`s to be represented. If you are needing to support full I18N of your applications consider using `repeat(String, int)` instead.

Parameters:
  `ch` - character to repeat
  `repeat` - number of times to repeat char, negative treated as zero
Returns:
  String with repeated character
See Also:
  `repeat(String, int)`

#### repeat

    public static java.lang.String repeat​(java.lang.String str,
                                          int repeat)

Repeat a String `repeat` times to form a new String.

     StringUtils.repeat(null, 2) = null
     StringUtils.repeat("", 0)   = ""
     StringUtils.repeat("", 2)   = ""
     StringUtils.repeat("a", 3)  = "aaa"
     StringUtils.repeat("ab", 2) = "abab"
     StringUtils.repeat("a", -2) = ""

Parameters:
  `str` - the String to repeat, may be null
  `repeat` - number of times to repeat str, negative treated as zero
Returns:
  a new String consisting of the original String repeated, `null` if null String input

#### repeat

    public static java.lang.String repeat​(java.lang.String str,
                                          java.lang.String separator,
                                          int repeat)

Repeat 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)    = "xxx"
     StringUtils.repeat("?", ", ", 3)  = "?, ?, ?"

Parameters:
  `str` - the String to repeat, may be null
  `separator` - the String to inject, may be null
  `repeat` - number of times to repeat str, negative treated as zero
Returns:
  a new String consisting of the original String repeated, `null` if null String input
Since:
  2.5

#### replace

    public static java.lang.String replace​(java.lang.String text,
                                           java.lang.String searchString,
                                           java.lang.String replacement)

Replaces all occurrences of a String within another String.

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

     StringUtils.replace(null, *, *)        = null
     StringUtils.replace("", *, *)          = ""
     StringUtils.replace("any", null, *)    = "any"
     StringUtils.replace("any", *, null)    = "any"
     StringUtils.replace("any", "", *)      = "any"
     StringUtils.replace("aba", "a", null)  = "aba"
     StringUtils.replace("aba", "a", "")    = "b"
     StringUtils.replace("aba", "a", "z")   = "zbz"

Parameters:
  `text` - text to search and replace in, may be null
  `searchString` - the String to search for, may be null
  `replacement` - the String to replace it with, may be null
Returns:
  the text with any replacements processed, `null` if null String input
See Also:
  `replace(String text, String searchString, String replacement, int max)`

#### replace

    public static java.lang.String replace​(java.lang.String text,
                                           java.lang.String searchString,
                                           java.lang.String replacement,
                                           int max)

Replaces a String with another String inside a larger String, for the first `max` values of the search String.

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

     StringUtils.replace(null, *, *, *)         = null
     StringUtils.replace("", *, *, *)           = ""
     StringUtils.replace("any", null, *, *)     = "any"
     StringUtils.replace("any", *, null, *)     = "any"
     StringUtils.replace("any", "", *, *)       = "any"
     StringUtils.replace("any", *, *, 0)        = "any"
     StringUtils.replace("abaa", "a", null, -1) = "abaa"
     StringUtils.replace("abaa", "a", "", -1)   = "b"
     StringUtils.replace("abaa", "a", "z", 0)   = "abaa"
     StringUtils.replace("abaa", "a", "z", 1)   = "zbaa"
     StringUtils.replace("abaa", "a", "z", 2)   = "zbza"
     StringUtils.replace("abaa", "a", "z", -1)  = "zbzz"

Parameters:
  `text` - text to search and replace in, may be null
  `searchString` - the String to search for, may be null
  `replacement` - the String to replace it with, may be null
  `max` - maximum number of values to replace, or `-1` if no maximum
Returns:
  the text with any replacements processed, `null` if null String input

#### replaceAll

    @Deprecated
    public static java.lang.String replaceAll​(java.lang.String text,
                                              java.lang.String regex,
                                              java.lang.String replacement)

Deprecated.
Moved to RegExUtils.

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` - if the regular expression's syntax is invalid
Since:
  3.5
See Also:
  `replacePattern(String, String, String)`, `String.replaceAll(String, String)`, `Pattern`, `Pattern.DOTALL`

#### replaceChars

    public static java.lang.String replaceChars​(java.lang.String str,
                                                char searchChar,
                                                char replaceChar)

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

A `null` string input returns `null`. An empty ("") string input returns an empty string.

     StringUtils.replaceChars(null, *, *)        = null
     StringUtils.replaceChars("", *, *)          = ""
     StringUtils.replaceChars("abcba", 'b', 'y') = "aycya"
     StringUtils.replaceChars("abcba", 'z', 'y') = "abcba"

Parameters:
  `str` - String to replace characters in, may be null
  `searchChar` - the character to search for, may be null
  `replaceChar` - the character to replace, may be null
Returns:
  modified String, `null` if null string input
Since:
  2.0

#### replaceChars

    public static java.lang.String replaceChars​(java.lang.String str,
                                                java.lang.String searchChars,
                                                java.lang.String replaceChars)

Replaces multiple characters in a String in one go. This method can also be used to delete characters.

For example:
`replaceChars(&quot;hello&quot;, &quot;ho&quot;, &quot;jy&quot;) = jelly`.

A `null` string input returns `null`. An empty ("") string input returns an empty string. A null or empty set of search characters returns the input string.

The length of the search characters should normally equal the length of the replace characters. If the search characters is longer, then the extra search characters are deleted. If the search characters is shorter, then the extra replace characters are ignored.

     StringUtils.replaceChars(null, *, *)           = null
     StringUtils.replaceChars("", *, *)             = ""
     StringUtils.replaceChars("abc", null, *)       = "abc"
     StringUtils.replaceChars("abc", "", *)         = "abc"
     StringUtils.replaceChars("abc", "b", null)     = "ac"
     StringUtils.replaceChars("abc", "b", "")       = "ac"
     StringUtils.replaceChars("abcba", "bc", "yz")  = "ayzya"
     StringUtils.replaceChars("abcba", "bc", "y")   = "ayya"
     StringUtils.replaceChars("abcba", "bc", "yzx") = "ayzya"

Parameters:
  `str` - String to replace characters in, may be null
  `searchChars` - a set of characters to search for, may be null
  `replaceChars` - a set of characters to replace, may be null
Returns:
  modified String, `null` if null string input
Since:
  2.0

#### replaceEach

    public static java.lang.String replaceEach​(java.lang.String text,
                                               java.lang.String[] searchList,
                                               java.lang.String[] replacementList)

Replaces all occurrences of Strings within another String.

A `null` reference passed to this method is a no-op, or if any "search string" or "string to replace" is null, that replace will be ignored. This will not repeat. For repeating replaces, call the overloaded method.

      StringUtils.replaceEach(null, *, *)        = null
      StringUtils.replaceEach("", *, *)          = ""
      StringUtils.replaceEach("aba", null, null) = "aba"
      StringUtils.replaceEach("aba", new String[0], null) = "aba"
      StringUtils.replaceEach("aba", null, new String[0]) = "aba"
      StringUtils.replaceEach("aba", new String[]{"a"}, null)  = "aba"
      StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""})  = "b"
      StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"})  = "aba"
      StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"})  = "wcte"
      (example of how it does not repeat)
      StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"})  = "dcte"

Parameters:
  `text` - text to search and replace in, no-op if null
  `searchList` - the Strings to search for, no-op if null
  `replacementList` - the Strings to replace them with, no-op if null
Returns:
  the text with any replacements processed, `null` if null String input
Throws:
  `java.lang.IllegalArgumentException` - if the lengths of the arrays are not the same (null is ok, and/or size 0)
Since:
  2.4

#### replaceEachRepeatedly

    public static java.lang.String replaceEachRepeatedly​(java.lang.String text,
                                                         java.lang.String[] searchList,
                                                         java.lang.String[] replacementList)

Replaces all occurrences of Strings within another String.

A `null` reference passed to this method is a no-op, or if any "search string" or "string to replace" is null, that replace will be ignored.

      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"}) = 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` - if the search is repeating and there is an endless loop due to outputs of one being inputs to another
  `java.lang.IllegalArgumentException` - if the lengths of the arrays are not the same (null is ok, and/or size 0)
Since:
  2.4

#### replaceFirst

    @Deprecated
    public static java.lang.String replaceFirst​(java.lang.String text,
                                                java.lang.String regex,
                                                java.lang.String replacement)

Deprecated.
Moved to RegExUtils.

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` - if the regular expression's syntax is invalid
Since:
  3.5
See Also:
  `String.replaceFirst(String, String)`, `Pattern`, `Pattern.DOTALL`

#### replaceIgnoreCase

    public static java.lang.String replaceIgnoreCase​(java.lang.String text,
                                                     java.lang.String searchString,
                                                     java.lang.String replacement)

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
See Also:
  `replaceIgnoreCase(String text, String searchString, String replacement, int max)`

#### replaceIgnoreCase

    public static java.lang.String replaceIgnoreCase​(java.lang.String text,
                                                     java.lang.String searchString,
                                                     java.lang.String replacement,
                                                     int max)

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

#### replaceOnce

    public static java.lang.String replaceOnce​(java.lang.String text,
                                               java.lang.String searchString,
                                               java.lang.String replacement)

Replaces a String with another String inside a larger String, once.

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

     StringUtils.replaceOnce(null, *, *)        = null
     StringUtils.replaceOnce("", *, *)          = ""
     StringUtils.replaceOnce("any", null, *)    = "any"
     StringUtils.replaceOnce("any", *, null)    = "any"
     StringUtils.replaceOnce("any", "", *)      = "any"
     StringUtils.replaceOnce("aba", "a", null)  = "aba"
     StringUtils.replaceOnce("aba", "a", "")    = "ba"
     StringUtils.replaceOnce("aba", "a", "z")   = "zba"

Parameters:
  `text` - text to search and replace in, may be null
  `searchString` - the String to search for, may be null
  `replacement` - the String to replace with, may be null
Returns:
  the text with any replacements processed, `null` if null String input
See Also:
  `replace(String text, String searchString, String replacement, int max)`

#### replaceOnceIgnoreCase

    public static java.lang.String replaceOnceIgnoreCase​(java.lang.String text,
                                                         java.lang.String searchString,
                                                         java.lang.String replacement)

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
See Also:
  `replaceIgnoreCase(String text, String searchString, String replacement, int max)`

#### replacePattern

    @Deprecated
    public static java.lang.String replacePattern​(java.lang.String source,
                                                  java.lang.String regex,
                                                  java.lang.String replacement)

Deprecated.
Moved to RegExUtils.

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(&quot;(?s)&quot; + 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`
Since:
  3.2, 3.5 Changed `null` reference passed to this method is a no-op.
See Also:
  `replaceAll(String, String, String)`, `String.replaceAll(String, String)`, `Pattern.DOTALL`

#### reverse

    public static java.lang.String reverse​(java.lang.String str)

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

#### reverseDelimited

    public static java.lang.String reverseDelimited​(java.lang.String str,
                                                    char separatorChar)

Reverses a String that is delimited by a specific character.

The Strings between the delimiters are not reversed. Thus java.lang.String becomes String.lang.java (if the delimiter is `'.'`).

     StringUtils.reverseDelimited(null, *)      = null
     StringUtils.reverseDelimited("", *)        = ""
     StringUtils.reverseDelimited("a.b.c", 'x') = "a.b.c"
     StringUtils.reverseDelimited("a.b.c", ".") = "c.b.a"

Parameters:
  `str` - the String to reverse, may be null
  `separatorChar` - the separator character to use
Returns:
  the reversed String, `null` if null String input
Since:
  2.0

#### right

    public static java.lang.String right​(java.lang.String str,
                                         int len)

Gets the rightmost `len` characters of a String.

If `len` characters are not available, or the String is `null`, the String will be returned without an an exception. An 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

#### rightPad

    public static java.lang.String rightPad​(java.lang.String str,
                                            int size)

Right pad a String with spaces (' ').

The String is padded to the size of `size`.

     StringUtils.rightPad(null, *)   = null
     StringUtils.rightPad("", 3)     = "   "
     StringUtils.rightPad("bat", 3)  = "bat"
     StringUtils.rightPad("bat", 5)  = "bat  "
     StringUtils.rightPad("bat", 1)  = "bat"
     StringUtils.rightPad("bat", -1) = "bat"

Parameters:
  `str` - the String to pad out, may be null
  `size` - the size to pad to
Returns:
  right padded String or original String if no padding is necessary, `null` if null String input

#### rightPad

    public static java.lang.String rightPad​(java.lang.String str,
                                            int size,
                                            char padChar)

Right pad a String with a specified character.

The String is padded to the size of `size`.

     StringUtils.rightPad(null, *, *)     = null
     StringUtils.rightPad("", 3, 'z')     = "zzz"
     StringUtils.rightPad("bat", 3, 'z')  = "bat"
     StringUtils.rightPad("bat", 5, 'z')  = "batzz"
     StringUtils.rightPad("bat", 1, 'z')  = "bat"
     StringUtils.rightPad("bat", -1, 'z') = "bat"

Parameters:
  `str` - the String to pad out, may be null
  `size` - the size to pad to
  `padChar` - the character to pad with
Returns:
  right padded String or original String if no padding is necessary, `null` if null String input
Since:
  2.0

#### rightPad

    public static java.lang.String rightPad​(java.lang.String str,
                                            int size,
                                            java.lang.String padStr)

Right pad a String with a specified String.

The String is padded to the size of `size`.

     StringUtils.rightPad(null, *, *)      = null
     StringUtils.rightPad("", 3, "z")      = "zzz"
     StringUtils.rightPad("bat", 3, "yz")  = "bat"
     StringUtils.rightPad("bat", 5, "yz")  = "batyz"
     StringUtils.rightPad("bat", 8, "yz")  = "batyzyzy"
     StringUtils.rightPad("bat", 1, "yz")  = "bat"
     StringUtils.rightPad("bat", -1, "yz") = "bat"
     StringUtils.rightPad("bat", 5, null)  = "bat  "
     StringUtils.rightPad("bat", 5, "")    = "bat  "

Parameters:
  `str` - the String to pad out, may be null
  `size` - the size to pad to
  `padStr` - the String to pad with, null or empty treated as single space
Returns:
  right padded String or original String if no padding is necessary, `null` if null String input

#### rotate

    public static java.lang.String rotate​(java.lang.String str,
                                          int shift)

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

#### split

    public static java.lang.String[] split​(java.lang.String str)

Splits the provided text into an array, using whitespace as the separator. Whitespace is defined by `Character.isWhitespace(char)`.

The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.

A `null` input String returns `null`.

     StringUtils.split(null)       = null
     StringUtils.split("")         = []
     StringUtils.split("abc def")  = ["abc", "def"]
     StringUtils.split("abc  def") = ["abc", "def"]
     StringUtils.split(" abc ")    = ["abc"]

Parameters:
  `str` - the String to parse, may be null
Returns:
  an array of parsed Strings, `null` if null String input

#### split

    public static java.lang.String[] split​(java.lang.String str,
                                           char separatorChar)

Splits the provided text into an array, separator specified. This is an alternative to using StringTokenizer.

The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.

A `null` input String returns `null`.

     StringUtils.split(null, *)         = null
     StringUtils.split("", *)           = []
     StringUtils.split("a.b.c", '.')    = ["a", "b", "c"]
     StringUtils.split("a..b.c", '.')   = ["a", "b", "c"]
     StringUtils.split("a:b:c", '.')    = ["a:b:c"]
     StringUtils.split("a b c", ' ')    = ["a", "b", "c"]

Parameters:
  `str` - the String to parse, may be null
  `separatorChar` - the character used as the delimiter
Returns:
  an array of parsed Strings, `null` if null String input
Since:
  2.0

#### split

    public static java.lang.String[] split​(java.lang.String str,
                                           java.lang.String separatorChars)

Splits the provided text into an array, separators specified. This is an alternative to using StringTokenizer.

The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.

A `null` input String returns `null`. A `null` separatorChars splits on whitespace.

     StringUtils.split(null, *)         = null
     StringUtils.split("", *)           = []
     StringUtils.split("abc def", null) = ["abc", "def"]
     StringUtils.split("abc def", " ")  = ["abc", "def"]
     StringUtils.split("abc  def", " ") = ["abc", "def"]
     StringUtils.split("ab:cd:ef", ":") = ["ab", "cd", "ef"]

Parameters:
  `str` - the String to parse, may be null
  `separatorChars` - the characters used as the delimiters, `null` splits on whitespace
Returns:
  an array of parsed Strings, `null` if null String input

#### split

    public static java.lang.String[] split​(java.lang.String str,
                                           java.lang.String separatorChars,
                                           int max)

Splits the provided text into an array with a maximum length, separators specified.

The separator is not included in the returned String array. Adjacent separators are treated as one separator.

A `null` input String returns `null`. A `null` separatorChars splits on whitespace.

If more than `max` delimited substrings are found, the last returned string includes all characters after the first `max - 1` returned strings (including separator characters).

     StringUtils.split(null, *, *)            = null
     StringUtils.split("", *, *)              = []
     StringUtils.split("ab 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

#### splitByCharacterType

    public static java.lang.String[] splitByCharacterType​(java.lang.String str)

Splits a String by Character type as returned by `java.lang.Character.getType(char)`. Groups of contiguous characters of the same type are returned as complete tokens.

     StringUtils.splitByCharacterType(null)         = null
     StringUtils.splitByCharacterType("")           = []
     StringUtils.splitByCharacterType("ab de fg")   = ["ab", " ", "de", " ", "fg"]
     StringUtils.splitByCharacterType("ab   de fg") = ["ab", "   ", "de", " ", "fg"]
     StringUtils.splitByCharacterType("ab:cd:ef")   = ["ab", ":", "cd", ":", "ef"]
     StringUtils.splitByCharacterType("number5")    = ["number", "5"]
     StringUtils.splitByCharacterType("fooBar")     = ["foo", "B", "ar"]
     StringUtils.splitByCharacterType("foo200Bar")  = ["foo", "200", "B", "ar"]
     StringUtils.splitByCharacterType("ASFRules")   = ["ASFR", "ules"]

Parameters:
  `str` - the String to split, may be `null`
Returns:
  an array of parsed Strings, `null` if null String input
Since:
  2.4

#### splitByCharacterTypeCamelCase

    public static java.lang.String[] splitByCharacterTypeCamelCase​(java.lang.String str)

Splits a String by Character type as returned by `java.lang.Character.getType(char)`. Groups of contiguous characters of the same type are returned as complete tokens, with the following exception: the character of type `Character.UPPERCASE_LETTER`, if any, immediately preceding a token of type `Character.LOWERCASE_LETTER` will belong to the following token rather than to the preceding, if any, `Character.UPPERCASE_LETTER` token.

     StringUtils.splitByCharacterTypeCamelCase(null)         = null
     StringUtils.splitByCharacterTypeCamelCase("")           = []
     StringUtils.splitByCharacterTypeCamelCase("ab de fg")   = ["ab", " ", "de", " ", "fg"]
     StringUtils.splitByCharacterTypeCamelCase("ab   de fg") = ["ab", "   ", "de", " ", "fg"]
     StringUtils.splitByCharacterTypeCamelCase("ab:cd:ef")   = ["ab", ":", "cd", ":", "ef"]
     StringUtils.splitByCharacterTypeCamelCase("number5")    = ["number", "5"]
     StringUtils.splitByCharacterTypeCamelCase("fooBar")     = ["foo", "Bar"]
     StringUtils.splitByCharacterTypeCamelCase("foo200Bar")  = ["foo", "200", "Bar"]
     StringUtils.splitByCharacterTypeCamelCase("ASFRules")   = ["ASF", "Rules"]

Parameters:
  `str` - the String to split, may be `null`
Returns:
  an array of parsed Strings, `null` if null String input
Since:
  2.4

#### splitByWholeSeparator

    public static java.lang.String[] splitByWholeSeparator​(java.lang.String str,
                                                           java.lang.String separator)

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

The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator.

A `null` input String returns `null`. A `null` separator splits on whitespace.

     StringUtils.splitByWholeSeparator(null, *)               = null
     StringUtils.splitByWholeSeparator("", *)                 = []
     StringUtils.splitByWholeSeparator("ab de fg", null)      = ["ab", "de", "fg"]
     StringUtils.splitByWholeSeparator("ab   de fg", null)    = ["ab", "de", "fg"]
     StringUtils.splitByWholeSeparator("ab:cd:ef", ":")       = ["ab", "cd", "ef"]
     StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]

Parameters:
  `str` - the String to parse, may be null
  `separator` - String containing the String to be used as a delimiter, `null` splits on whitespace
Returns:
  an array of parsed Strings, `null` if null String was input

#### splitByWholeSeparator

    public static java.lang.String[] splitByWholeSeparator​(java.lang.String str,
                                                           java.lang.String separator,
                                                           int max)

Splits the provided text into an array, separator string specified. Returns a maximum of `max` substrings.

The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator.

A `null` input String returns `null`. A `null` separator splits on whitespace.

     StringUtils.splitByWholeSeparator(null, *, *)               = null
     StringUtils.splitByWholeSeparator("", *, *)                 = []
     StringUtils.splitByWholeSeparator("ab de fg", null, 0)      = ["ab", "de", "fg"]
     StringUtils.splitByWholeSeparator("ab   de fg", null, 0)    = ["ab", "de", "fg"]
     StringUtils.splitByWholeSeparator("ab:cd:ef", ":", 2)       = ["ab", "cd:ef"]
     StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
     StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]

Parameters:
  `str` - the String to parse, may be null
  `separator` - String containing the String to be used as a delimiter, `null` splits on whitespace
  `max` - the maximum number of elements to include in the returned array. A zero or negative value implies no limit.
Returns:
  an array of parsed Strings, `null` if null String was input

#### splitByWholeSeparatorPreserveAllTokens

    public static java.lang.String[] splitByWholeSeparatorPreserveAllTokens​(java.lang.String str,
                                                                            java.lang.String separator)

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

The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.

A `null` input String returns `null`. A `null` separator splits on whitespace.

     StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *)               = null
     StringUtils.splitByWholeSeparatorPreserveAllTokens("", *)                 = []
     StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null)      = ["ab", "de", "fg"]
     StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null)    = ["ab", "", "", "de", "fg"]
     StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":")       = ["ab", "cd", "ef"]
     StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]

Parameters:
  `str` - the String to parse, may be null
  `separator` - String containing the String to be used as a delimiter, `null` splits on whitespace
Returns:
  an array of parsed Strings, `null` if null String was input
Since:
  2.4

#### splitByWholeSeparatorPreserveAllTokens

    public static java.lang.String[] splitByWholeSeparatorPreserveAllTokens​(java.lang.String str,
                                                                            java.lang.String separator,
                                                                            int max)

Splits the provided text into an array, separator string specified. Returns a maximum of `max` substrings.

The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.

A `null` input String returns `null`. A `null` separator splits on whitespace.

     StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *, *)               = null
     StringUtils.splitByWholeSeparatorPreserveAllTokens("", *, *)                 = []
     StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null, 0)      = ["ab", "de", "fg"]
     StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null, 0)    = ["ab", "", "", "de", "fg"]
     StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":", 2)       = ["ab", "cd:ef"]
     StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
     StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]

Parameters:
  `str` - the String to parse, may be null
  `separator` - String containing the String to be used as a delimiter, `null` splits on whitespace
  `max` - the maximum number of elements to include in the returned array. A zero or negative value implies no limit.
Returns:
  an array of parsed Strings, `null` if null String was input
Since:
  2.4

#### splitPreserveAllTokens

    public static java.lang.String[] splitPreserveAllTokens​(java.lang.String str)

Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer. Whitespace is defined by `Character.isWhitespace(char)`.

The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.

A `null` input String returns `null`.

     StringUtils.splitPreserveAllTokens(null)       = null
     StringUtils.splitPreserveAllTokens("")         = []
     StringUtils.splitPreserveAllTokens("abc def")  = ["abc", "def"]
     StringUtils.splitPreserveAllTokens("abc  def") = ["abc", "", "def"]
     StringUtils.splitPreserveAllTokens(" abc ")    = ["", "abc", ""]

Parameters:
  `str` - the String to parse, may be `null`
Returns:
  an array of parsed Strings, `null` if null String input
Since:
  2.1

#### splitPreserveAllTokens

    public static java.lang.String[] splitPreserveAllTokens​(java.lang.String str,
                                                            char separatorChar)

Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer.

The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.

A `null` input String returns `null`.

     StringUtils.splitPreserveAllTokens(null, *)         = null
     StringUtils.splitPreserveAllTokens("", *)           = []
     StringUtils.splitPreserveAllTokens("a.b.c", '.')    = ["a", "b", "c"]
     StringUtils.splitPreserveAllTokens("a..b.c", '.')   = ["a", "", "b", "c"]
     StringUtils.splitPreserveAllTokens("a:b:c", '.')    = ["a:b:c"]
     StringUtils.splitPreserveAllTokens("a\tb\nc", null) = ["a", "b", "c"]
     StringUtils.splitPreserveAllTokens("a b c", ' ')    = ["a", "b", "c"]
     StringUtils.splitPreserveAllTokens("a b c ", ' ')   = ["a", "b", "c", ""]
     StringUtils.splitPreserveAllTokens("a b c  ", ' ')   = ["a", "b", "c", "", ""]
     StringUtils.splitPreserveAllTokens(" a b c", ' ')   = ["", a", "b", "c"]
     StringUtils.splitPreserveAllTokens("  a b c", ' ')  = ["", "", a", "b", "c"]
     StringUtils.splitPreserveAllTokens(" a b c ", ' ')  = ["", a", "b", "c", ""]

Parameters:
  `str` - the String to parse, may be `null`
  `separatorChar` - the character used as the delimiter, `null` splits on whitespace
Returns:
  an array of parsed Strings, `null` if null String input
Since:
  2.1

#### splitPreserveAllTokens

    public static java.lang.String[] splitPreserveAllTokens​(java.lang.String str,
                                                            java.lang.String separatorChars)

Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer.

The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.

A `null` input String returns `null`. A `null` separatorChars splits on whitespace.

     StringUtils.splitPreserveAllTokens(null, *)           = null
     StringUtils.splitPreserveAllTokens("", *)             = []
     StringUtils.splitPreserveAllTokens("abc def", null)   = ["abc", "def"]
     StringUtils.splitPreserveAllTokens("abc def", " ")    = ["abc", "def"]
     StringUtils.splitPreserveAllTokens("abc  def", " ")   = ["abc", "", def"]
     StringUtils.splitPreserveAllTokens("ab:cd:ef", ":")   = ["ab", "cd", "ef"]
     StringUtils.splitPreserveAllTokens("ab:cd:ef:", ":")  = ["ab", "cd", "ef", ""]
     StringUtils.splitPreserveAllTokens("ab:cd:ef::", ":") = ["ab", "cd", "ef", "", ""]
     StringUtils.splitPreserveAllTokens("ab::cd:ef", ":")  = ["ab", "", cd", "ef"]
     StringUtils.splitPreserveAllTokens(":cd:ef", ":")     = ["", cd", "ef"]
     StringUtils.splitPreserveAllTokens("::cd:ef", ":")    = ["", "", cd", "ef"]
     StringUtils.splitPreserveAllTokens(":cd:ef:", ":")    = ["", cd", "ef", ""]

Parameters:
  `str` - the String to parse, may be `null`
  `separatorChars` - the characters used as the delimiters, `null` splits on whitespace
Returns:
  an array of parsed Strings, `null` if null String input
Since:
  2.1

#### splitPreserveAllTokens

    public static java.lang.String[] splitPreserveAllTokens​(java.lang.String str,
                                                            java.lang.String separatorChars,
                                                            int max)

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

The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. Adjacent separators are treated as one separator.

A `null` input String returns `null`. A `null` separatorChars splits on whitespace.

If more than `max` delimited substrings are found, the last returned string includes all characters after the first `max - 1` returned strings (including separator characters).

     StringUtils.splitPreserveAllTokens(null, *, *)            = null
     StringUtils.splitPreserveAllTokens("", *, *)              = []
     StringUtils.splitPreserveAllTokens("ab de fg", null, 0)   = ["ab", "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

#### startsWith

    public static boolean startsWith​(java.lang.CharSequence str,
                                     java.lang.CharSequence prefix)

Check if a CharSequence starts with a specified prefix.

`null`s 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`
Since:
  2.4, 3.0 Changed signature from startsWith(String, String) to startsWith(CharSequence, CharSequence)
See Also:
  `String.startsWith(String)`

#### startsWithAny

    public static boolean startsWithAny​(java.lang.CharSequence sequence,
                                        java.lang.CharSequence... searchStrings)

Check 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:
  2.5, 3.0 Changed signature from startsWithAny(String, String[]) to startsWithAny(CharSequence, CharSequence...)
See Also:
  `startsWith(CharSequence, CharSequence)`

#### startsWithIgnoreCase

    public static boolean startsWithIgnoreCase​(java.lang.CharSequence str,
                                               java.lang.CharSequence prefix)

Case insensitive check if a CharSequence starts with a specified prefix.

`null`s 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`
Since:
  2.4, 3.0 Changed signature from startsWithIgnoreCase(String, String) to startsWithIgnoreCase(CharSequence, CharSequence)
See Also:
  `String.startsWith(String)`

#### strip

    public static java.lang.String strip​(java.lang.String str)

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

#### strip

    public static java.lang.String strip​(java.lang.String str,
                                         java.lang.String stripChars)

Strips any of a set of characters from the start and end of a String. This is similar to `String.trim()` but allows the characters to be stripped to be controlled.

A `null` input String returns `null`. An empty string ("") input returns the empty string.

If the stripChars String is `null`, whitespace is stripped as defined by `Character.isWhitespace(char)`. Alternatively use `strip(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

#### stripAccents

    public static java.lang.String stripAccents​(java.lang.String input)

Removes diacritics (~= accents) from a string. The case will not be altered.

For instance, 'à' will be replaced by 'a'.

Note that ligatures will be left as is.

     StringUtils.stripAccents(null)                = null
     StringUtils.stripAccents("")                  = ""
     StringUtils.stripAccents("control")           = "control"
     StringUtils.stripAccents("éclair")     = "eclair"

Parameters:
  `input` - String to be stripped
Returns:
  input text with diacritics removed
Since:
  3.0

#### stripAll

    public static java.lang.String[] stripAll​(java.lang.String... strs)

Strips whitespace from the start and end of every String in an array. Whitespace is defined by `Character.isWhitespace(char)`.

A new array is returned each time, except for length zero. A `null` array will return `null`. An empty array will return itself. A `null` array entry will be ignored.

     StringUtils.stripAll(null)             = null
     StringUtils.stripAll([])               = []
     StringUtils.stripAll(["abc", "  abc"]) = ["abc", "abc"]
     StringUtils.stripAll(["abc  ", null])  = ["abc", null]

Parameters:
  `strs` - the array to remove whitespace from, may be null
Returns:
  the stripped Strings, `null` if null array input

#### stripAll

    public static java.lang.String[] stripAll​(java.lang.String[] strs,
                                              java.lang.String stripChars)

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

Whitespace is defined by `Character.isWhitespace(char)`.

A new array is returned each time, except for length zero. A `null` array will return `null`. An empty array will return itself. A `null` array entry will be ignored. A `null` stripChars will strip whitespace as defined by `Character.isWhitespace(char)`.

     StringUtils.stripAll(null, *)                = null
     StringUtils.stripAll([], *)                  = []
     StringUtils.stripAll(["abc", "  abc"], null) = ["abc", "abc"]
     StringUtils.stripAll(["abc  ", null], null)  = ["abc", null]
     StringUtils.stripAll(["abc  ", null], "yz")  = ["abc  ", null]
     StringUtils.stripAll(["yabcz", null], "yz")  = ["abc", null]

Parameters:
  `strs` - the array to remove characters from, may be null
  `stripChars` - the characters to remove, null treated as whitespace
Returns:
  the stripped Strings, `null` if null array input

#### stripEnd

    public static java.lang.String stripEnd​(java.lang.String str,
                                            java.lang.String stripChars)

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

A `null` input String returns `null`. An empty string ("") input returns the empty string.

If the stripChars String is `null`, whitespace is stripped as defined by `Character.isWhitespace(char)`.

     StringUtils.stripEnd(null, *)          = null
     StringUtils.stripEnd("", *)            = ""
     StringUtils.stripEnd("abc", "")        = "abc"
     StringUtils.stripEnd("abc", null)      = "abc"
     StringUtils.stripEnd("  abc", null)    = "  abc"
     StringUtils.stripEnd("abc  ", null)    = "abc"
     StringUtils.stripEnd(" abc ", null)    = " abc"
     StringUtils.stripEnd("  abcyx", "xyz") = "  abc"
     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

#### stripStart

    public static java.lang.String stripStart​(java.lang.String str,
                                              java.lang.String stripChars)

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

A `null` input String returns `null`. An empty string ("") input returns the empty string.

If the stripChars String is `null`, whitespace is stripped as defined by `Character.isWhitespace(char)`.

     StringUtils.stripStart(null, *)          = null
     StringUtils.stripStart("", *)            = ""
     StringUtils.stripStart("abc", "")        = "abc"
     StringUtils.stripStart("abc", null)      = "abc"
     StringUtils.stripStart("  abc", null)    = "abc"
     StringUtils.stripStart("abc  ", null)    = "abc  "
     StringUtils.stripStart(" abc ", null)    = "abc "
     StringUtils.stripStart("yxabc  ", "xyz") = "abc  "

Parameters:
  `str` - the String to remove characters from, may be null
  `stripChars` - the characters to remove, null treated as whitespace
Returns:
  the stripped String, `null` if null String input

#### stripToEmpty

    public static java.lang.String stripToEmpty​(java.lang.String str)

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

#### stripToNull

    public static java.lang.String stripToNull​(java.lang.String str)

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

This is similar to `trimToNull(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

#### substring

    public static java.lang.String substring​(java.lang.String str,
                                             int start)

Gets a substring from the specified String avoiding exceptions.

A negative start position can be used to start `n` characters from the end of the String.

A `null` String will return `null`. An empty ("") String will return "".

     StringUtils.substring(null, *)   = null
     StringUtils.substring("", *)     = ""
     StringUtils.substring("abc", 0)  = "abc"
     StringUtils.substring("abc", 2)  = "c"
     StringUtils.substring("abc", 4)  = ""
     StringUtils.substring("abc", -2) = "bc"
     StringUtils.substring("abc", -4) = "abc"

Parameters:
  `str` - the String to get the substring from, may be null
  `start` - the position to start from, negative means count back from the end of the String by this many characters
Returns:
  substring from start position, `null` if null String input

#### substring

    public static java.lang.String substring​(java.lang.String str,
                                             int start,
                                             int end)

Gets a substring from the specified String avoiding exceptions.

A negative start position can be used to start/end `n` characters from the end of the String.

The returned substring starts with the character in the `start` position and ends before the `end` position. All position counting is zero-based -- i.e., to start at the beginning of the string use `start = 0`. Negative start and end positions can be used to specify offsets relative to the end of the String.

If `start` is not strictly to the left of `end`, "" is returned.

     StringUtils.substring(null, *, *)    = null
     StringUtils.substring("", * ,  *)    = "";
     StringUtils.substring("abc", 0, 2)   = "ab"
     StringUtils.substring("abc", 2, 0)   = ""
     StringUtils.substring("abc", 2, 4)   = "c"
     StringUtils.substring("abc", 4, 6)   = ""
     StringUtils.substring("abc", 2, 2)   = ""
     StringUtils.substring("abc", -2, -1) = "b"
     StringUtils.substring("abc", -4, 2)  = "ab"

Parameters:
  `str` - the String to get the substring from, may be null
  `start` - the position to start from, negative means count back from the end of the String by this many characters
  `end` - the position to end at (exclusive), negative means count back from the end of the String by this many characters
Returns:
  substring from start position to end position, `null` if null String input

#### substringAfter

    public static java.lang.String substringAfter​(java.lang.String str,
                                                  int separator)

Gets the substring after the first occurrence of a separator. The separator is not returned.

A `null` string input will return `null`. An empty ("") string input will return the empty string.

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
  `separator` - the character to search.
Returns:
  the substring after the first occurrence of the separator, `null` if null String input
Since:
  3.11

#### substringAfter

    public static java.lang.String substringAfter​(java.lang.String str,
                                                  java.lang.String separator)

Gets the substring after the first occurrence of a separator. The separator is not returned.

A `null` string input will return `null`. An empty ("") string input will return the empty string. A `null` separator will return the empty string if the input string is not `null`.

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
  `separator` - the String to search for, may be null
Returns:
  the substring after the first occurrence of the separator, `null` if null String input
Since:
  2.0

#### substringAfterLast

    public static java.lang.String substringAfterLast​(java.lang.String str,
                                                      int separator)

Gets the substring after the last occurrence of a separator. The separator is not returned.

A `null` string input will return `null`. An empty ("") string input will return the empty string.

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
  `separator` - the String to search for, may be null
Returns:
  the substring after the last occurrence of the separator, `null` if null String input
Since:
  3.11

#### substringAfterLast

    public static java.lang.String substringAfterLast​(java.lang.String str,
                                                      java.lang.String separator)

Gets the substring after the last occurrence of a separator. The separator is not returned.

A `null` string input will return `null`. An empty ("") string input will return the empty string. An empty or `null` separator will return the empty string if the input string is not `null`.

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
  `separator` - the String to search for, may be null
Returns:
  the substring after the last occurrence of the separator, `null` if null String input
Since:
  2.0

#### substringBefore

    public static java.lang.String substringBefore​(java.lang.String str,
                                                   java.lang.String separator)

Gets the substring before the first occurrence of a separator. The separator is not returned.

A `null` string input will return `null`. An empty ("") string input will return the empty string. A `null` separator will return the input string.

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
  `separator` - the String to search for, may be null
Returns:
  the substring before the first occurrence of the separator, `null` if null String input
Since:
  2.0

#### substringBeforeLast

    public static java.lang.String substringBeforeLast​(java.lang.String str,
                                                       java.lang.String separator)

Gets the substring before the last occurrence of a separator. The separator is not returned.

A `null` string input will return `null`. An empty ("") string input will return the empty string. An empty or `null` separator will return the input string.

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
  `separator` - the String to search for, may be null
Returns:
  the substring before the last occurrence of the separator, `null` if null String input
Since:
  2.0

#### substringBetween

    public static java.lang.String substringBetween​(java.lang.String str,
                                                    java.lang.String tag)

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

A `null` input String returns `null`. A `null` tag returns `null`.

     StringUtils.substringBetween(null, *)            = null
     StringUtils.substringBetween("", "")             = ""
     StringUtils.substringBetween("", "tag")          = null
     StringUtils.substringBetween("tagabctag", null)  = null
     StringUtils.substringBetween("tagabctag", "")    = ""
     StringUtils.substringBetween("tagabctag", "tag") = "abc"

Parameters:
  `str` - the String containing the substring, may be null
  `tag` - the String before and after the substring, may be null
Returns:
  the substring, `null` if no match
Since:
  2.0

#### substringBetween

    public static java.lang.String substringBetween​(java.lang.String str,
                                                    java.lang.String open,
                                                    java.lang.String close)

Gets the String that is nested in between two Strings. Only the first match is returned.

A `null` input String returns `null`. A `null` open/close returns `null` (no match). An empty ("") open and close returns an empty string.

     StringUtils.substringBetween("wx[b]yz", "[", "]") = "b"
     StringUtils.substringBetween(null, *, *)          = null
     StringUtils.substringBetween(*, null, *)          = null
     StringUtils.substringBetween(*, *, null)          = null
     StringUtils.substringBetween("", "", "")          = ""
     StringUtils.substringBetween("", "", "]")         = null
     StringUtils.substringBetween("", "[", "]")        = null
     StringUtils.substringBetween("yabcz", "", "")     = ""
     StringUtils.substringBetween("yabcz", "y", "z")   = "abc"
     StringUtils.substringBetween("yabczyabcz", "y", "z")   = "abc"

Parameters:
  `str` - the String containing the substring, may be null
  `open` - the String before the substring, may be null
  `close` - the String after the substring, may be null
Returns:
  the substring, `null` if no match
Since:
  2.0

#### substringsBetween

    public static java.lang.String[] substringsBetween​(java.lang.String str,
                                                       java.lang.String open,
                                                       java.lang.String close)

Searches a String for substrings delimited by a start and end tag, returning all matching substrings in an array.

A `null` input String returns `null`. A `null` open/close returns `null` (no match). An empty ("") open/close returns `null` (no match).

     StringUtils.substringsBetween("[a][b][c]", "[", "]") = ["a","b","c"]
     StringUtils.substringsBetween(null, *, *)            = null
     StringUtils.substringsBetween(*, null, *)            = null
     StringUtils.substringsBetween(*, *, null)            = null
     StringUtils.substringsBetween("", "[", "]")          = []

Parameters:
  `str` - the String containing the substrings, null returns null, empty returns empty
  `open` - the String identifying the start of the substring, empty returns null
  `close` - the String identifying the end of the substring, empty returns null
Returns:
  a String Array of substrings, or `null` if no match
Since:
  2.3

#### swapCase

    public static java.lang.String swapCase​(java.lang.String str)

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

- Upper case character converts to Lower case
- Title case character converts to Lower case
- Lower case character converts to Upper case

For a word based algorithm, see `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

#### toCodePoints

    public static int[] toCodePoints​(java.lang.CharSequence str)

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:
  `str` - the character sequence to convert
Returns:
  an array of code points
Since:
  3.6

#### toEncodedString

    public static java.lang.String toEncodedString​(byte[] bytes,
                                                   java.nio.charset.Charset charset)

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` - if `bytes` is null
Since:
  3.2, 3.3 No longer throws `UnsupportedEncodingException`.

#### toRootLowerCase

    public static java.lang.String toRootLowerCase​(java.lang.String 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

#### toRootUpperCase

    public static java.lang.String toRootUpperCase​(java.lang.String source)

Converts the given source String as a 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 a upper-case using the `Locale.ROOT` locale or null.
Since:
  3.10

#### toString

    @Deprecated
    public static java.lang.String toString​(byte[] bytes,
                                            java.lang.String charsetName)
                                     throws java.io.UnsupportedEncodingException

Deprecated.
use `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.io.UnsupportedEncodingException` - If the named charset is not supported
  `java.lang.NullPointerException` - if the input is null
Since:
  3.1

#### trim

    public static java.lang.String trim​(java.lang.String str)

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

The String is trimmed using `String.trim()`. Trim removes start and end characters <= 32. To strip whitespace use `strip(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

#### trimToEmpty

    public static java.lang.String trimToEmpty​(java.lang.String str)

Removes control characters (char <= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if it is `null`.

The String is trimmed using `String.trim()`. Trim removes start and end characters <= 32. To strip whitespace use `stripToEmpty(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

#### trimToNull

    public static java.lang.String trimToNull​(java.lang.String str)

Removes control characters (char <= 32) from both ends of this String returning `null` if the String is empty ("") after the trim or if it is `null`.

The String is trimmed using `String.trim()`. Trim removes start and end characters <= 32. To strip whitespace use `stripToNull(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

#### truncate

    public static java.lang.String truncate​(java.lang.String str,
                                            int maxWidth)

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 positive
Returns:
  truncated String, `null` if null String input
Throws:
  `java.lang.IllegalArgumentException` - If `maxWidth` is less than `0`
Since:
  3.5

#### truncate

    public static java.lang.String truncate​(java.lang.String str,
                                            int offset,
                                            int maxWidth)

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 positive
Returns:
  truncated String, `null` if null String input
Throws:
  `java.lang.IllegalArgumentException` - If `offset` or `maxWidth` is less than `0`
Since:
  3.5

#### uncapitalize

    public static java.lang.String uncapitalize​(java.lang.String str)

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 `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
Since:
  2.0
See Also:
  `WordUtils.uncapitalize(String)`, `capitalize(String)`

#### unwrap

    public static java.lang.String unwrap​(java.lang.String str,
                                          char wrapChar)

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

#### unwrap

    public static java.lang.String unwrap​(java.lang.String str,
                                          java.lang.String wrapToken)

Unwraps a given string from anther 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

#### upperCase

    public static java.lang.String upperCase​(java.lang.String str)

Converts a String to upper case as per `String.toUpperCase()`.

A `null` input String returns `null`.

     StringUtils.upperCase(null)  = null
     StringUtils.upperCase("")    = ""
     StringUtils.upperCase("aBc") = "ABC"

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 `lowerCase(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

#### upperCase

    public static java.lang.String upperCase​(java.lang.String str,
                                             java.util.Locale locale)

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

#### valueOf

    public static java.lang.String valueOf​(char[] value)

Returns the string representation of the `char` array or null.

Parameters:
  `value` - the character array.
Returns:
  a String or null
Since:
  3.9
See Also:
  `String.valueOf(char[])`

#### wrap

    public static java.lang.String wrap​(java.lang.String str,
                                        char wrapWith)

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

#### wrap

    public static java.lang.String wrap​(java.lang.String str,
                                        java.lang.String wrapWith)

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

#### wrapIfMissing

    public static java.lang.String wrapIfMissing​(java.lang.String str,
                                                 char wrapWith)

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

#### wrapIfMissing

    public static java.lang.String wrapIfMissing​(java.lang.String str,
                                                 java.lang.String wrapWith)

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