WordUtils
Date: 2017-02-08

org.apache.commons.lang3.text

## Class WordUtils

- java.lang.Object
- - org.apache.commons.lang3.text.WordUtils

-     public class WordUtils
      extends java.lang.Object

  Operations on Strings that contain words.

  This class tries to handle `null` input gracefully. An exception will not be thrown for a `null` input. Each method documents its behaviour in more detail.

  Since:
    2.0

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `capitalize(java.lang.String str)` Capitalizes all the whitespace separated words in a String.
    `static java.lang.String` | `capitalize(java.lang.String str, char... delimiters)` Capitalizes all the delimiter separated words in a String.
    `static java.lang.String` | `capitalizeFully(java.lang.String str)` Converts all the whitespace separated words in a String into capitalized words, that is each word is made up of a titlecase character and then a series of lowercase characters.
    `static java.lang.String` | `capitalizeFully(java.lang.String str, char... delimiters)` Converts all the delimiter separated words in a String into capitalized words, that is each word is made up of a titlecase character and then a series of lowercase characters.
    `static boolean` | `containsAllWords(java.lang.CharSequence word, java.lang.CharSequence... words)` Checks if the String contains all words in the given array.
    `static java.lang.String` | `initials(java.lang.String str)` Extracts the initial characters from each word in the String.
    `static java.lang.String` | `initials(java.lang.String str, char... delimiters)` Extracts the initial characters from each word in the String.
    `static java.lang.String` | `swapCase(java.lang.String str)` Swaps the case of a String using a word based algorithm.
    `static java.lang.String` | `uncapitalize(java.lang.String str)` Uncapitalizes all the whitespace separated words in a String.
    `static java.lang.String` | `uncapitalize(java.lang.String str, char... delimiters)` Uncapitalizes all the whitespace separated words in a String.
    `static java.lang.String` | `wrap(java.lang.String str, int wrapLength)` Wraps a single line of text, identifying words by `' '`.
    `static java.lang.String` | `wrap(java.lang.String str, int wrapLength, java.lang.String newLineStr, boolean wrapLongWords)` Wraps a single line of text, identifying words by `' '`.
    `static java.lang.String` | `wrap(java.lang.String str, int wrapLength, java.lang.String newLineStr, boolean wrapLongWords, java.lang.String wrapOn)` Wraps a single line of text, identifying words by `wrapOn`.

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

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

