Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.lang
Class StringUtils

    java.lang.Object
      |
      +--org.apache.commons.lang.StringUtils

public class StringUtils
extends Object

Operations on `String` that are `null` safe.

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

The `StringUtils` class defines certain words related to String handling.

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

`StringUtils` handles `null` input Strings quietly. That is to say that a `null` input will return `null`. Where a `boolean` or `int` is being returned details vary by method.

A side effect of the `null` handling is that a `NullPointerException` should be considered a bug in `StringUtils` (except for deprecated methods).

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

Since:
  1.0
Version:
  $Id: StringUtils.java 492377 2007-01-04 01:20:30Z scolebourne $
Author:
  Apache Jakarta Turbine, Jon S. Stevens, Daniel Rall, Greg Coladonato, Ed Korthof, Rand McNeely, Stephen Colebourne, Fredrik Westermarck, Holger Krauth, Alexander Day Chaffee, Henning P. Schmiedehausen, Arun Mammen Thomas, Gary Gregory, Phil Steitz, Al Chou, Michael Davey, Reuben Sivan, Chris Hyzer
See Also:
  `String`

Field Summary
`static String` | `EMPTY` The empty String `""`.
`static int` | `INDEX_NOT_FOUND` Represents a failed index search.

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

Method Summary
`static String` | `abbreviate(String str, int maxWidth)` Abbreviates a String using ellipses.
`static String` | `abbreviate(String str, int offset, int maxWidth)` Abbreviates a String using ellipses.
`static String` | `capitalise(String str)` Deprecated. Use the standardly named `capitalize(String)`. Method will be removed in Commons Lang 3.0.
`static String` | `capitaliseAllWords(String str)` Deprecated. Use the relocated `WordUtils.capitalize(String)`. Method will be removed in Commons Lang 3.0.
`static String` | `capitalize(String str)` Capitalizes a String changing the first letter to title case as per `Character.toTitleCase(char)`.
`static String` | `center(String str, int size)` Centers a String in a larger String of size `size` using the space character (' ').
`static String` | `center(String str, int size, char padChar)` Centers a String in a larger String of size `size`.
`static String` | `center(String str, int size, String padStr)` Centers a String in a larger String of size `size`.
`static String` | `chomp(String str)` Removes one newline from end of a String if it's there, otherwise leave it alone.
`static String` | `chomp(String str, String separator)` Removes `separator` from the end of `str` if it's there, otherwise leave it alone.
`static String` | `chompLast(String str)` Deprecated. Use `chomp(String)` instead. Method will be removed in Commons Lang 3.0.
`static String` | `chompLast(String str, String sep)` Deprecated. Use `chomp(String,String)` instead. Method will be removed in Commons Lang 3.0.
`static String` | `chop(String str)` Remove the last character from a String.
`static String` | `chopNewline(String str)` Deprecated. Use `chomp(String)` instead. Method will be removed in Commons Lang 3.0.
`static String` | `clean(String str)` Deprecated. Use the clearer named `trimToEmpty(String)`. Method will be removed in Commons Lang 3.0.
`static String` | `concatenate(Object[] array)` Deprecated. Use the better named `join(Object[])` instead. Method will be removed in Commons Lang 3.0.
`static boolean` | `contains(String str, char searchChar)` Checks if String contains a search character, handling `null`.
`static boolean` | `contains(String str, String searchStr)` Checks if String contains a search String, handling `null`.
`static boolean` | `containsIgnoreCase(String str, String searchStr)` Checks if String contains a search String irrespective of case, handling `null`.
`static boolean` | `containsNone(String str, char[] invalidChars)` Checks that the String does not contain certain characters.
`static boolean` | `containsNone(String str, String invalidChars)` Checks that the String does not contain certain characters.
`static boolean` | `containsOnly(String str, char[] valid)` Checks if the String contains only certain characters.
`static boolean` | `containsOnly(String str, String validChars)` Checks if the String contains only certain characters.
`static int` | `countMatches(String str, String sub)` Counts how many times the substring appears in the larger String.
`static String` | `defaultIfEmpty(String str, String defaultStr)` Returns either the passed in String, or if the String is empty or `null`, the value of `defaultStr`.
`static String` | `defaultString(String str)` Returns either the passed in String, or if the String is `null`, an empty String ("").
`static String` | `defaultString(String str, String defaultStr)` Returns either the passed in String, or if the String is `null`, the value of `defaultStr`.
`static String` | `deleteSpaces(String str)` Deprecated. Use the better localized `deleteWhitespace(String)`. Method will be removed in Commons Lang 3.0.
`static String` | `deleteWhitespace(String str)` Deletes all whitespaces from a String as defined by `Character.isWhitespace(char)`.
`static String` | `difference(String str1, String str2)` Compares two Strings, and returns the portion where they differ.
`static boolean` | `equals(String str1, String str2)` Compares two Strings, returning `true` if they are equal.
`static boolean` | `equalsIgnoreCase(String str1, String str2)` Compares two Strings, returning `true` if they are equal ignoring the case.
`static String` | `escape(String str)` Deprecated. Use `StringEscapeUtils.escapeJava(String)` This method will be removed in Commons Lang 3.0
`static String` | `getChomp(String str, String sep)` Deprecated. Use `substringAfterLast(String, String)` instead (although this doesn't include the separator) Method will be removed in Commons Lang 3.0.
`static int` | `getLevenshteinDistance(String s, String t)` Find the Levenshtein distance between two Strings.
`static String` | `getNestedString(String str, String tag)` Deprecated. Use the better named `substringBetween(String, String)`. Method will be removed in Commons Lang 3.0.
`static String` | `getNestedString(String str, String open, String close)` Deprecated. Use the better named `substringBetween(String, String, String)`. Method will be removed in Commons Lang 3.0.
`static String` | `getPrechomp(String str, String sep)` Deprecated. Use `substringBefore(String,String)` instead (although this doesn't include the separator). Method will be removed in Commons Lang 3.0.
`static int` | `indexOf(String str, char searchChar)` Finds the first index within a String, handling `null`.
`static int` | `indexOf(String str, char searchChar, int startPos)` Finds the first index within a String from a start position, handling `null`.
`static int` | `indexOf(String str, String searchStr)` Finds the first index within a String, handling `null`.
`static int` | `indexOf(String str, String searchStr, int startPos)` Finds the first index within a String, handling `null`.
`static int` | `indexOfAny(String str, char[] searchChars)` Search a String to find the first index of any character in the given set of characters.
`static int` | `indexOfAny(String str, String searchChars)` Search a String to find the first index of any character in the given set of characters.
`static int` | `indexOfAny(String str, String[] searchStrs)` Find the first index of any of a set of potential substrings.
`static int` | `indexOfAnyBut(String str, char[] searchChars)` Search a String to find the first index of any character not in the given set of characters.
`static int` | `indexOfAnyBut(String str, String searchChars)` Search a String to find the first index of any character not in the given set of characters.
`static int` | `indexOfDifference(String str1, String str2)` Compares two Strings, and returns the index at which the Strings begin to differ.
`static boolean` | `isAlpha(String str)` Checks if the String contains only unicode letters.
`static boolean` | `isAlphanumeric(String str)` Checks if the String contains only unicode letters or digits.
`static boolean` | `isAlphanumericSpace(String str)` Checks if the String contains only unicode letters, digits or space (`' '`).
`static boolean` | `isAlphaSpace(String str)` Checks if the String contains only unicode letters and space (' ').
`static boolean` | `isAsciiPrintable(String str)` Checks if the string contains only ASCII printable characters.
`static boolean` | `isBlank(String str)` Checks if a String is whitespace, empty ("") or null.
`static boolean` | `isEmpty(String str)` Checks if a String is empty ("") or null.
`static boolean` | `isNotBlank(String str)` Checks if a String is not empty (""), not null and not whitespace only.
`static boolean` | `isNotEmpty(String str)` Checks if a String is not empty ("") and not null.
`static boolean` | `isNumeric(String str)` Checks if the String contains only unicode digits.
`static boolean` | `isNumericSpace(String str)` Checks if the String contains only unicode digits or space (`' '`).
`static boolean` | `isWhitespace(String str)` Checks if the String contains only whitespace.
`static String` | `join(Collection collection, char separator)` Joins the elements of the provided `Collection` into a single String containing the provided elements.
`static String` | `join(Collection collection, String separator)` Joins the elements of the provided `Collection` into a single String containing the provided elements.
`static String` | `join(Iterator iterator, char separator)` Joins the elements of the provided `Iterator` into a single String containing the provided elements.
`static String` | `join(Iterator iterator, String separator)` Joins the elements of the provided `Iterator` into a single String containing the provided elements.
`static String` | `join(Object[] array)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static String` | `join(Object[] array, char separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static String` | `join(Object[] array, char separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static String` | `join(Object[] array, String separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static String` | `join(Object[] array, String separator, int startIndex, int endIndex)` Joins the elements of the provided array into a single String containing the provided list of elements.
`static int` | `lastIndexOf(String str, char searchChar)` Finds the last index within a String, handling `null`.
`static int` | `lastIndexOf(String str, char searchChar, int startPos)` Finds the last index within a String from a start position, handling `null`.
`static int` | `lastIndexOf(String str, String searchStr)` Finds the last index within a String, handling `null`.
`static int` | `lastIndexOf(String str, String searchStr, int startPos)` Finds the first index within a String, handling `null`.
`static int` | `lastIndexOfAny(String str, String[] searchStrs)` Find the latest index of any of a set of potential substrings.
`static String` | `left(String str, int len)` Gets the leftmost `len` characters of a String.
`static String` | `leftPad(String str, int size)` Left pad a String with spaces (' ').
`static String` | `leftPad(String str, int size, char padChar)` Left pad a String with a specified character.
`static String` | `leftPad(String str, int size, String padStr)` Left pad a String with a specified String.
`static String` | `lowerCase(String str)` Converts a String to lower case as per `String.toLowerCase()`.
`static String` | `mid(String str, int pos, int len)` Gets `len` characters from the middle of a String.
`static int` | `ordinalIndexOf(String str, String searchStr, int ordinal)` Finds the n-th index within a String, handling `null`.
`static String` | `overlay(String str, String overlay, int start, int end)` Overlays part of a String with another String.
`static String` | `overlayString(String text, String overlay, int start, int end)` Deprecated. Use better named `overlay(String, String, int, int)` instead. Method will be removed in Commons Lang 3.0.
`static String` | `prechomp(String str, String sep)` Deprecated. Use `substringAfter(String,String)` instead. Method will be removed in Commons Lang 3.0.
`static String` | `remove(String str, char remove)` Removes all occurances of a character from within the source string.
`static String` | `remove(String str, String remove)` Removes all occurances of a substring from within the source string.
`static String` | `removeEnd(String str, String remove)` Removes a substring only if it is at the end of a source string, otherwise returns the source string.
`static String` | `removeStart(String str, String remove)` Removes a substring only if it is at the begining of a source string, otherwise returns the source string.
`static String` | `repeat(String str, int repeat)` Repeat a String `repeat` times to form a new String.
`static String` | `replace(String text, String repl, String with)` Replaces all occurrences of a String within another String.
`static String` | `replace(String text, String repl, String with, int max)` Replaces a String with another String inside a larger String, for the first `max` values of the search String.
`static String` | `replaceChars(String str, char searchChar, char replaceChar)` Replaces all occurrences of a character in a String with another.
`static String` | `replaceChars(String str, String searchChars, String replaceChars)` Replaces multiple characters in a String in one go.
`static String` | `replaceOnce(String text, String repl, String with)` Replaces a String with another String inside a larger String, once.
`static String` | `reverse(String str)` Reverses a String as per `StringBuffer.reverse()`.
`static String` | `reverseDelimited(String str, char separatorChar)` Reverses a String that is delimited by a specific character.
`static String` | `reverseDelimitedString(String str, String separatorChars)` Deprecated. Use `reverseDelimited(String, char)` instead. This method is broken as the join doesn't know which char to use. Method will be removed in Commons Lang 3.0.
`static String` | `right(String str, int len)` Gets the rightmost `len` characters of a String.
`static String` | `rightPad(String str, int size)` Right pad a String with spaces (' ').
`static String` | `rightPad(String str, int size, char padChar)` Right pad a String with a specified character.
`static String` | `rightPad(String str, int size, String padStr)` Right pad a String with a specified String.
`static String[]` | `split(String str)` Splits the provided text into an array, using whitespace as the separator.
`static String[]` | `split(String str, char separatorChar)` Splits the provided text into an array, separator specified.
`static String[]` | `split(String str, String separatorChars)` Splits the provided text into an array, separators specified.
`static String[]` | `split(String str, String separatorChars, int max)` Splits the provided text into an array with a maximum length, separators specified.
`static String[]` | `splitByWholeSeparator(String str, String separator)` Splits the provided text into an array, separator string specified.
`static String[]` | `splitByWholeSeparator(String str, String separator, int max)` Splits the provided text into an array, separator string specified.
`static String[]` | `splitPreserveAllTokens(String str)` Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators.
`static String[]` | `splitPreserveAllTokens(String str, char separatorChar)` Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators.
`static String[]` | `splitPreserveAllTokens(String str, String separatorChars)` Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators.
`static String[]` | `splitPreserveAllTokens(String str, String separatorChars, int max)` Splits the provided text into an array with a maximum length, separators specified, preserving all tokens, including empty tokens created by adjacent separators.
`static String` | `strip(String str)` Strips whitespace from the start and end of a String.
`static String` | `strip(String str, String stripChars)` Strips any of a set of characters from the start and end of a String.
`static String[]` | `stripAll(String[] strs)` Strips whitespace from the start and end of every String in an array.
`static String[]` | `stripAll(String[] strs, String stripChars)` Strips any of a set of characters from the start and end of every String in an array.
`static String` | `stripEnd(String str, String stripChars)` Strips any of a set of characters from the end of a String.
`static String` | `stripStart(String str, String stripChars)` Strips any of a set of characters from the start of a String.
`static String` | `stripToEmpty(String str)` Strips whitespace from the start and end of a String returning an empty String if `null` input.
`static String` | `stripToNull(String str)` Strips whitespace from the start and end of a String returning `null` if the String is empty ("") after the strip.
`static String` | `substring(String str, int start)` Gets a substring from the specified String avoiding exceptions.
`static String` | `substring(String str, int start, int end)` Gets a substring from the specified String avoiding exceptions.
`static String` | `substringAfter(String str, String separator)` Gets the substring after the first occurrence of a separator.
`static String` | `substringAfterLast(String str, String separator)` Gets the substring after the last occurrence of a separator.
`static String` | `substringBefore(String str, String separator)` Gets the substring before the first occurrence of a separator.
`static String` | `substringBeforeLast(String str, String separator)` Gets the substring before the last occurrence of a separator.
`static String` | `substringBetween(String str, String tag)` Gets the String that is nested in between two instances of the same String.
`static String` | `substringBetween(String str, String open, String close)` Gets the String that is nested in between two Strings.
`static String[]` | `substringsBetween(String str, String open, String close)` Searches a String for substrings delimited by a start and end tag, returning all matching substrings in an array.
`static String` | `swapCase(String str)` Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
`static String` | `trim(String str)` Removes control characters (char <= 32) from both ends of this String, handling `null` by returning `null`.
`static String` | `trimToEmpty(String str)` Removes control characters (char <= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if it is `null`.
`static String` | `trimToNull(String str)` Removes control characters (char <= 32) from both ends of this String returning `null` if the String is empty ("") after the trim or if it is `null`.
`static String` | `uncapitalise(String str)` Deprecated. Use the standardly named `uncapitalize(String)`. Method will be removed in Commons Lang 3.0.
`static String` | `uncapitalize(String str)` Uncapitalizes a String changing the first letter to title case as per `Character.toLowerCase(char)`.
`static String` | `upperCase(String str)` Converts a String to upper case as per `String.toUpperCase()`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### EMPTY

    public static final String EMPTY

  The empty String `""`.
  Since:
    2.0

### INDEX_NOT_FOUND

    public static final int INDEX_NOT_FOUND

  Represents a failed index search.
  Since:
    2.1

Constructor Detail

### StringUtils

    public StringUtils()

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

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

Method Detail

### isEmpty

    public static boolean isEmpty(String str)

  Checks if a String is empty ("") or null.

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

  NOTE: This method changed in Lang version 2.0. It no longer trims the String. That functionality is available in isBlank().

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if the String is empty or null

### isNotEmpty

    public static boolean isNotEmpty(String str)

  Checks if a String is not empty ("") and not null.

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if the String is not empty and not null

### isBlank

    public static boolean isBlank(String str)

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

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if the String is null, empty or whitespace
  Since:
    2.0

### isNotBlank

    public static boolean isNotBlank(String str)

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

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if the String is not empty and not null and not whitespace
  Since:
    2.0

### clean

    public static String clean(String str)

  Deprecated. Use the clearer named `trimToEmpty(String)`. Method will be removed in Commons Lang 3.0.

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

       StringUtils.clean(null)          = ""
       StringUtils.clean("")            = ""
       StringUtils.clean("abc")         = "abc"
       StringUtils.clean("    abc    ") = "abc"
       StringUtils.clean("     ")       = ""

  Parameters:
    `str` - the String to clean, may be null
  Returns:
    the trimmed text, never `null`
  See Also:
    `String.trim()`

### trim

    public static String trim(String str)

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

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

### trimToNull

    public static String trimToNull(String str)

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

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

### trimToEmpty

    public static String trimToEmpty(String str)

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

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

### strip

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

### stripToNull

    public static String stripToNull(String str)

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

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

### stripToEmpty

    public static String stripToEmpty(String str)

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

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

### strip

    public static String strip(String str,
                               String stripChars)

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

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

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

### stripStart

    public static String stripStart(String str,
                                    String stripChars)

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

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

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

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

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

### stripEnd

    public static String stripEnd(String str,
                                  String stripChars)

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

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

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

       StringUtils.stripEnd(null, *)          = null
       StringUtils.stripEnd("", *)            = ""
       StringUtils.stripEnd("abc", "")        = "abc"
       StringUtils.stripEnd("abc", null)      = "abc"
       StringUtils.stripEnd("  abc", null)    = "  abc"
       StringUtils.stripEnd("abc  ", null)    = "abc"
       StringUtils.stripEnd(" abc ", null)    = " abc"
       StringUtils.stripEnd("  abcyx", "xyz") = "  abc"

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

### stripAll

    public static String[] stripAll(String[] strs)

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

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

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

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

### stripAll

    public static String[] stripAll(String[] strs,
                                    String stripChars)

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

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

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

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

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

### equals

    public static boolean equals(String str1,
                                 String str2)

  Compares two Strings, returning `true` if they are equal.

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

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

  Parameters:
    `str1` - the first String, may be null
    `str2` - the second String, may be null
  Returns:
    `true` if the Strings are equal, case sensitive, or both `null`
  See Also:
    `String.equals(Object)`

### equalsIgnoreCase

    public static boolean equalsIgnoreCase(String str1,
                                           String str2)

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

  `null`s are handled without exceptions. Two `null` references are considered equal. Comparison is case insensitive.

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

  Parameters:
    `str1` - the first String, may be null
    `str2` - the second String, may be null
  Returns:
    `true` if the Strings are equal, case insensitive, or both `null`
  See Also:
    `String.equalsIgnoreCase(String)`

### indexOf

    public static int indexOf(String str,
                              char searchChar)

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

  A `null` or empty ("") String will return `-1`.

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

  Parameters:
    `str` - the String to check, may be null
    `searchChar` - the character to find
  Returns:
    the first index of the search character, -1 if no match or `null` string input
  Since:
    2.0

### indexOf

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

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

  A `null` or empty ("") String will return `-1`. A negative start position is treated as zero. A start position greater than the string length returns `-1`.

       StringUtils.indexOf(null, *, *)          = -1
       StringUtils.indexOf("", *, *)            = -1
       StringUtils.indexOf("aabaabaa", 'b', 0)  = 2
       StringUtils.indexOf("aabaabaa", 'b', 3)  = 5
       StringUtils.indexOf("aabaabaa", 'b', 9)  = -1
       StringUtils.indexOf("aabaabaa", 'b', -1) = 2

  Parameters:
    `str` - the String to check, may be null
    `searchChar` - the character to find
    `startPos` - the start position, negative treated as zero
  Returns:
    the first index of the search character, -1 if no match or `null` string input
  Since:
    2.0

### indexOf

    public static int indexOf(String str,
                              String searchStr)

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

  A `null` String will return `-1`.

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

  Parameters:
    `str` - the String to check, may be null
    `searchStr` - the String to find, may be null
  Returns:
    the first index of the search String, -1 if no match or `null` string input
  Since:
    2.0

### ordinalIndexOf

    public static int ordinalIndexOf(String str,
                                     String searchStr,
                                     int ordinal)

  Finds the n-th index within a String, handling `null`. This method uses `String.indexOf(String)`.

  A `null` String will return `-1`.

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

  Parameters:
    `str` - the String to check, may be null
    `searchStr` - the String to find, may be null
    `ordinal` - the n-th `searchStr` to find
  Returns:
    the n-th index of the search String, `-1` (`INDEX_NOT_FOUND`) if no match or `null` string input
  Since:
    2.1

### indexOf

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

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

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

       StringUtils.indexOf(null, *, *)          = -1
       StringUtils.indexOf(*, null, *)          = -1
       StringUtils.indexOf("", "", 0)           = 0
       StringUtils.indexOf("aabaabaa", "a", 0)  = 0
       StringUtils.indexOf("aabaabaa", "b", 0)  = 2
       StringUtils.indexOf("aabaabaa", "ab", 0) = 1
       StringUtils.indexOf("aabaabaa", "b", 3)  = 5
       StringUtils.indexOf("aabaabaa", "b", 9)  = -1
       StringUtils.indexOf("aabaabaa", "b", -1) = 2
       StringUtils.indexOf("aabaabaa", "", 2)   = 2
       StringUtils.indexOf("abc", "", 9)        = 3

  Parameters:
    `str` - the String to check, may be null
    `searchStr` - the String to find, may be null
    `startPos` - the start position, negative treated as zero
  Returns:
    the first index of the search String, -1 if no match or `null` string input
  Since:
    2.0

### lastIndexOf

    public static int lastIndexOf(String str,
                                  char searchChar)

  Finds the last index within a String, handling `null`. This method uses `String.lastIndexOf(int)`.

  A `null` or empty ("") String will return `-1`.

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

  Parameters:
    `str` - the String to check, may be null
    `searchChar` - the character to find
  Returns:
    the last index of the search character, -1 if no match or `null` string input
  Since:
    2.0

### lastIndexOf

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

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

  A `null` or empty ("") String will return `-1`. A negative start position returns `-1`. A start position greater than the string length searches the whole string.

       StringUtils.lastIndexOf(null, *, *)          = -1
       StringUtils.lastIndexOf("", *,  *)           = -1
       StringUtils.lastIndexOf("aabaabaa", 'b', 8)  = 5
       StringUtils.lastIndexOf("aabaabaa", 'b', 4)  = 2
       StringUtils.lastIndexOf("aabaabaa", 'b', 0)  = -1
       StringUtils.lastIndexOf("aabaabaa", 'b', 9)  = 5
       StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1
       StringUtils.lastIndexOf("aabaabaa", 'a', 0)  = 0

  Parameters:
    `str` - the String to check, may be null
    `searchChar` - the character to find
    `startPos` - the start position
  Returns:
    the last index of the search character, -1 if no match or `null` string input
  Since:
    2.0

### lastIndexOf

    public static int lastIndexOf(String str,
                                  String searchStr)

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

  A `null` String will return `-1`.

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

  Parameters:
    `str` - the String to check, may be null
    `searchStr` - the String to find, may be null
  Returns:
    the last index of the search String, -1 if no match or `null` string input
  Since:
    2.0

### lastIndexOf

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

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

  A `null` String will return `-1`. A negative start position returns `-1`. An empty ("") search String always matches unless the start position is negative. A start position greater than the string length searches the whole string.

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

  Parameters:
    `str` - the String to check, may be null
    `searchStr` - the String to find, may be null
    `startPos` - the start position, negative treated as zero
  Returns:
    the first index of the search String, -1 if no match or `null` string input
  Since:
    2.0

### contains

    public static boolean contains(String str,
                                   char searchChar)

  Checks if String contains a search character, handling `null`. This method uses `String.indexOf(int)`.

  A `null` or empty ("") String will return `false`.

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

  Parameters:
    `str` - the String to check, may be null
    `searchChar` - the character to find
  Returns:
    true if the String contains the search character, false if not or `null` string input
  Since:
    2.0

### contains

    public static boolean contains(String str,
                                   String searchStr)

  Checks if String contains a search String, handling `null`. This method uses `String.indexOf(String)`.

  A `null` String will return `false`.

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

  Parameters:
    `str` - the String to check, may be null
    `searchStr` - the String to find, may be null
  Returns:
    true if the String contains the search String, false if not or `null` string input
  Since:
    2.0

### containsIgnoreCase

    public static boolean containsIgnoreCase(String str,
                                             String searchStr)

  Checks if String contains a search String irrespective of case, handling `null`. This method uses `contains(String, String)`.

  A `null` String will return `false`.

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

  Parameters:
    `str` - the String to check, may be null
    `searchStr` - the String to find, may be null
  Returns:
    true if the String contains the search String irrespective of case or false if not or `null` string input

### indexOfAny

    public static int indexOfAny(String str,
                                 char[] searchChars)

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

  A `null` String will return `-1`. A `null` or zero length search array will return `-1`.

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

  Parameters:
    `str` - the String to check, may be null
    `searchChars` - the chars to search for, may be null
  Returns:
    the index of any of the chars, -1 if no match or null input
  Since:
    2.0

### indexOfAny

    public static int indexOfAny(String str,
                                 String searchChars)

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

  A `null` String will return `-1`. A `null` search string will return `-1`.

       StringUtils.indexOfAny(null, *)            = -1
       StringUtils.indexOfAny("", *)              = -1
       StringUtils.indexOfAny(*, null)            = -1
       StringUtils.indexOfAny(*, "")              = -1
       StringUtils.indexOfAny("zzabyycdxx", "za") = 0
       StringUtils.indexOfAny("zzabyycdxx", "by") = 3
       StringUtils.indexOfAny("aba","z")          = -1

  Parameters:
    `str` - the String to check, may be null
    `searchChars` - the chars to search for, may be null
  Returns:
    the index of any of the chars, -1 if no match or null input
  Since:
    2.0

### indexOfAnyBut

    public static int indexOfAnyBut(String str,
                                    char[] searchChars)

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

  A `null` String will return `-1`. A `null` or zero length search array will return `-1`.

       StringUtils.indexOfAnyBut(null, *)           = -1
       StringUtils.indexOfAnyBut("", *)             = -1
       StringUtils.indexOfAnyBut(*, null)           = -1
       StringUtils.indexOfAnyBut(*, [])             = -1
       StringUtils.indexOfAnyBut("zzabyycdxx",'za') = 3
       StringUtils.indexOfAnyBut("zzabyycdxx", '')  = 0
       StringUtils.indexOfAnyBut("aba", 'ab')       = -1

  Parameters:
    `str` - the String to check, may be null
    `searchChars` - the chars to search for, may be null
  Returns:
    the index of any of the chars, -1 if no match or null input
  Since:
    2.0

### indexOfAnyBut

    public static int indexOfAnyBut(String str,
                                    String searchChars)

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

  A `null` String will return `-1`. A `null` search string will return `-1`.

       StringUtils.indexOfAnyBut(null, *)            = -1
       StringUtils.indexOfAnyBut("", *)              = -1
       StringUtils.indexOfAnyBut(*, null)            = -1
       StringUtils.indexOfAnyBut(*, "")              = -1
       StringUtils.indexOfAnyBut("zzabyycdxx", "za") = 3
       StringUtils.indexOfAnyBut("zzabyycdxx", "")   = 0
       StringUtils.indexOfAnyBut("aba","ab")         = -1

  Parameters:
    `str` - the String to check, may be null
    `searchChars` - the chars to search for, may be null
  Returns:
    the index of any of the chars, -1 if no match or null input
  Since:
    2.0

### containsOnly

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

  Checks if the String contains only certain characters.

  A `null` String will return `false`. A `null` valid character array will return `false`. An empty String ("") always returns `true`.

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

  Parameters:
    `str` - the String to check, may be null
    `valid` - an array of valid chars, may be null
  Returns:
    true if it only contains valid chars and is non-null

### containsOnly

    public static boolean containsOnly(String str,
                                       String validChars)

  Checks if the String contains only certain characters.

  A `null` String will return `false`. A `null` valid character String will return `false`. An empty String ("") always returns `true`.

       StringUtils.containsOnly(null, *)       = false
       StringUtils.containsOnly(*, null)       = false
       StringUtils.containsOnly("", *)         = true
       StringUtils.containsOnly("ab", "")      = false
       StringUtils.containsOnly("abab", "abc") = true
       StringUtils.containsOnly("ab1", "abc")  = false
       StringUtils.containsOnly("abz", "abc")  = false

  Parameters:
    `str` - the String to check, may be null
    `validChars` - a String of valid chars, may be null
  Returns:
    true if it only contains valid chars and is non-null
  Since:
    2.0

### containsNone

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

  Checks that the String does not contain certain characters.

  A `null` String will return `true`. A `null` invalid character array will return `true`. An empty String ("") always returns true.

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

  Parameters:
    `str` - the String to check, may be null
    `invalidChars` - an array of invalid chars, may be null
  Returns:
    true if it contains none of the invalid chars, or is null
  Since:
    2.0

### containsNone

    public static boolean containsNone(String str,
                                       String invalidChars)

  Checks that the String does not contain certain characters.

  A `null` String will return `true`. A `null` invalid character array will return `true`. An empty String ("") always returns true.

       StringUtils.containsNone(null, *)       = true
       StringUtils.containsNone(*, null)       = true
       StringUtils.containsNone("", *)         = true
       StringUtils.containsNone("ab", "")      = true
       StringUtils.containsNone("abab", "xyz") = true
       StringUtils.containsNone("ab1", "xyz")  = true
       StringUtils.containsNone("abz", "xyz")  = false

  Parameters:
    `str` - the String to check, may be null
    `invalidChars` - a String of invalid chars, may be null
  Returns:
    true if it contains none of the invalid chars, or is null
  Since:
    2.0

### indexOfAny

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

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

  A `null` String will return `-1`. A `null` or zero length search array will return `-1`. A `null` search array entry will be ignored, but a search array containing "" will return `0` if `str` is not null. This method uses `String.indexOf(String)`.

       StringUtils.indexOfAny(null, *)                     = -1
       StringUtils.indexOfAny(*, null)                     = -1
       StringUtils.indexOfAny(*, [])                       = -1
       StringUtils.indexOfAny("zzabyycdxx", ["ab","cd"])   = 2
       StringUtils.indexOfAny("zzabyycdxx", ["cd","ab"])   = 2
       StringUtils.indexOfAny("zzabyycdxx", ["mn","op"])   = -1
       StringUtils.indexOfAny("zzabyycdxx", ["zab","aby"]) = 1
       StringUtils.indexOfAny("zzabyycdxx", [""])          = 0
       StringUtils.indexOfAny("", [""])                    = 0
       StringUtils.indexOfAny("", ["a"])                   = -1

  Parameters:
    `str` - the String to check, may be null
    `searchStrs` - the Strings to search for, may be null
  Returns:
    the first index of any of the searchStrs in str, -1 if no match

### lastIndexOfAny

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

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

  A `null` String will return `-1`. A `null` search array will return `-1`. A `null` or zero length search array entry will be ignored, but a search array containing "" will return the length of `str` if `str` is not null. This method uses `String.indexOf(String)`

       StringUtils.lastIndexOfAny(null, *)                   = -1
       StringUtils.lastIndexOfAny(*, null)                   = -1
       StringUtils.lastIndexOfAny(*, [])                     = -1
       StringUtils.lastIndexOfAny(*, [null])                 = -1
       StringUtils.lastIndexOfAny("zzabyycdxx", ["ab","cd"]) = 6
       StringUtils.lastIndexOfAny("zzabyycdxx", ["cd","ab"]) = 6
       StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1
       StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1
       StringUtils.lastIndexOfAny("zzabyycdxx", ["mn",""])   = 10

  Parameters:
    `str` - the String to check, may be null
    `searchStrs` - the Strings to search for, may be null
  Returns:
    the last index of any of the Strings, -1 if no match

### substring

    public static String substring(String str,
                                   int start)

  Gets a substring from the specified String avoiding exceptions.

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

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

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

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

### substring

    public static String substring(String str,
                                   int start,
                                   int end)

  Gets a substring from the specified String avoiding exceptions.

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

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

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

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

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

### left

    public static String left(String str,
                              int len)

  Gets the leftmost `len` characters of a String.

  If `len` characters are not available, or the String is `null`, the String will be returned without an exception. An exception is thrown if len is negative.

       StringUtils.left(null, *)    = null
       StringUtils.left(*, -ve)     = ""
       StringUtils.left("", *)      = ""
       StringUtils.left("abc", 0)   = ""
       StringUtils.left("abc", 2)   = "ab"
       StringUtils.left("abc", 4)   = "abc"

  Parameters:
    `str` - the String to get the leftmost characters from, may be null
    `len` - the length of the required String, must be zero or positive
  Returns:
    the leftmost characters, `null` if null String input

### right

    public static String right(String str,
                               int len)

  Gets the rightmost `len` characters of a String.

  If `len` characters are not available, or the String is `null`, the String will be returned without an an exception. An exception is thrown if len is negative.

       StringUtils.right(null, *)    = null
       StringUtils.right(*, -ve)     = ""
       StringUtils.right("", *)      = ""
       StringUtils.right("abc", 0)   = ""
       StringUtils.right("abc", 2)   = "bc"
       StringUtils.right("abc", 4)   = "abc"

  Parameters:
    `str` - the String to get the rightmost characters from, may be null
    `len` - the length of the required String, must be zero or positive
  Returns:
    the rightmost characters, `null` if null String input

### mid

    public static String mid(String str,
                             int pos,
                             int len)

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

  If `len` characters are not available, the remainder of the String will be returned without an exception. If the String is `null`, `null` will be returned. An exception is thrown if len is negative.

       StringUtils.mid(null, *, *)    = null
       StringUtils.mid(*, *, -ve)     = ""
       StringUtils.mid("", 0, *)      = ""
       StringUtils.mid("abc", 0, 2)   = "ab"
       StringUtils.mid("abc", 0, 4)   = "abc"
       StringUtils.mid("abc", 2, 4)   = "c"
       StringUtils.mid("abc", 4, 2)   = ""
       StringUtils.mid("abc", -2, 2)  = "ab"

  Parameters:
    `str` - the String to get the characters from, may be null
    `pos` - the position to start from, negative treated as zero
    `len` - the length of the required String, must be zero or positive
  Returns:
    the middle characters, `null` if null String input

### substringBefore

    public static String substringBefore(String str,
                                         String separator)

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

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

       StringUtils.substringBefore(null, *)      = null
       StringUtils.substringBefore("", *)        = ""
       StringUtils.substringBefore("abc", "a")   = ""
       StringUtils.substringBefore("abcba", "b") = "a"
       StringUtils.substringBefore("abc", "c")   = "ab"
       StringUtils.substringBefore("abc", "d")   = "abc"
       StringUtils.substringBefore("abc", "")    = ""
       StringUtils.substringBefore("abc", null)  = "abc"

  Parameters:
    `str` - the String to get a substring from, may be null
    `separator` - the String to search for, may be null
  Returns:
    the substring before the first occurrence of the separator, `null` if null String input
  Since:
    2.0

### substringAfter

    public static String substringAfter(String str,
                                        String separator)

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

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

       StringUtils.substringAfter(null, *)      = null
       StringUtils.substringAfter("", *)        = ""
       StringUtils.substringAfter(*, null)      = ""
       StringUtils.substringAfter("abc", "a")   = "bc"
       StringUtils.substringAfter("abcba", "b") = "cba"
       StringUtils.substringAfter("abc", "c")   = ""
       StringUtils.substringAfter("abc", "d")   = ""
       StringUtils.substringAfter("abc", "")    = "abc"

  Parameters:
    `str` - the String to get a substring from, may be null
    `separator` - the String to search for, may be null
  Returns:
    the substring after the first occurrence of the separator, `null` if null String input
  Since:
    2.0

### substringBeforeLast

    public static String substringBeforeLast(String str,
                                             String separator)

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

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

       StringUtils.substringBeforeLast(null, *)      = null
       StringUtils.substringBeforeLast("", *)        = ""
       StringUtils.substringBeforeLast("abcba", "b") = "abc"
       StringUtils.substringBeforeLast("abc", "c")   = "ab"
       StringUtils.substringBeforeLast("a", "a")     = ""
       StringUtils.substringBeforeLast("a", "z")     = "a"
       StringUtils.substringBeforeLast("a", null)    = "a"
       StringUtils.substringBeforeLast("a", "")      = "a"

  Parameters:
    `str` - the String to get a substring from, may be null
    `separator` - the String to search for, may be null
  Returns:
    the substring before the last occurrence of the separator, `null` if null String input
  Since:
    2.0

### substringAfterLast

    public static String substringAfterLast(String str,
                                            String separator)

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

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

       StringUtils.substringAfterLast(null, *)      = null
       StringUtils.substringAfterLast("", *)        = ""
       StringUtils.substringAfterLast(*, "")        = ""
       StringUtils.substringAfterLast(*, null)      = ""
       StringUtils.substringAfterLast("abc", "a")   = "bc"
       StringUtils.substringAfterLast("abcba", "b") = "a"
       StringUtils.substringAfterLast("abc", "c")   = ""
       StringUtils.substringAfterLast("a", "a")     = ""
       StringUtils.substringAfterLast("a", "z")     = ""

  Parameters:
    `str` - the String to get a substring from, may be null
    `separator` - the String to search for, may be null
  Returns:
    the substring after the last occurrence of the separator, `null` if null String input
  Since:
    2.0

### substringBetween

    public static String substringBetween(String str,
                                          String tag)

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

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

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

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

### substringBetween

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

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

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

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

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

### substringsBetween

    public static String[] substringsBetween(String str,
                                             String open,
                                             String close)

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

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

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

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

### getNestedString

    public static String getNestedString(String str,
                                         String tag)

  Deprecated. Use the better named `substringBetween(String, String)`. Method will be removed in Commons Lang 3.0.

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

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

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

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

### getNestedString

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

  Deprecated. Use the better named `substringBetween(String, String, String)`. Method will be removed in Commons Lang 3.0.

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

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

       StringUtils.getNestedString(null, *, *)          = null
       StringUtils.getNestedString("", "", "")          = ""
       StringUtils.getNestedString("", "", "tag")       = null
       StringUtils.getNestedString("", "tag", "tag")    = null
       StringUtils.getNestedString("yabcz", null, null) = null
       StringUtils.getNestedString("yabcz", "", "")     = ""
       StringUtils.getNestedString("yabcz", "y", "z")   = "abc"
       StringUtils.getNestedString("yabczyabcz", "y", "z")   = "abc"

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

### split

    public static String[] split(String str)

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

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

  A `null` input String returns `null`.

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

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

### split

    public static String[] split(String str,
                                 char separatorChar)

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

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

  A `null` input String returns `null`.

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

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

### split

    public static String[] split(String str,
                                 String separatorChars)

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

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

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

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

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

### split

    public static String[] split(String str,
                                 String separatorChars,
                                 int max)

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

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

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

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

       StringUtils.split(null, *, *)            = null
       StringUtils.split("", *, *)              = []
       StringUtils.split("ab de fg", null, 0)   = ["ab", "cd", "ef"]
       StringUtils.split("ab   de fg", null, 0) = ["ab", "cd", "ef"]
       StringUtils.split("ab:cd:ef", ":", 0)    = ["ab", "cd", "ef"]
       StringUtils.split("ab:cd:ef", ":", 2)    = ["ab", "cd:ef"]

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

### splitByWholeSeparator

    public static String[] splitByWholeSeparator(String str,
                                                 String separator)

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

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

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

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

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

### splitByWholeSeparator

    public static String[] splitByWholeSeparator(String str,
                                                 String separator,
                                                 int max)

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

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

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

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

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

### splitPreserveAllTokens

    public static String[] splitPreserveAllTokens(String str)

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

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

  A `null` input String returns `null`.

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

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

### splitPreserveAllTokens

    public static String[] splitPreserveAllTokens(String str,
                                                  char separatorChar)

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

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

  A `null` input String returns `null`.

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

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

### splitPreserveAllTokens

    public static String[] splitPreserveAllTokens(String str,
                                                  String separatorChars)

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

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

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

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

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

### splitPreserveAllTokens

    public static String[] splitPreserveAllTokens(String str,
                                                  String separatorChars,
                                                  int max)

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

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

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

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

       StringUtils.splitPreserveAllTokens(null, *, *)            = null
       StringUtils.splitPreserveAllTokens("", *, *)              = []
       StringUtils.splitPreserveAllTokens("ab de fg", null, 0)   = ["ab", "cd", "ef"]
       StringUtils.splitPreserveAllTokens("ab   de fg", null, 0) = ["ab", "cd", "ef"]
       StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 0)    = ["ab", "cd", "ef"]
       StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 2)    = ["ab", "cd:ef"]
       StringUtils.splitPreserveAllTokens("ab   de fg", null, 2) = ["ab", "  de fg"]
       StringUtils.splitPreserveAllTokens("ab   de fg", null, 3) = ["ab", "", " de fg"]
       StringUtils.splitPreserveAllTokens("ab   de fg", null, 4) = ["ab", "", "", "de fg"]

  Parameters:
    `str` - the String to parse, may be `null`
    `separatorChars` - the characters used as the delimiters, `null` splits on whitespace
    `max` - the maximum number of elements to include in the array. A zero or negative value implies no limit
  Returns:
    an array of parsed Strings, `null` if null String input
  Since:
    2.1

### concatenate

    public static String concatenate(Object[] array)

  Deprecated. Use the better named `join(Object[])` instead. Method will be removed in Commons Lang 3.0.

  Concatenates elements of an array into a single String. Null objects or empty strings within the array are represented by empty strings.

       StringUtils.concatenate(null)            = null
       StringUtils.concatenate([])              = ""
       StringUtils.concatenate([null])          = ""
       StringUtils.concatenate(["a", "b", "c"]) = "abc"
       StringUtils.concatenate([null, "", "a"]) = "a"

  Parameters:
    `array` - the array of values to concatenate, may be null
  Returns:
    the concatenated String, `null` if null array input

### join

    public static String join(Object[] array)

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

  No separator is added to the joined String. Null objects or empty strings within the array are represented by empty strings.

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

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

### join

    public static String join(Object[] array,
                              char separator)

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

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

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

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

### join

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

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

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

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

  Parameters:
    `array` - the array of values to join together, may be null
    `separator` - the separator character to use
    `startIndex` - the first index to start joining from. It is an error to pass in an end index past the end of the array
    `endIndex` - the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array
  Returns:
    the joined String, `null` if null array input
  Since:
    2.0

### join

    public static String join(Object[] array,
                              String separator)

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

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

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

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

### join

    public static String join(Object[] array,
                              String separator,
                              int startIndex,
                              int endIndex)

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

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

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

  Parameters:
    `array` - the array of values to join together, may be null
    `separator` - the separator character to use, null treated as ""
    `startIndex` - the first index to start joining from. It is an error to pass in an end index past the end of the array
    `endIndex` - the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array
  Returns:
    the joined String, `null` if null array input

### join

    public static String join(Iterator iterator,
                              char separator)

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

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

  See the examples here: `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 String join(Iterator iterator,
                              String separator)

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

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

  See the examples here: `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 String join(Collection collection,
                              char separator)

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

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

  See the examples here: `join(Object[],char)`.

  Parameters:
    `collection` - the `Collection` of values to join together, may be null
    `separator` - the separator character to use
  Returns:
    the joined String, `null` if null iterator input
  Since:
    2.3

### join

    public static String join(Collection collection,
                              String separator)

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

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

  See the examples here: `join(Object[],String)`.

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

### deleteSpaces

    public static String deleteSpaces(String str)

  Deprecated. Use the better localized `deleteWhitespace(String)`. Method will be removed in Commons Lang 3.0.

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

  This is the only StringUtils method that uses the `isSpace` definition. You are advised to use `deleteWhitespace(String)` instead as whitespace is much better localized.

       StringUtils.deleteSpaces(null)           = null
       StringUtils.deleteSpaces("")             = ""
       StringUtils.deleteSpaces("abc")          = "abc"
       StringUtils.deleteSpaces(" \t  abc \n ") = "abc"
       StringUtils.deleteSpaces("ab  c")        = "abc"
       StringUtils.deleteSpaces("a\nb\tc     ") = "abc"

  Spaces are defined as `{' ', '\t', '\r', '\n', '\b'}` in line with the deprecated `isSpace` method.

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

### deleteWhitespace

    public static String deleteWhitespace(String str)

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

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

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

### removeStart

    public static String removeStart(String str,
                                     String remove)

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

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

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

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

### removeEnd

    public static String removeEnd(String str,
                                   String remove)

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

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

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

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

### remove

    public static String remove(String str,
                                String remove)

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

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

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

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

### remove

    public static String remove(String str,
                                char remove)

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

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

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

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

### replaceOnce

    public static String replaceOnce(String text,
                                     String repl,
                                     String with)

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

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

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

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

### replace

    public static String replace(String text,
                                 String repl,
                                 String with)

  Replaces all occurrences of a String within another String.

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

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

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

### replace

    public static String replace(String text,
                                 String repl,
                                 String with,
                                 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
    `repl` - the String to search for, may be null
    `with` - the String to replace with, may be null
    `max` - maximum number of values to replace, or `-1` if no maximum
  Returns:
    the text with any replacements processed, `null` if null String input

### replaceChars

    public static String replaceChars(String str,
                                      char searchChar,
                                      char replaceChar)

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

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

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

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

### replaceChars

    public static String replaceChars(String str,
                                      String searchChars,
                                      String replaceChars)

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

  For example:
  `replaceChars("hello", "ho", "jy") = jelly`.

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

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

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

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

### overlayString

    public static String overlayString(String text,
                                       String overlay,
                                       int start,
                                       int end)

  Deprecated. Use better named `overlay(String, String, int, int)` instead. Method will be removed in Commons Lang 3.0.

  Overlays part of a String with another String.

       StringUtils.overlayString(null, *, *, *)           = NullPointerException
       StringUtils.overlayString(*, null, *, *)           = NullPointerException
       StringUtils.overlayString("", "abc", 0, 0)         = "abc"
       StringUtils.overlayString("abcdef", null, 2, 4)    = "abef"
       StringUtils.overlayString("abcdef", "", 2, 4)      = "abef"
       StringUtils.overlayString("abcdef", "zzzz", 2, 4)  = "abzzzzef"
       StringUtils.overlayString("abcdef", "zzzz", 4, 2)  = "abcdzzzzcdef"
       StringUtils.overlayString("abcdef", "zzzz", -1, 4) = IndexOutOfBoundsException
       StringUtils.overlayString("abcdef", "zzzz", 2, 8)  = IndexOutOfBoundsException

  Parameters:
    `text` - the String to do overlaying in, may be null
    `overlay` - the String to overlay, may be null
    `start` - the position to start overlaying at, must be valid
    `end` - the position to stop overlaying before, must be valid
  Returns:
    overlayed String, `null` if null String input
  Throws:
    `NullPointerException` - if text or overlay is null
    `IndexOutOfBoundsException` - if either position is invalid

### overlay

    public static String overlay(String str,
                                 String overlay,
                                 int start,
                                 int end)

  Overlays part of a String with another String.

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

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

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

### chomp

    public static String chomp(String str)

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

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

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

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

### chomp

    public static String chomp(String str,
                               String separator)

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

  NOTE: This method changed in version 2.0. It now more closely matches Perl chomp. For the previous behavior, use `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

### chompLast

    public static String chompLast(String str)

  Deprecated. Use `chomp(String)` instead. Method will be removed in Commons Lang 3.0.

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

  Parameters:
    `str` - the String to chomp from, must not be null
  Returns:
    String without chomped ending
  Throws:
    `NullPointerException` - if str is `null`

### chompLast

    public static String chompLast(String str,
                                   String sep)

  Deprecated. Use `chomp(String,String)` instead. Method will be removed in Commons Lang 3.0.

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

  Parameters:
    `str` - the String to chomp from, must not be null
    `sep` - the String to chomp, must not be null
  Returns:
    String without chomped ending
  Throws:
    `NullPointerException` - if str or sep is `null`

### getChomp

    public static String getChomp(String str,
                                  String sep)

  Deprecated. Use `substringAfterLast(String, String)` instead (although this doesn't include the separator) Method will be removed in Commons Lang 3.0.

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

  Parameters:
    `str` - the String to chomp from, must not be null
    `sep` - the String to chomp, must not be null
  Returns:
    String chomped
  Throws:
    `NullPointerException` - if str or sep is `null`

### prechomp

    public static String prechomp(String str,
                                  String sep)

  Deprecated. Use `substringAfter(String,String)` instead. Method will be removed in Commons Lang 3.0.

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

  Parameters:
    `str` - the String to chomp from, must not be null
    `sep` - the String to chomp, must not be null
  Returns:
    String without chomped beginning
  Throws:
    `NullPointerException` - if str or sep is `null`

### getPrechomp

    public static String getPrechomp(String str,
                                     String sep)

  Deprecated. Use `substringBefore(String,String)` instead (although this doesn't include the separator). Method will be removed in Commons Lang 3.0.

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

  Parameters:
    `str` - the String to chomp from, must not be null
    `sep` - the String to chomp, must not be null
  Returns:
    String prechomped
  Throws:
    `NullPointerException` - if str or sep is `null`

### chop

    public static String chop(String str)

  Remove the last character from a String.

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

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

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

### chopNewline

    public static String chopNewline(String str)

  Deprecated. Use `chomp(String)` instead. Method will be removed in Commons Lang 3.0.

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

  Parameters:
    `str` - the String to chop a newline from, must not be null
  Returns:
    String without newline
  Throws:
    `NullPointerException` - if str is `null`

### escape

    public static String escape(String str)

  Deprecated. Use `StringEscapeUtils.escapeJava(String)` This method will be removed in Commons Lang 3.0

  Escapes any values it finds into their String form.

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

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

  Parameters:
    `str` - String to escape values in
  Returns:
    String with escaped values
  Throws:
    `NullPointerException` - if str is `null`
  See Also:
    `StringEscapeUtils.escapeJava(java.lang.String)`

### repeat

    public static String repeat(String str,
                                int repeat)

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

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

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

### rightPad

    public static String rightPad(String str,
                                  int size)

  Right pad a String with spaces (' ').

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

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

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

### rightPad

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

  Right pad a String with a specified character.

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

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

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

### rightPad

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

  Right pad a String with a specified String.

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

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

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

### leftPad

    public static String leftPad(String str,
                                 int size)

  Left pad a String with spaces (' ').

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

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

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

### leftPad

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

  Left pad a String with a specified character.

  Pad to a size of `size`.

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

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

### leftPad

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

  Left pad a String with a specified String.

  Pad to a size of `size`.

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

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

### center

    public static String center(String str,
                                int size)

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

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

  Equivalent to `center(str, size, " ")`.

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

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

### center

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

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

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

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

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

### center

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

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

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

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

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

### upperCase

    public static String upperCase(String str)

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

  A `null` input String returns `null`.

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

  Parameters:
    `str` - the String to upper case, may be null
  Returns:
    the upper cased String, `null` if null String input

### lowerCase

    public static String lowerCase(String str)

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

  A `null` input String returns `null`.

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

  Parameters:
    `str` - the String to lower case, may be null
  Returns:
    the lower cased String, `null` if null String input

### capitalize

    public static String capitalize(String str)

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

  For a word based algorithm, see `WordUtils.capitalize(String)`. A `null` input String returns `null`.

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

  Parameters:
    `str` - the String to capitalize, may be null
  Returns:
    the capitalized String, `null` if null String input
  Since:
    2.0
  See Also:
    `WordUtils.capitalize(String)`, `uncapitalize(String)`

### capitalise

    public static String capitalise(String str)

  Deprecated. Use the standardly named `capitalize(String)`. Method will be removed in Commons Lang 3.0.

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

  Parameters:
    `str` - the String to capitalize, may be null
  Returns:
    the capitalized String, `null` if null String input

### uncapitalize

    public static String uncapitalize(String str)

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

  For a word based algorithm, see `WordUtils.uncapitalize(String)`. A `null` input String returns `null`.

       StringUtils.uncapitalize(null)  = null
       StringUtils.uncapitalize("")    = ""
       StringUtils.uncapitalize("Cat") = "cat"
       StringUtils.uncapitalize("CAT") = "cAT"

  Parameters:
    `str` - the String to uncapitalize, may be null
  Returns:
    the uncapitalized String, `null` if null String input
  Since:
    2.0
  See Also:
    `WordUtils.uncapitalize(String)`, `capitalize(String)`

### uncapitalise

    public static String uncapitalise(String str)

  Deprecated. Use the standardly named `uncapitalize(String)`. Method will be removed in Commons Lang 3.0.

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

  Parameters:
    `str` - the String to uncapitalize, may be null
  Returns:
    the uncapitalized String, `null` if null String input

### swapCase

    public static String swapCase(String str)

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

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

  For a word based algorithm, see `WordUtils.swapCase(String)`. A `null` input String returns `null`.

       StringUtils.swapCase(null)                 = null
       StringUtils.swapCase("")                   = ""
       StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"

  NOTE: This method changed in Lang version 2.0. It no longer performs a word based algorithm. If you only use ASCII, you will notice no change. That functionality is available in WordUtils.

  Parameters:
    `str` - the String to swap case, may be null
  Returns:
    the changed String, `null` if null String input

### capitaliseAllWords

    public static String capitaliseAllWords(String str)

  Deprecated. Use the relocated `WordUtils.capitalize(String)`. Method will be removed in Commons Lang 3.0.

  Capitalizes all the whitespace separated words in a String. Only the first letter of each word is changed.

  Whitespace is defined by `Character.isWhitespace(char)`. A `null` input String returns `null`.

  Parameters:
    `str` - the String to capitalize, may be null
  Returns:
    capitalized String, `null` if null String input

### countMatches

    public static int countMatches(String str,
                                   String sub)

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

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

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

  Parameters:
    `str` - the String to check, may be null
    `sub` - the substring to count, may be null
  Returns:
    the number of occurrences, 0 if either String is `null`

### isAlpha

    public static boolean isAlpha(String str)

  Checks if the String contains only unicode letters.

  `null` will return `false`. An empty String ("") will return `true`.

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if only contains letters, and is non-null

### isAlphaSpace

    public static boolean isAlphaSpace(String str)

  Checks if the String contains only unicode letters and space (' ').

  `null` will return `false` An empty String ("") will return `true`.

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if only contains letters and space, and is non-null

### isAlphanumeric

    public static boolean isAlphanumeric(String str)

  Checks if the String contains only unicode letters or digits.

  `null` will return `false`. An empty String ("") will return `true`.

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if only contains letters or digits, and is non-null

### isAlphanumericSpace

    public static boolean isAlphanumericSpace(String str)

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

  `null` will return `false`. An empty String ("") will return `true`.

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if only contains letters, digits or space, and is non-null

### isAsciiPrintable

    public static boolean isAsciiPrintable(String str)

  Checks if the string contains only ASCII printable characters.

  `null` will return `false`. An empty String ("") will return `true`.

       StringUtils.isAsciiPrintable(null)     = false
       StringUtils.isAsciiPrintable("")       = true
       StringUtils.isAsciiPrintable(" ")      = true
       StringUtils.isAsciiPrintable("Ceki")   = true
       StringUtils.isAsciiPrintable("ab2c")   = true
       StringUtils.isAsciiPrintable("!ab-c~") = true
       StringUtils.isAsciiPrintable(" ") = true
       StringUtils.isAsciiPrintable("!") = true
       StringUtils.isAsciiPrintable("~") = true
       StringUtils.isAsciiPrintable("") = false
       StringUtils.isAsciiPrintable("Ceki GŸlcŸ") = false

  Parameters:
    `str` - the string to check, may be null
  Returns:
    `true` if every character is in the range 32 thru 126
  Since:
    2.1

### isNumeric

    public static boolean isNumeric(String str)

  Checks if the String contains only unicode digits. A decimal point is not a unicode digit and returns false.

  `null` will return `false`. An empty String ("") will return `true`.

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if only contains digits, and is non-null

### isNumericSpace

    public static boolean isNumericSpace(String str)

  Checks if the String contains only unicode digits or space (`' '`). A decimal point is not a unicode digit and returns false.

  `null` will return `false`. An empty String ("") will return `true`.

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if only contains digits or space, and is non-null

### isWhitespace

    public static boolean isWhitespace(String str)

  Checks if the String contains only whitespace.

  `null` will return `false`. An empty String ("") will return `true`.

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

  Parameters:
    `str` - the String to check, may be null
  Returns:
    `true` if only contains whitespace, and is non-null
  Since:
    2.0

### defaultString

    public static String defaultString(String str)

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

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

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

### defaultString

    public static String defaultString(String str,
                                       String defaultStr)

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

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

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

### defaultIfEmpty

    public static String defaultIfEmpty(String str,
                                        String defaultStr)

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

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

  Parameters:
    `str` - the String to check, may be null
    `defaultStr` - the default String to return if the input is empty ("") or `null`, may be null
  Returns:
    the passed in String, or the default
  See Also:
    `defaultString(String, String)`

### reverse

    public static String reverse(String str)

  Reverses a String as per `StringBuffer.reverse()`.

  A `null` String returns `null`.

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

  Parameters:
    `str` - the String to reverse, may be null
  Returns:
    the reversed String, `null` if null String input

### reverseDelimited

    public static String reverseDelimited(String str,
                                          char separatorChar)

  Reverses a String that is delimited by a specific character.

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

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

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

### reverseDelimitedString

    public static String reverseDelimitedString(String str,
                                                String separatorChars)

  Deprecated. Use `reverseDelimited(String, char)` instead. This method is broken as the join doesn't know which char to use. Method will be removed in Commons Lang 3.0.

  Reverses a String that is delimited by a specific character.

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

       StringUtils.reverseDelimitedString(null, *)       = null
       StringUtils.reverseDelimitedString("",*)          = ""
       StringUtils.reverseDelimitedString("a.b.c", null) = "a.b.c"
       StringUtils.reverseDelimitedString("a.b.c", ".")  = "c.b.a"

  Parameters:
    `str` - the String to reverse, may be null
    `separatorChars` - the separator characters to use, null treated as whitespace
  Returns:
    the reversed String, `null` if null String input

### abbreviate

    public static String abbreviate(String str,
                                    int maxWidth)

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

  Specifically:

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

       StringUtils.abbreviate(null, *)      = null
       StringUtils.abbreviate("", 4)        = ""
       StringUtils.abbreviate("abcdefg", 6) = "abc..."
       StringUtils.abbreviate("abcdefg", 7) = "abcdefg"
       StringUtils.abbreviate("abcdefg", 8) = "abcdefg"
       StringUtils.abbreviate("abcdefg", 4) = "a..."
       StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException

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

### abbreviate

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

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

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

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

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

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

### difference

    public static String difference(String str1,
                                    String str2)

  Compares two Strings, and returns the portion where they differ. (More precisely, return the remainder of the second String, starting from where it's different from the first.)

  For example, `difference("i am a machine", "i am a robot") -> "robot"`.

       StringUtils.difference(null, null) = null
       StringUtils.difference("", "") = ""
       StringUtils.difference("", "abc") = "abc"
       StringUtils.difference("abc", "") = ""
       StringUtils.difference("abc", "abc") = ""
       StringUtils.difference("ab", "abxyz") = "xyz"
       StringUtils.difference("abcde", "abxyz") = "xyz"
       StringUtils.difference("abcde", "xyz") = "xyz"

  Parameters:
    `str1` - the first String, may be null
    `str2` - the second String, may be null
  Returns:
    the portion of str2 where it differs from str1; returns the empty String if they are equal
  Since:
    2.0

### indexOfDifference

    public static int indexOfDifference(String str1,
                                        String str2)

  Compares two Strings, and returns the index at which the Strings begin to differ.

  For example, `indexOfDifference("i am a machine", "i am a robot") -> 7`

       StringUtils.indexOfDifference(null, null) = -1
       StringUtils.indexOfDifference("", "") = -1
       StringUtils.indexOfDifference("", "abc") = 0
       StringUtils.indexOfDifference("abc", "") = 0
       StringUtils.indexOfDifference("abc", "abc") = -1
       StringUtils.indexOfDifference("ab", "abxyz") = 2
       StringUtils.indexOfDifference("abcde", "abxyz") = 2
       StringUtils.indexOfDifference("abcde", "xyz") = 0

  Parameters:
    `str1` - the first String, may be null
    `str2` - the second String, may be null
  Returns:
    the index where str2 and str1 begin to differ; -1 if they are equal
  Since:
    2.0

### getLevenshteinDistance

    public static int getLevenshteinDistance(String s,
                                             String t)

  Find the Levenshtein distance between two Strings.

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

  The previous implementation of the Levenshtein distance algorithm was from http://www.merriampark.com/ld.htm

  Chas Emerick has written an implementation in Java, which avoids an OutOfMemoryError which can occur when my Java implementation is used with very large strings.
  This implementation of the Levenshtein distance algorithm is from http://www.merriampark.com/ldjava.htm

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

  Parameters:
    `s` - the first String, must not be null
    `t` - the second String, must not be null
  Returns:
    result distance
  Throws:
    `IllegalArgumentException` - if either String input `null`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2005 - Apache Software Foundation