Top Description Constructors Methods
org.apache.commons.text

public Class WordUtils

extends Object
Class Inheritance
Imports
java.util.HashSet, .Set, java.util.function.Predicate, java.util.regex.Matcher, .Pattern, org.apache.commons.lang3.ArrayUtils, .StringUtils, .Strings, .Validate
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

AccessConstructor and Description
public
WordUtils()

WordUtils instances should NOT be constructed in standard programming.

Method Summary

Modifier and TypeMethod and Description
public static String

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));    = Throws IllegalArgumentException
WordUtils.abbreviate("Now is the time for all good men", 10, 5, null));     = Throws IllegalArgumentException
abbreviate(final String
the string to be abbreviated. If null is passed, null is returned. If the empty String is passed, the empty string is returned.
str, int
the lower limit; negative value is treated as zero.
lower, int
the upper limit; specify -1 if no limit is desired. The upper limit cannot be lower than the lower limit.
upper, final String
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.
appendToEnd)

Abbreviates the words nicely.

public static String

Returns:

capitalized String, null if null String input.
capitalize(final String
the String to capitalize, may be null.
str)

Capitalizes all the whitespace separated words in a String.

public static String

Returns:

capitalized String, null if null String input.
capitalize(final String
the String to capitalize, may be null.
str, final char...
set of characters to determine capitalization, null means whitespace.
delimiters)

Capitalizes all the delimiter separated words in a String.

public static String

Returns:

