Class WordUtils
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
ConstructorsConstructorDescriptionWordUtilsinstances should NOT be constructed in standard programming. -
Method Summary
Modifier and TypeMethodDescriptionstatic Stringabbreviate(String str, int lower, int upper, String appendToEnd) Abbreviates the words nicely.static Stringcapitalize(String str) Capitalizes all the whitespace separated words in a String.static Stringcapitalize(String str, char... delimiters) Capitalizes all the delimiter separated words in a String.static StringcapitalizeFully(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 StringcapitalizeFully(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 booleancontainsAllWords(CharSequence word, CharSequence... words) Checks if the String contains all words in the given array.static StringExtracts the initial characters from each word in the String.static StringExtracts the initial characters from each word in the String.static booleanisDelimiter(char ch, char[] delimiters) Deprecated.as of 1.2 and will be removed in 2.0static booleanisDelimiter(int codePoint, char[] delimiters) Deprecated.as of 1.2 and will be removed in 2.0static StringSwaps the case of a String using a word based algorithm.static Stringuncapitalize(String str) Uncapitalizes all the whitespace separated words in a String.static Stringuncapitalize(String str, char... delimiters) Uncapitalizes all the whitespace separated words in a String.static StringWraps a single line of text, identifying words by' '.static StringWraps a single line of text, identifying words by' '.static StringWraps a single line of text, identifying words bywrapOn.
-
Constructor Details
-
WordUtils
public WordUtils()WordUtilsinstances should NOT be constructed in standard programming. Instead, the class should be used asWordUtils.wrap("foo bar", 20);.This constructor is public to permit tools that require a JavaBean instance to operate.
-
-
Method Details
-
abbreviate
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; negative value is treated as zero.upper- the upper limit; specify -1 if no limit is desired. The upper limit cannot be lower than 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
-
capitalize
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, usecapitalizeFully(String).Whitespace is defined by
Character.isWhitespace(char). Anullinput String returnsnull. 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,
nullif null String input - See Also:
-
capitalize
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, usecapitalizeFully(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
nullinput String returnsnull. 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 nulldelimiters- set of characters to determine capitalization, null means whitespace- Returns:
- capitalized String,
nullif null String input - See Also:
-
capitalizeFully
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). Anullinput String returnsnull. 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,
nullif null String input
-
capitalizeFully
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
nullinput String returnsnull. 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 nulldelimiters- set of characters to determine capitalization, null means whitespace- Returns:
- capitalized String,
nullif null String input
-
containsAllWords
Checks if the String contains all words in the given array.A
nullString will returnfalse. Anull, zero length search array or if one element of array is null will returnfalse.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 nullwords- The array of String words to search for, may be null- Returns:
trueif all search words are found,falseotherwise
-
initials
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). Anullinput String returnsnull.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,
nullif null String input - See Also:
-
initials
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). Anullinput String returnsnull. 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 nulldelimiters- set of characters to determine words, null means whitespace- Returns:
- String of initial characters,
nullif null String input - See Also:
-
isDelimiter
Deprecated.as of 1.2 and will be removed in 2.0Is the character a delimiter.- Parameters:
ch- the character to checkdelimiters- the delimiters- Returns:
- true if it is a delimiter
-
isDelimiter
Deprecated.as of 1.2 and will be removed in 2.0Is the codePoint a delimiter.- Parameters:
codePoint- the codePint to checkdelimiters- the delimiters- Returns:
- true if it is a delimiter
-
swapCase
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). Anullinput String returnsnull.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,
nullif null String input
-
uncapitalize
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). Anullinput String returnsnull.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,
nullif null String input - See Also:
-
uncapitalize
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). Anullinput String returnsnull.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 nulldelimiters- set of characters to determine uncapitalization, null means whitespace- Returns:
- uncapitalized String,
nullif null String input - See Also:
-
wrap
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.
(assuming that '\n' is the systems line separator)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" - Parameters:
str- the String to be word wrapped, may be nullwrapLength- the column to wrap the words at, less than 1 is treated as 1- Returns:
- a line with newlines inserted,
nullif null input
-
wrap
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- the String to be word wrapped, may be nullwrapLength- the column to wrap the words at, less than 1 is treated as 1newLineStr- the string to insert for a new line,nulluses the system property line separatorwrapLongWords- true if long words (such as URLs) should be wrapped- Returns:
- a line with newlines inserted,
nullif 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 bywrapOn.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- the String to be word wrapped, may be nullwrapLength- the column to wrap the words at, less than 1 is treated as 1newLineStr- the string to insert for a new line,nulluses the system property line separatorwrapLongWords- true if long words (such as URLs) should be wrappedwrapOn- 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,
nullif null input
-