org.apache.commons.text

## Class WordUtils

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

-     public class WordUtils
      extends 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 behavior in more detail.

  Since:
    1.1

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `abbreviate(String str, int lower, int upper, String appendToEnd)` Abbreviates the words nicely.
    `static String` | `capitalize(String str)` Capitalizes all the whitespace separated words in a String.
    `static String` | `capitalize(String str, char... delimiters)` Capitalizes all the delimiter separated words in a String.
    `static String` | `capitalizeFully(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 String` | `capitalizeFully(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(CharSequence word, CharSequence... words)` Checks if the String contains all words in the given array.
    `static String` | `initials(String str)` Extracts the initial characters from each word in the String.
    `static String` | `initials(String str, char... delimiters)` Extracts the initial characters from each word in the String.
    `static boolean` | `isDelimiter(char ch, char[] delimiters)` Deprecated. as of 1.2 and will be removed in 2.0
    `static boolean` | `isDelimiter(int codePoint, char[] delimiters)` Deprecated. as of 1.2 and will be removed in 2.0
    `static String` | `swapCase(String str)` Swaps the case of a String using a word based algorithm.
    `static String` | `uncapitalize(String str)` Uncapitalizes all the whitespace separated words in a String.
    `static String` | `uncapitalize(String str, char... delimiters)` Uncapitalizes all the whitespace separated words in a String.
    `static String` | `wrap(String str, int wrapLength)` Wraps a single line of text, identifying words by `' '`.
    `static String` | `wrap(String str, int wrapLength, String newLineStr, boolean wrapLongWords)` Wraps a single line of text, identifying words by `' '`.
    `static String` | `wrap(String str, int wrapLength, String newLineStr, boolean wrapLongWords, 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 String wrap(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.

      Examples
      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 - https://commons.apache.org" | 20 | "Click here to jump\nto the commons\nwebsite -\nhttps://commons.apache.org"
      "Click here, https://commons.apache.org, to jump to the commons website" | 20 | "Click here,\nhttps://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 String wrap(String str,
                                    int wrapLength,
                                    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.

      Examples
      input | wrapLength | 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 - https://commons.apache.org" | 20 | "\n" | false | "Click here to jump\nto the commons\nwebsite -\nhttps://commons.apache.org"
      "Click here to jump to the commons website - https://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 String wrap(String str,
                                    int wrapLength,
                                    String newLineStr,
                                    boolean wrapLongWords,
                                    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.

      Examples
      input | wrapLength | 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 - https://commons.apache.org" | 20 | "\n" | false | " " | "Click here to jump\nto the commons\nwebsite -\nhttps://commons.apache.org"
      "Click here to jump to the commons website - https://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 String capitalize(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 String capitalize(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"
           WordUtils.capitalize("i am fine", new char[]{}) = "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
      See Also:
        `uncapitalize(String)`, `capitalizeFully(String)`

    - #### capitalizeFully

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

    - #### uncapitalize

          public static String uncapitalize(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 String uncapitalize(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"
           WordUtils.uncapitalize("I am fine", new char[]{}) = "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
      See Also:
        `capitalize(String)`

    - #### swapCase

          public static String swapCase(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 String initials(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
      See Also:
        `initials(String,char[])`

    - #### initials

          public static String initials(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
      See Also:
        `initials(String)`

    - #### containsAllWords

          public static boolean containsAllWords(CharSequence word,
                                                 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

    - #### isDelimiter

          @Deprecated
          public static boolean isDelimiter(char ch,
                                                         char[] delimiters)

      Deprecated. as of 1.2 and will be removed in 2.0
      Is the character a delimiter.
      Parameters:
        `ch` - the character to check
        `delimiters` - the delimiters
      Returns:
        true if it is a delimiter

    - #### isDelimiter

          @Deprecated
          public static boolean isDelimiter(int codePoint,
                                                         char[] delimiters)

      Deprecated. as of 1.2 and will be removed in 2.0
      Is the codePoint a delimiter.
      Parameters:
        `codePoint` - the codePint to check
        `delimiters` - the delimiters
      Returns:
        true if it is a delimiter

    - #### abbreviate

          public static String abbreviate(String str,
                                          int lower,
                                          int upper,
                                          String appendToEnd)

      Abbreviates the words nicely. This method searches for the first space after the lower limit and abbreviates the String there. It will also append any String passed as a parameter to the end of the String. The upper limit can be specified to forcibly abbreviate a String.
      Parameters:
        `str` - the string to be abbreviated. If null is passed, null is returned. If the empty String is passed, the empty string is returned.
        `lower` - the lower limit.
        `upper` - the upper limit; specify -1 if no limit is desired. If the upper limit is lower than the lower limit, it will be adjusted to be the same as the lower limit.
        `appendToEnd` - String to be appended to the end of the abbreviated string. This is appended ONLY if the string was indeed abbreviated. The append does not count towards the lower or upper limits.
      Returns:
        The abbreviated String.

             WordUtils.abbreviate("Now is the time for all good men", 0, 40, null));     = "Now"
             WordUtils.abbreviate("Now is the time for all good men", 10, 40, null));    = "Now is the"
             WordUtils.abbreviate("Now is the time for all good men", 20, 40, null));    = "Now is the time for all"
             WordUtils.abbreviate("Now is the time for all good men", 0, 40, ""));       = "Now"
             WordUtils.abbreviate("Now is the time for all good men", 10, 40, ""));      = "Now is the"
             WordUtils.abbreviate("Now is the time for all good men", 20, 40, ""));      = "Now is the time for all"
             WordUtils.abbreviate("Now is the time for all good men", 0, 40, " ..."));   = "Now ..."
             WordUtils.abbreviate("Now is the time for all good men", 10, 40, " ..."));  = "Now is the ..."
             WordUtils.abbreviate("Now is the time for all good men", 20, 40, " ..."));  = "Now is the time for all ..."
             WordUtils.abbreviate("Now is the time for all good men", 0, -1, ""));       = "Now"
             WordUtils.abbreviate("Now is the time for all good men", 10, -1, ""));      = "Now is the"
             WordUtils.abbreviate("Now is the time for all good men", 20, -1, ""));      = "Now is the time for all"
             WordUtils.abbreviate("Now is the time for all good men", 50, -1, ""));      = "Now is the time for all good men"
             WordUtils.abbreviate("Now is the time for all good men", 1000, -1, ""));    = "Now is the time for all good men"
             WordUtils.abbreviate("Now is the time for all good men", 9, -10, null));    = IllegalArgumentException
             WordUtils.abbreviate("Now is the time for all good men", 10, 5, null));     = IllegalArgumentException

Copyright © 2014–2020 The Apache Software Foundation. All rights reserved.