- - ### Constructor Detail

    - #### WordUtils

          public WordUtils()

      `WordUtils` instances should NOT be constructed in standard programming. Instead, the class should be used as `WordUtils.wrap("foo bar", 20);`.

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

  - ### Method Detail

    - #### wrap

          public static java.lang.String wrap(java.lang.String str,
                              int wrapLength)

      Wraps a single line of text, identifying words by `' '`.

      New lines will be separated by the system property line separator. Very long words, such as URLs will not be wrapped.

      Leading spaces on a new line are stripped. Trailing spaces are not stripped.

      input | wrapLength | result
      --- | --- | ---
      null | * | null
      "" | * | ""
      "Here is one line of text that is going to be wrapped after 20 columns." | 20 | "Here is one line of\ntext that is going\nto be wrapped after\n20 columns."
      "Click here to jump to the commons website - http://commons.apache.org" | 20 | "Click here to jump\nto the commons\nwebsite -\nhttp://commons.apache.org"
      "Click here, http://commons.apache.org, to jump to the commons website" | 20 | "Click here,\nhttp://commons.apache.org,\nto jump to the\ncommons website"

      (assuming that '\n' is the systems line separator)
      Parameters:
        `str` - the String to be word wrapped, may be null
        `wrapLength` - the column to wrap the words at, less than 1 is treated as 1
      Returns:
        a line with newlines inserted, `null` if null input

    - #### wrap

          public static java.lang.String wrap(java.lang.String str,
                              int wrapLength,
                              java.lang.String newLineStr,
                              boolean wrapLongWords)

      Wraps a single line of text, identifying words by `' '`.

      Leading spaces on a new line are stripped. Trailing spaces are not stripped.

      input | wrapLenght | newLineString | wrapLongWords | result
      --- | --- | --- | --- | ---
      null | * | * | true/false | null
      "" | * | * | true/false | ""
      "Here is one line of text that is going to be wrapped after 20 columns." | 20 | "\n" | true/false | "Here is one line of\ntext that is going\nto be wrapped after\n20 columns."
      "Here is one line of text that is going to be wrapped after 20 columns." | 20 | "<br />" | true/false | "Here is one line of<br />text that is going<br />to be wrapped after<br />20 columns."
      "Here is one line of text that is going to be wrapped after 20 columns." | 20 | null | true/false | "Here is one line of" + systemNewLine + "text that is going" + systemNewLine + "to be wrapped after" + systemNewLine + "20 columns."
      "Click here to jump to the commons website - http://commons.apache.org" | 20 | "\n" | false | "Click here to jump\nto the commons\nwebsite -\nhttp://commons.apache.org"
      "Click here to jump to the commons website - http://commons.apache.org" | 20 | "\n" | true | "Click here to jump\nto the commons\nwebsite -\nhttp://commons.apach\ne.org"

      Parameters:
        `str` - the String to be word wrapped, may be null
        `wrapLength` - the column to wrap the words at, less than 1 is treated as 1
        `newLineStr` - the string to insert for a new line, `null` uses the system property line separator
        `wrapLongWords` - true if long words (such as URLs) should be wrapped
      Returns:
        a line with newlines inserted, `null` if null input

    - #### wrap

          public static java.lang.String wrap(java.lang.String str,
                              int wrapLength,
                              java.lang.String newLineStr,
                              boolean wrapLongWords,
                              java.lang.String wrapOn)

      Wraps a single line of text, identifying words by `wrapOn`.

      Leading spaces on a new line are stripped. Trailing spaces are not stripped.

      input | wrapLenght | newLineString | wrapLongWords | wrapOn | result
      --- | --- | --- | --- | --- | ---
      null | * | * | true/false | * | null
      "" | * | * | true/false | * | ""
      "Here is one line of text that is going to be wrapped after 20 columns." | 20 | "\n" | true/false | " " | "Here is one line of\ntext that is going\nto be wrapped after\n20 columns."
      "Here is one line of text that is going to be wrapped after 20 columns." | 20 | "<br />" | true/false | " " | "Here is one line of<br />text that is going<br />to be wrapped after<br />20 columns."
      "Here is one line of text that is going to be wrapped after 20 columns." | 20 | null | true/false | " " | "Here is one line of" + systemNewLine + "text that is going" + systemNewLine + "to be wrapped after" + systemNewLine + "20 columns."
      "Click here to jump to the commons website - http://commons.apache.org" | 20 | "\n" | false | " " | "Click here to jump\nto the commons\nwebsite -\nhttp://commons.apache.org"
      "Click here to jump to the commons website - http://commons.apache.org" | 20 | "\n" | true | " " | "Click here to jump\nto the commons\nwebsite -\nhttp://commons.apach\ne.org"
      "flammable/inflammable" | 20 | "\n" | true | "/" | "flammable\ninflammable"

      Parameters:
        `str` - the String to be word wrapped, may be null
        `wrapLength` - the column to wrap the words at, less than 1 is treated as 1
        `newLineStr` - the string to insert for a new line, `null` uses the system property line separator
        `wrapLongWords` - true if long words (such as URLs) should be wrapped
        `wrapOn` - regex expression to be used as a breakable characters, if blank string is provided a space character will be used
      Returns:
        a line with newlines inserted, `null` if null input

    - #### capitalize

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

      Capitalizes all the whitespace separated words in a String. Only the first character of each word is changed. To convert the rest of each word to lowercase at the same time, use `capitalizeFully(String)`.

      Whitespace is defined by `Character.isWhitespace(char)`. A `null` input String returns `null`. Capitalization uses the Unicode title case, normally equivalent to upper case.

           WordUtils.capitalize(null)        = null
           WordUtils.capitalize("")          = ""
           WordUtils.capitalize("i am FINE") = "I Am FINE"

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

    - #### capitalize

          public static java.lang.String capitalize(java.lang.String str,
                                    char... delimiters)

      Capitalizes all the delimiter separated words in a String. Only the first character of each word is changed. To convert the rest of each word to lowercase at the same time, use `capitalizeFully(String, char[])`.

      The delimiters represent a set of characters understood to separate words. The first string character and the first non-delimiter character after a delimiter will be capitalized.

      A `null` input String returns `null`. Capitalization uses the Unicode title case, normally equivalent to upper case.

           WordUtils.capitalize(null, *)            = null
           WordUtils.capitalize("", *)              = ""
           WordUtils.capitalize(*, new char[0])     = *
           WordUtils.capitalize("i am fine", null)  = "I Am Fine"
           WordUtils.capitalize("i aM.fine", {'.'}) = "I aM.Fine"

      Parameters:
        `str` - the String to capitalize, may be null
        `delimiters` - set of characters to determine capitalization, null means whitespace
      Returns:
        capitalized String, `null` if null String input
      Since:
        2.1
      See Also:
        `uncapitalize(String)`, `capitalizeFully(String)`

    - #### capitalizeFully

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

      Converts all the whitespace separated words in a String into capitalized words, that is each word is made up of a titlecase character and then a series of lowercase characters.

      Whitespace is defined by `Character.isWhitespace(char)`. A `null` input String returns `null`. Capitalization uses the Unicode title case, normally equivalent to upper case.

           WordUtils.capitalizeFully(null)        = null
           WordUtils.capitalizeFully("")          = ""
           WordUtils.capitalizeFully("i am FINE") = "I Am Fine"

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

    - #### capitalizeFully

          public static java.lang.String capitalizeFully(java.lang.String str,
                                         char... delimiters)

      Converts all the delimiter separated words in a String into capitalized words, that is each word is made up of a titlecase character and then a series of lowercase characters.

      The delimiters represent a set of characters understood to separate words. The first string character and the first non-delimiter character after a delimiter will be capitalized.

      A `null` input String returns `null`. Capitalization uses the Unicode title case, normally equivalent to upper case.

           WordUtils.capitalizeFully(null, *)            = null
           WordUtils.capitalizeFully("", *)              = ""
           WordUtils.capitalizeFully(*, null)            = *
           WordUtils.capitalizeFully(*, new char[0])     = *
           WordUtils.capitalizeFully("i aM.fine", {'.'}) = "I am.Fine"

      Parameters:
        `str` - the String to capitalize, may be null
        `delimiters` - set of characters to determine capitalization, null means whitespace
      Returns:
        capitalized String, `null` if null String input
      Since:
        2.1

    - #### uncapitalize

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

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

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

           WordUtils.uncapitalize(null)        = null
           WordUtils.uncapitalize("")          = ""
           WordUtils.uncapitalize("I Am FINE") = "i am fINE"

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

    - #### uncapitalize

          public static java.lang.String uncapitalize(java.lang.String str,
                                      char... delimiters)

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

      The delimiters represent a set of characters understood to separate words. The first string character and the first non-delimiter character after a delimiter will be uncapitalized.

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

           WordUtils.uncapitalize(null, *)            = null
           WordUtils.uncapitalize("", *)              = ""
           WordUtils.uncapitalize(*, null)            = *
           WordUtils.uncapitalize(*, new char[0])     = *
           WordUtils.uncapitalize("I AM.FINE", {'.'}) = "i AM.fINE"

      Parameters:
        `str` - the String to uncapitalize, may be null
        `delimiters` - set of characters to determine uncapitalization, null means whitespace
      Returns:
        uncapitalized String, `null` if null String input
      Since:
        2.1
      See Also:
        `capitalize(String)`

    - #### swapCase

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

      Swaps the case of a String using a word based algorithm.

      - Upper case character converts to Lower case
      - Title case character converts to Lower case
      - Lower case character after Whitespace or at start converts to Title case
      - Other Lower case character converts to Upper case

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

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

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

    - #### initials

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

      Extracts the initial characters from each word in the String.

      All first characters after whitespace are returned as a new string. Their case is not changed.

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

           WordUtils.initials(null)             = null
           WordUtils.initials("")               = ""
           WordUtils.initials("Ben John Lee")   = "BJL"
           WordUtils.initials("Ben J.Lee")      = "BJ"

      Parameters:
        `str` - the String to get initials from, may be null
      Returns:
        String of initial letters, `null` if null String input
      Since:
        2.2
      See Also:
        `initials(String,char[])`

    - #### initials

          public static java.lang.String initials(java.lang.String str,
                                  char... delimiters)

      Extracts the initial characters from each word in the String.

      All first characters after the defined delimiters are returned as a new string. Their case is not changed.

      If the delimiters array is null, then Whitespace is used. Whitespace is defined by `Character.isWhitespace(char)`. A `null` input String returns `null`. An empty delimiter array returns an empty String.

           WordUtils.initials(null, *)                = null
           WordUtils.initials("", *)                  = ""
           WordUtils.initials("Ben John Lee", null)   = "BJL"
           WordUtils.initials("Ben J.Lee", null)      = "BJ"
           WordUtils.initials("Ben J.Lee", [' ','.']) = "BJL"
           WordUtils.initials(*, new char[0])         = ""

      Parameters:
        `str` - the String to get initials from, may be null
        `delimiters` - set of characters to determine words, null means whitespace
      Returns:
        String of initial characters, `null` if null String input
      Since:
        2.2
      See Also:
        `initials(String)`

    - #### containsAllWords

          public static boolean containsAllWords(java.lang.CharSequence word,
                                 java.lang.CharSequence... words)

      Checks if the String contains all words in the given array.

      A `null` String will return `false`. A `null`, zero length search array or if one element of array is null will return `false`.

           WordUtils.containsAllWords(null, *)            = false
           WordUtils.containsAllWords("", *)              = false
           WordUtils.containsAllWords(*, null)            = false
           WordUtils.containsAllWords(*, [])              = false
           WordUtils.containsAllWords("abcd", "ab", "cd") = false
           WordUtils.containsAllWords("abc def", "def", "abc") = true

      Parameters:
        `word` - The CharSequence to check, may be null
        `words` - The array of String words to search for, may be null
      Returns:
        `true` if all search words are found, `false` otherwise
      Since:
        3.5