org.apache.commons.lang

Class 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 behaviour in more detail.

Version:
$Id: WordUtils.java 161678 2005-04-17 18:42:40Z mvdb $
Authors:
Apache Jakarta Velocity
Henri Yandell
Stephen Colebourne
Henning P. Schmiedehausen
Gary Gregory
Since:
2.0

Constructor Summary

WordUtils()
WordUtils instances should NOT be constructed in standard programming.

Method Summary

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

Constructor Details

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 Details

capitalize

public static String capitalize(String str)
Capitalizes all the whitespace separated words in a String. Only the first letter 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

capitalize

public static String capitalize(String str,
                                char[] delimiters)
Capitalizes all the delimiter separated words in a String. Only the first letter 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

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
Since:
2.1

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

uncapitalize

public static String uncapitalize(String str)
Uncapitalizes all the whitespace separated words in a String. Only the first letter 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

uncapitalize

public static String uncapitalize(String str,
                                  char[] delimiters)
Uncapitalizes all the whitespace separated words in a String. Only the first letter 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

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.

 WordUtils.wrap(null, *) = null
 WordUtils.wrap("", *) = ""
 
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.

 WordUtils.wrap(null, *, *, *) = null
 WordUtils.wrap("", *, *, *) = ""
 
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

Copyright © 2001-2005 - Apache Software Foundation