org.codehaus.plexus.util

## Class StringUtils

- java.lang.Object
- - org.codehaus.plexus.util.StringUtils

-     public class StringUtils
      extends java.lang.Object

  Common `String` manipulation routines.

  Originally from Turbine and the GenerationJavaCore library.

  Since:
    1.0
  Version:
    $Id: StringUtils.java 8001 2009-01-03 13:17:09Z vsiveton $
  Author:
    Jon S. Stevens, Daniel Rall, Greg Coladonato, Henri Yandell, Ed Korthof, Rand McNeely, Stephen Colebourne, Fredrik Westermarck, Holger Krauth, Alexander Day Chaffee, Vincent Siveton

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `abbreviate(java.lang.String s, int maxWidth)` Turn "Now is the time for all good men" into "Now is the time for..."
    `static java.lang.String` | `abbreviate(java.lang.String s, int offset, int maxWidth)` Turn "Now is the time for all good men" into "...is the time for..."
    `static java.lang.String` | `addAndDeHump(java.lang.String view)`
    `static java.lang.String` | `capitalise(java.lang.String str)` Capitalise a String.
    `static java.lang.String` | `capitaliseAllWords(java.lang.String str)` Capitalise all the words in a String.
    `static java.lang.String` | `capitalizeFirstLetter(java.lang.String data)`
    `static java.lang.String` | `center(java.lang.String str, int size)` Center a String in a larger String of size `n`.
    `static java.lang.String` | `center(java.lang.String str, int size, java.lang.String delim)` Center a String in a larger String of size `n`.
    `static java.lang.String` | `chomp(java.lang.String str)` Remove the last newline, and everything after it from a String.
    `static java.lang.String` | `chomp(java.lang.String str, java.lang.String sep)` Remove the last value of a supplied String, and everything after it from a String.
    `static java.lang.String` | `chompLast(java.lang.String str)` Remove a newline if and only if it is at the end of the supplied String.
    `static java.lang.String` | `chompLast(java.lang.String str, java.lang.String sep)` Remove a value if and only if the String ends with that value.
    `static java.lang.String` | `chop(java.lang.String str)` Remove the last character from a String.
    `static java.lang.String` | `chopNewline(java.lang.String str)` Remove `\n` from end of a String if it's there.
    `static java.lang.String` | `clean(java.lang.String str)` Removes control characters, including whitespace, from both ends of this String, handling `null` by returning an empty String.
    `static java.lang.String` | `concatenate(java.lang.Object[] array)` Concatenates elements of an array into a single String.
    `static boolean` | `contains(java.lang.String str, char searchChar)` Checks if String contains a search character, handling `null`.
    `static boolean` | `contains(java.lang.String str, java.lang.String searchStr)` Checks if String contains a search String, handling `null`.
    `static int` | `countMatches(java.lang.String str, java.lang.String sub)` How many times is the substring in the larger String.
    `static java.lang.String` | `defaultString(java.lang.Object obj)` Returns either the passed in `Object` as a String, or, if the `Object` is `null`, an empty String.
    `static java.lang.String` | `defaultString(java.lang.Object obj, java.lang.String defaultString)` Returns either the passed in `Object` as a String, or, if the `Object` is `null`, a passed in default String.
    `static java.lang.String` | `deleteWhitespace(java.lang.String str)` Deletes all whitespaces from a String.
    `static java.lang.String` | `difference(java.lang.String s1, java.lang.String s2)` Compare two strings, and return the portion where they differ.
    `static int` | `differenceAt(java.lang.String s1, java.lang.String s2)` Compare two strings, and return the index at which the strings begin to differ.
    `static boolean` | `equals(java.lang.String str1, java.lang.String str2)` Compares two Strings, returning `true` if they are equal.
    `static boolean` | `equalsIgnoreCase(java.lang.String str1, java.lang.String str2)` Compares two Strings, returning `true` if they are equal ignoring the case.
    `static java.lang.String` | `escape(java.lang.String str)` Escapes any values it finds into their String form.
    `static java.lang.String` | `escape(java.lang.String source, char[] escapedChars, char escapeChar)`
    `static java.lang.String` | `getChomp(java.lang.String str, java.lang.String sep)` Remove everything and return the last value of a supplied String, and everything after it from a String.
    `static java.lang.String` | `getNestedString(java.lang.String str, java.lang.String tag)` Get the String that is nested in between two instances of the same String.
    `static java.lang.String` | `getNestedString(java.lang.String str, java.lang.String open, java.lang.String close)` Get the String that is nested in between two Strings.
    `static java.lang.String` | `getPrechomp(java.lang.String str, java.lang.String sep)` Remove and return everything before the first value of a supplied String from another String.
    `static int` | `indexOfAny(java.lang.String str, java.lang.String[] searchStrs)` Find the first index of any of a set of potential substrings.
    `static java.lang.String` | `interpolate(java.lang.String text, java.util.Map namespace)`
    `static boolean` | `isAlpha(java.lang.String str)` Checks if the String contains only unicode letters.
    `static boolean` | `isAlphanumeric(java.lang.String str)` Checks if the String contains only unicode letters or digits.
    `static boolean` | `isAlphanumericSpace(java.lang.String str)` Checks if the String contains only unicode letters, digits or space (`' '`).
    `static boolean` | `isAlphaSpace(java.lang.String str)` Checks if the String contains only unicode letters and space (`' '`).
    `static boolean` | `isBlank(java.lang.String str)` Checks if a String is whitespace, empty ("") or null.
    `static boolean` | `isEmpty(java.lang.String str)` Checks if a (trimmed) String is `null` or empty.
    `static boolean` | `isNotBlank(java.lang.String str)` Checks if a String is not empty (""), not null and not whitespace only.
    `static boolean` | `isNotEmpty(java.lang.String str)` Checks if a String is non `null` and is not empty (`length > 0`).
    `static boolean` | `isNumeric(java.lang.String str)` Checks if the String contains only unicode digits.
    `static boolean` | `isNumericSpace(java.lang.String str)` Checks if the String contains only unicode digits or space (`' '`).
    `static boolean` | `isWhitespace(java.lang.String str)` Checks if the String contains only whitespace.
    `static java.lang.String` | `join(java.util.Iterator iterator, java.lang.String separator)` Joins the elements of the provided `Iterator` into a single String containing the provided elements.
    `static java.lang.String` | `join(java.lang.Object[] array, java.lang.String separator)` Joins the elements of the provided array into a single String containing the provided list of elements.
    `static int` | `lastIndexOfAny(java.lang.String str, java.lang.String[] searchStrs)` Find the latest index of any of a set of potential substrings.
    `static java.lang.String` | `left(java.lang.String str, int len)` Gets the leftmost `n` characters of a String.
    `static java.lang.String` | `leftPad(java.lang.String str, int size)` Left pad a String with spaces.
    `static java.lang.String` | `leftPad(java.lang.String str, int size, java.lang.String delim)` Left pad a String with a specified string.
    `static java.lang.String` | `lowerCase(java.lang.String str)` Convert a String to lower case, `null` String returns `null`.
    `static java.lang.String` | `lowercaseFirstLetter(java.lang.String data)`
    `static java.lang.String` | `mid(java.lang.String str, int pos, int len)` Gets `n` characters from the middle of a String.
    `static java.lang.String` | `overlayString(java.lang.String text, java.lang.String overlay, int start, int end)` Overlay a part of a String with another String.
    `static java.lang.String` | `prechomp(java.lang.String str, java.lang.String sep)` Remove the first value of a supplied String, and everything before it from a String.
    `static java.lang.String` | `quoteAndEscape(java.lang.String source, char quoteChar)` Quote and escape a String with the given character, handling `null`.
    `static java.lang.String` | `quoteAndEscape(java.lang.String source, char quoteChar, char[] quotingTriggers)` Quote and escape a String with the given character, handling `null`.
    `static java.lang.String` | `quoteAndEscape(java.lang.String source, char quoteChar, char[] escapedChars, char[] quotingTriggers, char escapeChar, boolean force)`
    `static java.lang.String` | `quoteAndEscape(java.lang.String source, char quoteChar, char[] escapedChars, char escapeChar, boolean force)`
    `static java.lang.String` | `removeAndHump(java.lang.String data, java.lang.String replaceThis)`
    `static java.lang.String` | `removeDuplicateWhitespace(java.lang.String s)` Remove all duplicate whitespace characters and line terminators are replaced with a single space.
    `static java.lang.String` | `repeat(java.lang.String str, int repeat)` Repeat a String `n` times to form a new string.
    `static java.lang.String` | `replace(java.lang.String text, char repl, char with)` Replace all occurances of a char within another char.
    `static java.lang.String` | `replace(java.lang.String text, char repl, char with, int max)` Replace a char with another char inside a larger String, for the first `max` values of the search char.
    `static java.lang.String` | `replace(java.lang.String text, java.lang.String repl, java.lang.String with)` Replace all occurances of a String within another String.
    `static java.lang.String` | `replace(java.lang.String text, java.lang.String repl, java.lang.String with, int max)` Replace a String with another String inside a larger String, for the first `max` values of the search String.
    `static java.lang.String` | `replaceOnce(java.lang.String text, char repl, char with)` Replace a char with another char inside a larger String, once.
    `static java.lang.String` | `replaceOnce(java.lang.String text, java.lang.String repl, java.lang.String with)` Replace a String with another String inside a larger String, once.
    `static java.lang.String` | `reverse(java.lang.String str)` Reverse a String.
    `static java.lang.String` | `reverseDelimitedString(java.lang.String str, java.lang.String delimiter)` Reverses a String that is delimited by a specific character.
    `static java.lang.String` | `right(java.lang.String str, int len)` Gets the rightmost `n` characters of a String.
    `static java.lang.String` | `rightPad(java.lang.String str, int size)` Right pad a String with spaces.
    `static java.lang.String` | `rightPad(java.lang.String str, int size, java.lang.String delim)` Right pad a String with a specified string.
    `static java.lang.String[]` | `split(java.lang.String str)` Splits the provided text into a array, using whitespace as the separator.
    `static java.lang.String[]` | `split(java.lang.String text, java.lang.String separator)`
    `static java.lang.String[]` | `split(java.lang.String str, java.lang.String separator, int max)` Splits the provided text into a array, based on a given separator.
    `static java.lang.String` | `strip(java.lang.String str)` Remove whitespace from the front and back of a String.
    `static java.lang.String` | `strip(java.lang.String str, java.lang.String delim)` Remove a specified String from the front and back of a String.
    `static java.lang.String[]` | `stripAll(java.lang.String[] strs)` Strip whitespace from the front and back of every String in the array.
    `static java.lang.String[]` | `stripAll(java.lang.String[] strs, java.lang.String delimiter)` Strip the specified delimiter from the front and back of every String in the array.
    `static java.lang.String` | `stripEnd(java.lang.String str, java.lang.String strip)` Strip any of a supplied String from the end of a String.
    `static java.lang.String` | `stripStart(java.lang.String str, java.lang.String strip)` Strip any of a supplied String from the start of a String.
    `static java.lang.String` | `substring(java.lang.String str, int start)` Gets a substring from the specified string avoiding exceptions.
    `static java.lang.String` | `substring(java.lang.String str, int start, int end)` Gets a substring from the specified String avoiding exceptions.
    `static java.lang.String` | `swapCase(java.lang.String str)` Swaps the case of String.
    `static java.lang.String` | `trim(java.lang.String str)` Removes control characters, including whitespace, from both ends of this String, handling `null` by returning `null`.
    `static java.lang.String` | `uncapitalise(java.lang.String str)` Uncapitalise a String.
    `static java.lang.String` | `uncapitaliseAllWords(java.lang.String str)` Uncapitalise all the words in a string.
    `static java.lang.String` | `unifyLineSeparators(java.lang.String s)` Parses the given String and replaces all occurrences of '\n', '\r' and '\r\n' with the system line separator.
    `static java.lang.String` | `unifyLineSeparators(java.lang.String s, java.lang.String ls)` Parses the given String and replaces all occurrences of '\n', '\r' and '\r\n' with the system line separator.
    `static java.lang.String` | `upperCase(java.lang.String str)` Convert a String to upper case, `null` String returns `null`.

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

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