capitalized String, null if null String input.
capitalizeFully(final String
the String to capitalize, may be null.
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.

public static String

Returns:

capitalized String, null if null String input.
capitalizeFully(String
the String to capitalize, may be null.
str, final char...
set of characters to determine capitalization, null means whitespace.
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.

public static boolean

Returns:

true if all search words are found, false otherwise.
containsAllWords(final CharSequence
The CharSequence to check, may be null.
word, final CharSequence...
The array of String words to search for, may be null.
words)

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

private static Predicate<Integer>

Returns:

Predicate taking a code point value as an argument and returning true if a delimiter.
generateIsDelimiterFunction(final char[]
set of characters to determine delimiters, null means whitespace.
delimiters)

Given the array of delimiters supplied; returns a function determining whether a character code point is a delimiter.

public static String

Returns:

String of initial letters, null if null String input.
initials(final String
the String to get initials from, may be null.
str)

Extracts the initial characters from each word in the String.

public static String

Returns:

String of initial characters, null if null String input.
initials(final String
the String to get initials from, may be null.
str, final char...
set of characters to determine words, null means whitespace.
delimiters)

Extracts the initial characters from each word in the String.

public static boolean

Returns:

true if it is a delimiter.
isDelimiter(final char
the character to check.
ch, final char[]
the delimiters.
delimiters)
Deprecated as of 1.2 and will be removed in 2.0.

Is the character a delimiter.

public static boolean

Returns:

true if it is a delimiter.
isDelimiter(final int
the codePint to check.
codePoint, final char[]
the delimiters.
delimiters)
Deprecated as of 1.2 and will be removed in 2.0.

Is the codePoint a delimiter.

public static String

Returns:

The changed String, null if null String input.
swapCase(final String
the String to swap case, may be null.
str)

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

public static String

Returns:

uncapitalized String, null if null String input.
uncapitalize(final String
the String to uncapitalize, may be null.
str)

Uncapitalizes all the whitespace separated words in a String.

public static String

Returns:

uncapitalized String, null if null String input.
uncapitalize(final String
the String to uncapitalize, may be null.
str, final char...
set of characters to determine uncapitalization, null means whitespace.
delimiters)

Uncapitalizes all the whitespace separated words in a String.

public static String

Returns:

a line with newlines inserted, null if null input.
wrap(final String
the String to be word wrapped, may be null.
str, final int
the column to wrap the words at, less than 1 is treated as 1.
wrapLength)

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

public static String

Returns:

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

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

public static String

Returns:

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

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

WordUtilsback to summary
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

abbreviateback to summary
public static String abbreviate(final String str, int lower, int upper, final 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:String

the string to be abbreviated. If null is passed, null is returned. If the empty String is passed, the empty string is returned.

lower:int

the lower limit; negative value is treated as zero.

upper:int

the upper limit; specify -1 if no limit is desired. The upper limit cannot be lower than the lower limit.

appendToEnd:String

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

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));    = Throws IllegalArgumentException
WordUtils.abbreviate("Now is the time for all good men", 10, 5, null));     = Throws IllegalArgumentException
capitalizeback to summary
public static String capitalize(final 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:String

the String to capitalize, may be null.

Returns:String

capitalized String, null if null String input.

See Also
uncapitalize(String), capitalizeFully(String)
capitalizeback to summary
public static String capitalize(final String str, final 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:String

the String to capitalize, may be null.

delimiters:char[]

set of characters to determine capitalization, null means whitespace.

Returns:String

capitalized String, null if null String input.

See Also
uncapitalize(String), capitalizeFully(String)
capitalizeFullyback to summary
public static String capitalizeFully(final 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:String

the String to capitalize, may be null.

Returns:String

capitalized String, null if null String input.

capitalizeFullyback to summary
public static String capitalizeFully(String str, final 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:String

the String to capitalize, may be null.

delimiters:char[]

set of characters to determine capitalization, null means whitespace.

Returns:String

capitalized String, null if null String input.

containsAllWordsback to summary
public static boolean containsAllWords(final CharSequence word, final 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:CharSequence

The CharSequence to check, may be null.

words:CharSequence[]

The array of String words to search for, may be null.

Returns:boolean

true if all search words are found, false otherwise.

generateIsDelimiterFunctionback to summary
private static Predicate<Integer> generateIsDelimiterFunction(final char[] delimiters)

Given the array of delimiters supplied; returns a function determining whether a character code point is a delimiter. The function provides O(1) lookup time. Whitespace is defined by Character#isWhitespace(char) and is used as the defaultvalue if delimiters is null.

Parameters
delimiters:char[]

set of characters to determine delimiters, null means whitespace.

Returns:Predicate<Integer>

Predicate taking a code point value as an argument and returning true if a delimiter.

initialsback to summary
public static String initials(final 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:String

the String to get initials from, may be null.

Returns:String

String of initial letters, null if null String input.

See Also
initials(String, char[])
initialsback to summary
public static String initials(final String str, final 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:String

the String to get initials from, may be null.

delimiters:char[]

set of characters to determine words, null means whitespace.

Returns:String

String of initial characters, null if null String input.

See Also
initials(String)
isDelimiterback to summary
public static boolean isDelimiter(final char ch, final char[] delimiters)

Deprecated

as of 1.2 and will be removed in 2.0.

Is the character a delimiter.

Parameters
ch:char

the character to check.

delimiters:char[]

the delimiters.

Returns:boolean

true if it is a delimiter.

Annotations
@Deprecated
isDelimiterback to summary
public static boolean isDelimiter(final int codePoint, final char[] delimiters)

Deprecated

as of 1.2 and will be removed in 2.0.

Is the codePoint a delimiter.

Parameters
codePoint:int

the codePint to check.

delimiters:char[]

the delimiters.

Returns:boolean

true if it is a delimiter.

Annotations
@Deprecated
swapCaseback to summary
public static String swapCase(final 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:String

the String to swap case, may be null.

Returns:String

The changed String, null if null String input.

uncapitalizeback to summary
public static String uncapitalize(final 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:String

the String to uncapitalize, may be null.

Returns:String

uncapitalized String, null if null String input.

See Also
capitalize(String)
uncapitalizeback to summary
public static String uncapitalize(final String str, final 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:String

the String to uncapitalize, may be null.

delimiters:char[]

set of characters to determine uncapitalization, null means whitespace.

Returns:String

uncapitalized String, null if null String input.

See Also
capitalize(String)
wrapback to summary
public static String wrap(final String str, final 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:String

the String to be word wrapped, may be null.

wrapLength:int

the column to wrap the words at, less than 1 is treated as 1.

Returns:String

a line with newlines inserted, null if null input.

wrapback to summary
public static String wrap(final String str, final int wrapLength, final String newLineStr, final 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 -\nhttps://commons.apach\ne.org"
Parameters
str:String

the String to be word wrapped, may be null.

wrapLength:int

the column to wrap the words at, less than 1 is treated as 1.

newLineStr:String

the string to insert for a new line, null uses the system property line separator.

wrapLongWords:boolean

true if long words (such as URLs) should be wrapped.

Returns:String

a line with newlines inserted, null if null input.

wrapback to summary
public static String wrap(final String str, int wrapLength, String newLineStr, final 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 -\nhttps://commons.apach\ne.org"
"flammable/inflammable" 20 "\n" true "/" "flammable\ninflammable"
Parameters
str:String

the String to be word wrapped, may be null.

wrapLength:int

the column to wrap the words at, less than 1 is treated as 1.

newLineStr:String

the string to insert for a new line, null uses the system property line separator.

wrapLongWords:boolean

true if long words (such as URLs) should be wrapped.

wrapOn:String

regex expression to be used as a breakable characters, if blank string is provided a space character will be used.

Returns:String

a line with newlines inserted, null if null input.