- - ### 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 manager to operate.

  - ### Method Detail

    - #### clean

          public static java.lang.String clean(java.lang.String str)

      Removes control characters, including whitespace, from both ends of this String, handling `null` by returning an empty String.

      Parameters:
        `str` - the String to check
      Returns:
        the trimmed text (never `null`)
      See Also:
        `String.trim()`

    - #### trim

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

      Removes control characters, including whitespace, from both ends of this String, handling `null` by returning `null`.

      Parameters:
        `str` - the String to check
      Returns:
        the trimmed text (or `null`)
      See Also:
        `String.trim()`

    - #### deleteWhitespace

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

      Deletes all whitespaces from a String.

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

      Parameters:
        `str` - String target to delete whitespace from
      Returns:
        the String without whitespaces
      Throws:
        `java.lang.NullPointerException`

    - #### isNotEmpty

          public static boolean isNotEmpty(java.lang.String str)

      Checks if a String is non `null` and is not empty (`length > 0`).

      Parameters:
        `str` - the String to check
      Returns:
        true if the String is non-null, and not length zero

    - #### isEmpty

          public static boolean isEmpty(java.lang.String str)

      Checks if a (trimmed) String is `null` or empty.

      Note: In future releases, this method will no longer trim the input string such that it works complementary to `isNotEmpty(String)`. Code that wants to test for whitespace-only strings should be migrated to use `isBlank(String)` instead.

      Parameters:
        `str` - the String to check
      Returns:
        `true` if the String is `null`, or length zero once trimmed

    - #### isBlank

          public static boolean isBlank(java.lang.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:
        1.5.2

    - #### isNotBlank

          public static boolean isNotBlank(java.lang.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:
        1.5.2

    - #### equals

          public static boolean equals(java.lang.String str1,
                                       java.lang.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.

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

    - #### equalsIgnoreCase

          public static boolean equalsIgnoreCase(java.lang.String str1,
                                                 java.lang.String str2)

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

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

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

    - #### indexOfAny

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

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

      `null` String will return `-1`.

      Parameters:
        `str` - the String to check
        `searchStrs` - the Strings to search for
      Returns:
        the first index of any of the searchStrs in str
      Throws:
        `java.lang.NullPointerException` - if any of searchStrs[i] is `null`

    - #### lastIndexOfAny

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

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

      `null` string will return `-1`.

      Parameters:
        `str` - the String to check
        `searchStrs` - the Strings to search for
      Returns:
        the last index of any of the Strings
      Throws:
        `java.lang.NullPointerException` - if any of searchStrs[i] is `null`

    - #### substring

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

      Gets a substring from the specified string avoiding exceptions.

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

      Parameters:
        `str` - the String to get the substring from
        `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

    - #### substring

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

      Gets a substring from the specified String avoiding exceptions.

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

      Parameters:
        `str` - the String to get the substring from
        `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

    - #### left

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

      Gets the leftmost `n` characters of a String.

      If `n` characters are not available, or the String is `null`, the String will be returned without an exception.

      Parameters:
        `str` - the String to get the leftmost characters from
        `len` - the length of the required String
      Returns:
        the leftmost characters
      Throws:
        `java.lang.IllegalArgumentException` - if len is less than zero

    - #### right

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

      Gets the rightmost `n` characters of a String.

      If `n` characters are not available, or the String is `null`, the String will be returned without an exception.

      Parameters:
        `str` - the String to get the rightmost characters from
        `len` - the length of the required String
      Returns:
        the leftmost characters
      Throws:
        `java.lang.IllegalArgumentException` - if len is less than zero

    - #### mid

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

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

      If `n` characters are not available, the remainder of the String will be returned without an exception. If the String is `null`, `null` will be returned.

      Parameters:
        `str` - the String to get the characters from
        `pos` - the position to start from
        `len` - the length of the required String
      Returns:
        the leftmost characters
      Throws:
        `java.lang.IndexOutOfBoundsException` - if pos is out of bounds
        `java.lang.IllegalArgumentException` - if len is less than zero

    - #### split

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

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

      The separator is not included in the returned String array.

      Parameters:
        `str` - the String to parse
      Returns:
        an array of parsed Strings

    - #### split

          public static java.lang.String[] split(java.lang.String text,
                                                 java.lang.String separator)

      See Also:
        `split(String, String, int)`

    - #### split

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

      Splits the provided text into a array, based on a given separator.

      The separator is not included in the returned String array. The maximum number of splits to perfom can be controlled. A `null` separator will cause parsing to be on whitespace.

      This is useful for quickly splitting a String directly into an array of tokens, instead of an enumeration of tokens (as `StringTokenizer` does).

      Parameters:
        `str` - The string to parse.
        `separator` - Characters used as the delimiters. If `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

    - #### concatenate

          public static java.lang.String concatenate(java.lang.Object[] array)

      Concatenates elements of an array into a single String.

      The difference from join is that concatenate has no delimiter.

      Parameters:
        `array` - the array of values to concatenate.
      Returns:
        the concatenated string.

    - #### join

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

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

      No delimiter is added before or after the list. A `null` separator is the same as a blank String.

      Parameters:
        `array` - the array of values to join together
        `separator` - the separator character to use
      Returns:
        the joined String

    - #### join

          public static java.lang.String join(java.util.Iterator iterator,
                                              java.lang.String separator)

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

      No delimiter is added before or after the list. A `null` separator is the same as a blank String.

      Parameters:
        `iterator` - the `Iterator` of values to join together
        `separator` - the separator character to use
      Returns:
        the joined String

    - #### replaceOnce

          public static java.lang.String replaceOnce(java.lang.String text,
                                                     char repl,
                                                     char with)

      Replace a char with another char inside a larger String, once.

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

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

    - #### replace

          public static java.lang.String replace(java.lang.String text,
                                                 char repl,
                                                 char with)

      Replace all occurances of a char within another char.

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

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

    - #### replace

          public static java.lang.String replace(java.lang.String text,
                                                 char repl,
                                                 char with,
                                                 int max)

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

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

      Parameters:
        `text` - text to search and replace in
        `repl` - char to search for
        `with` - char to replace with
        `max` - maximum number of values to replace, or `-1` if no maximum
      Returns:
        the text with any replacements processed

    - #### replaceOnce

          public static java.lang.String replaceOnce(java.lang.String text,
                                                     java.lang.String repl,
                                                     java.lang.String with)

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

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

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

    - #### replace

          public static java.lang.String replace(java.lang.String text,
                                                 java.lang.String repl,
                                                 java.lang.String with)

      Replace all occurances of a String within another String.

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

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

    - #### replace

          public static java.lang.String replace(java.lang.String text,
                                                 java.lang.String repl,
                                                 java.lang.String with,
                                                 int max)

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

      Parameters:
        `text` - text to search and replace in
        `repl` - String to search for
        `with` - String to replace with
        `max` - maximum number of values to replace, or `-1` if no maximum
      Returns:
        the text with any replacements processed

    - #### overlayString

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

      Overlay a part of a String with another String.

      Parameters:
        `text` - String to do overlaying in
        `overlay` - String to overlay
        `start` - int to start overlaying at
        `end` - int to stop overlaying before
      Returns:
        String with overlayed text
      Throws:
        `java.lang.NullPointerException` - if text or overlay is `null`

    - #### center

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

      Center a String in a larger String of size `n`.

      Uses spaces as the value to buffer the String with. Equivalent to `center(str, size, " ")`.

      Parameters:
        `str` - String to center
        `size` - int size of new String
      Returns:
        String containing centered String
      Throws:
        `java.lang.NullPointerException` - if str is `null`

    - #### center

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

      Center a String in a larger String of size `n`.

      Uses a supplied String as the value to buffer the String with.

      Parameters:
        `str` - String to center
        `size` - int size of new String
        `delim` - String to buffer the new String with
      Returns:
        String containing centered String
      Throws:
        `java.lang.NullPointerException` - if str or delim is `null`
        `java.lang.ArithmeticException` - if delim is the empty String

    - #### chomp

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

      Remove the last newline, and everything after it from a String.

      Parameters:
        `str` - String to chomp the newline from
      Returns:
        String without chomped newline
      Throws:
        `java.lang.NullPointerException` - if str is `null`

    - #### chomp

          public static java.lang.String chomp(java.lang.String str,
                                               java.lang.String sep)

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

      Parameters:
        `str` - String to chomp from
        `sep` - String to chomp
      Returns:
        String without chomped ending
      Throws:
        `java.lang.NullPointerException` - if str or sep is `null`

    - #### chompLast

          public static java.lang.String chompLast(java.lang.String str)

      Remove a newline if and only if it is at the end of the supplied String.

      Parameters:
        `str` - String to chomp from
      Returns:
        String without chomped ending
      Throws:
        `java.lang.NullPointerException` - if str is `null`

    - #### chompLast

          public static java.lang.String chompLast(java.lang.String str,
                                                   java.lang.String sep)

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

      Parameters:
        `str` - String to chomp from
        `sep` - String to chomp
      Returns:
        String without chomped ending
      Throws:
        `java.lang.NullPointerException` - if str or sep is `null`

    - #### getChomp

          public static java.lang.String getChomp(java.lang.String str,
                                                  java.lang.String sep)

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

      Parameters:
        `str` - String to chomp from
        `sep` - String to chomp
      Returns:
        String chomped
      Throws:
        `java.lang.NullPointerException` - if str or sep is `null`

    - #### prechomp

          public static java.lang.String prechomp(java.lang.String str,
                                                  java.lang.String sep)

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

      Parameters:
        `str` - String to chomp from
        `sep` - String to chomp
      Returns:
        String without chomped beginning
      Throws:
        `java.lang.NullPointerException` - if str or sep is `null`

    - #### getPrechomp

          public static java.lang.String getPrechomp(java.lang.String str,
                                                     java.lang.String sep)

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

      Parameters:
        `str` - String to chomp from
        `sep` - String to chomp
      Returns:
        String prechomped
      Throws:
        `java.lang.NullPointerException` - if str or sep is `null`

    - #### chop

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

      Remove the last character from a String.

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

      Parameters:
        `str` - String to chop last character from
      Returns:
        String without last character
      Throws:
        `java.lang.NullPointerException` - if str is `null`

    - #### chopNewline

          public static java.lang.String chopNewline(java.lang.String str)

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

      Parameters:
        `str` - String to chop a newline from
      Returns:
        String without newline
      Throws:
        `java.lang.NullPointerException` - if str is `null`

    - #### escape

          public static java.lang.String escape(java.lang.String str)

      Escapes any values it finds into their String form.

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

      Parameters:
        `str` - String to escape values in
      Returns:
        String with escaped values
      Throws:
        `java.lang.NullPointerException` - if str is `null`

    - #### repeat

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

      Repeat a String `n` times to form a new string.

      Parameters:
        `str` - String to repeat
        `repeat` - number of times to repeat str
      Returns:
        String with repeated String
      Throws:
        `java.lang.NegativeArraySizeException` - if `repeat < 0`
        `java.lang.NullPointerException` - if str is `null`

    - #### rightPad

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

      Right pad a String with spaces.

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

      Parameters:
        `str` - String to repeat
        `size` - number of times to repeat str
      Returns:
        right padded String
      Throws:
        `java.lang.NullPointerException` - if str is `null`

    - #### rightPad

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

      Right pad a String with a specified string.

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

      Parameters:
        `str` - String to pad out
        `size` - size to pad to
        `delim` - String to pad with
      Returns:
        right padded String
      Throws:
        `java.lang.NullPointerException` - if str or delim is `null`
        `java.lang.ArithmeticException` - if delim is the empty String

    - #### leftPad

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

      Left pad a String with spaces.

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

      Parameters:
        `str` - String to pad out
        `size` - size to pad to
      Returns:
        left padded String
      Throws:
        `java.lang.NullPointerException` - if str or delim is `null`

    - #### leftPad

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

      Left pad a String with a specified string. Pad to a size of n.
      Parameters:
        `str` - String to pad out
        `size` - size to pad to
        `delim` - String to pad with
      Returns:
        left padded String
      Throws:
        `java.lang.NullPointerException` - if str or delim is null
        `java.lang.ArithmeticException` - if delim is the empty string

    - #### strip

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

      Remove whitespace from the front and back of a String.

      Parameters:
        `str` - the String to remove whitespace from
      Returns:
        the stripped String

    - #### strip

          public static java.lang.String strip(java.lang.String str,
                                               java.lang.String delim)

      Remove a specified String from the front and back of a String.

      If whitespace is wanted to be removed, used the `strip(java.lang.String)` method.

      Parameters:
        `str` - the String to remove a string from
        `delim` - the String to remove at start and end
      Returns:
        the stripped String

    - #### stripAll

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

      Strip whitespace from the front and back of every String in the array.

      Parameters:
        `strs` - the Strings to remove whitespace from
      Returns:
        the stripped Strings

    - #### stripAll

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

      Strip the specified delimiter from the front and back of every String in the array.

      Parameters:
        `strs` - the Strings to remove a String from
        `delimiter` - the String to remove at start and end
      Returns:
        the stripped Strings

    - #### stripEnd

          public static java.lang.String stripEnd(java.lang.String str,
                                                  java.lang.String strip)

      Strip any of a supplied String from the end of a String.

      If the strip String is `null`, whitespace is stripped.

      Parameters:
        `str` - the String to remove characters from
        `strip` - the String to remove
      Returns:
        the stripped String

    - #### stripStart

          public static java.lang.String stripStart(java.lang.String str,
                                                    java.lang.String strip)

      Strip any of a supplied String from the start of a String.

      If the strip String is `null`, whitespace is stripped.

      Parameters:
        `str` - the String to remove characters from
        `strip` - the String to remove
      Returns:
        the stripped String

    - #### upperCase

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

      Convert a String to upper case, `null` String returns `null`.

      Parameters:
        `str` - the String to uppercase
      Returns:
        the upper cased String

    - #### lowerCase

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

      Convert a String to lower case, `null` String returns `null`.

      Parameters:
        `str` - the string to lowercase
      Returns:
        the lower cased String

    - #### uncapitalise

          public static java.lang.String uncapitalise(java.lang.String str)

      Uncapitalise a String.

      That is, convert the first character into lower-case. `null` is returned as `null`.

      Parameters:
        `str` - the String to uncapitalise
      Returns:
        uncapitalised String

    - #### capitalise

          public static java.lang.String capitalise(java.lang.String str)

      Capitalise a String.

      That is, convert the first character into title-case. `null` is returned as `null`.

      Parameters:
        `str` - the String to capitalise
      Returns:
        capitalised String

    - #### swapCase

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

      Swaps the case of String.

      Properly looks after making sure the start of words are Titlecase and not Uppercase.

      `null` is returned as `null`.

      Parameters:
        `str` - the String to swap the case of
      Returns:
        the modified String

    - #### capitaliseAllWords

          public static java.lang.String capitaliseAllWords(java.lang.String str)

      Capitalise all the words in a String.

      Uses `Character.isWhitespace(char)` as a separator between words.

      `null` will return `null`.

      Parameters:
        `str` - the String to capitalise
      Returns:
        capitalised String

    - #### uncapitaliseAllWords

          public static java.lang.String uncapitaliseAllWords(java.lang.String str)

      Uncapitalise all the words in a string.

      Uses `Character.isWhitespace(char)` as a separator between words.

      `null` will return `null`.

      Parameters:
        `str` - the string to uncapitalise
      Returns:
        uncapitalised string

    - #### getNestedString

          public static java.lang.String getNestedString(java.lang.String str,
                                                         java.lang.String tag)

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

      If `str` is `null`, will return `null`.

      Parameters:
        `str` - the String containing nested-string
        `tag` - the String before and after nested-string
      Returns:
        the String that was nested, or `null`
      Throws:
        `java.lang.NullPointerException` - if tag is `null`

    - #### getNestedString

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

      Get the String that is nested in between two Strings.

      Parameters:
        `str` - the String containing nested-string
        `open` - the String before nested-string
        `close` - the String after nested-string
      Returns:
        the String that was nested, or `null`
      Throws:
        `java.lang.NullPointerException` - if open or close is `null`

    - #### countMatches

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

      How many times is the substring in the larger String.

      `null` returns `0`.

      Parameters:
        `str` - the String to check
        `sub` - the substring to count
      Returns:
        the number of occurances, 0 if the String is `null`
      Throws:
        `java.lang.NullPointerException` - if sub is `null`

    - #### isAlpha

          public static boolean isAlpha(java.lang.String str)

      Checks if the String contains only unicode letters.

      `null` will return `false`. An empty String will return `true`.

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

    - #### isWhitespace

          public static boolean isWhitespace(java.lang.String str)

      Checks if the String contains only whitespace.

      `null` will return `false`. An empty String will return `true`.

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

    - #### isAlphaSpace

          public static boolean isAlphaSpace(java.lang.String str)

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

      `null` will return `false`. An empty String will return `true`.

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

    - #### isAlphanumeric

          public static boolean isAlphanumeric(java.lang.String str)

      Checks if the String contains only unicode letters or digits.

      `null` will return `false`. An empty String will return `true`.

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

    - #### isAlphanumericSpace

          public static boolean isAlphanumericSpace(java.lang.String str)

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

      `null` will return `false`. An empty String will return `true`.

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

    - #### isNumeric

          public static boolean isNumeric(java.lang.String str)

      Checks if the String contains only unicode digits.

      `null` will return `false`. An empty String will return `true`.

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

    - #### isNumericSpace

          public static boolean isNumericSpace(java.lang.String str)

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

      `null` will return `false`. An empty String will return `true`.

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

    - #### defaultString

          public static java.lang.String defaultString(java.lang.Object obj)

      Returns either the passed in `Object` as a String, or, if the `Object` is `null`, an empty String.

      Parameters:
        `obj` - the Object to check
      Returns:
        the passed in Object's toString, or blank if it was `null`

    - #### defaultString

          public static java.lang.String defaultString(java.lang.Object obj,
                                                       java.lang.String defaultString)

      Returns either the passed in `Object` as a String, or, if the `Object` is `null`, a passed in default String.

      Parameters:
        `obj` - the Object to check
        `defaultString` - the default String to return if str is `null`
      Returns:
        the passed in string, or the default if it was `null`

    - #### reverse

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

      Reverse a String.

      `null` String returns `null`.

      Parameters:
        `str` - the String to reverse
      Returns:
        the reversed String

    - #### reverseDelimitedString

          public static java.lang.String reverseDelimitedString(java.lang.String str,
                                                                java.lang.String delimiter)

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

      Parameters:
        `str` - the String to reverse
        `delimiter` - the delimiter to use
      Returns:
        the reversed String

    - #### abbreviate

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

      Turn "Now is the time for all good men" into "Now is the time for..."

      Specifically:

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

      Parameters:
        `maxWidth` - maximum length of result string

    - #### abbreviate

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

      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.

      Parameters:
        `offset` - left edge of source string
        `maxWidth` - maximum length of result string

    - #### difference

          public static java.lang.String difference(java.lang.String s1,
                                                    java.lang.String s2)

      Compare two strings, and return the portion where they differ. (More precisely, return the remainder of the second string, starting from where it's different from the first.)

      E.g. strdiff("i am a machine", "i am a robot") -> "robot"

      Returns:
        the portion of s2 where it differs from s1; returns the empty string ("") if they are equal

    - #### differenceAt

          public static int differenceAt(java.lang.String s1,
                                         java.lang.String s2)

      Compare two strings, and return the index at which the strings begin to differ.

      E.g. strdiff("i am a machine", "i am a robot") -> 7

      Returns:
        the index where s2 and s1 begin to differ; -1 if they are equal

    - #### interpolate

          public static java.lang.String interpolate(java.lang.String text,
                                                     java.util.Map namespace)

    - #### removeAndHump

          public static java.lang.String removeAndHump(java.lang.String data,
                                                       java.lang.String replaceThis)

    - #### capitalizeFirstLetter

          public static java.lang.String capitalizeFirstLetter(java.lang.String data)

    - #### lowercaseFirstLetter

          public static java.lang.String lowercaseFirstLetter(java.lang.String data)

    - #### addAndDeHump

          public static java.lang.String addAndDeHump(java.lang.String view)

    - #### quoteAndEscape

          public static java.lang.String quoteAndEscape(java.lang.String source,
                                                        char quoteChar)

      Quote and escape a String with the given character, handling `null`.

           StringUtils.quoteAndEscape(null, *)    = null
           StringUtils.quoteAndEscape("", *)      = ""
           StringUtils.quoteAndEscape("abc", '"') = abc
           StringUtils.quoteAndEscape("a\"bc", '"') = "a\"bc"
           StringUtils.quoteAndEscape("a\"bc", '\'') = 'a\"bc'

      Parameters:
        `source` -
        `quoteChar` -
      Returns:
        the String quoted and escaped
      Since:
        1.5.1
      See Also:
        `quoteAndEscape(String, char, char[], char[], char, boolean)`

    - #### quoteAndEscape

          public static java.lang.String quoteAndEscape(java.lang.String source,
                                                        char quoteChar,
                                                        char[] quotingTriggers)

      Quote and escape a String with the given character, handling `null`.

      Parameters:
        `source` -
        `quoteChar` -
        `quotingTriggers` -
      Returns:
        the String quoted and escaped
      Since:
        1.5.1
      See Also:
        `quoteAndEscape(String, char, char[], char[], char, boolean)`

    - #### quoteAndEscape

          public static java.lang.String quoteAndEscape(java.lang.String source,
                                                        char quoteChar,
                                                        char[] escapedChars,
                                                        char escapeChar,
                                                        boolean force)

      Parameters:
        `source` -
        `quoteChar` -
        `escapedChars` -
        `escapeChar` -
        `force` -
      Returns:
        the String quoted and escaped
      Since:
        1.5.1
      See Also:
        `quoteAndEscape(String, char, char[], char[], char, boolean)`

    - #### quoteAndEscape

          public static java.lang.String quoteAndEscape(java.lang.String source,
                                                        char quoteChar,
                                                        char[] escapedChars,
                                                        char[] quotingTriggers,
                                                        char escapeChar,
                                                        boolean force)

      Parameters:
        `source` -
        `quoteChar` -
        `escapedChars` -
        `quotingTriggers` -
        `escapeChar` -
        `force` -
      Returns:
        the String quoted and escaped
      Since:
        1.5.1

    - #### escape

          public static java.lang.String escape(java.lang.String source,
                                                char[] escapedChars,
                                                char escapeChar)

      Parameters:
        `source` -
        `escapedChars` -
        `escapeChar` -
      Returns:
        the String escaped
      Since:
        1.5.1

    - #### removeDuplicateWhitespace

          public static java.lang.String removeDuplicateWhitespace(java.lang.String s)

      Remove all duplicate whitespace characters and line terminators are replaced with a single space.
      Parameters:
        `s` - a not null String
      Returns:
        a string with unique whitespace.
      Since:
        1.5.7

    - #### unifyLineSeparators

          public static java.lang.String unifyLineSeparators(java.lang.String s)

      Parses the given String and replaces all occurrences of '\n', '\r' and '\r\n' with the system line separator.
      Parameters:
        `s` - a not null String
      Returns:
        a String that contains only System line separators.
      Since:
        1.5.7
      See Also:
        `unifyLineSeparators(String, String)`

    - #### unifyLineSeparators

          public static java.lang.String unifyLineSeparators(java.lang.String s,
                                                             java.lang.String ls)

      Parses the given String and replaces all occurrences of '\n', '\r' and '\r\n' with the system line separator.
      Parameters:
        `s` - a not null String
        `ls` - the wanted line separator ("\n" on UNIX), if null using the System line separator.
      Returns:
        a String that contains only System line separators.
      Throws:
        `java.lang.IllegalArgumentException` - if ls is not '\n', '\r' and '\r\n' characters.
      Since:
        1.5.7

    - #### contains

          public static boolean contains(java.lang.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:
        1.5.7

    - #### contains

          public static boolean contains(java.lang.String str,
                                         java.lang.String searchStr)

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

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