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.

Since: 2.0

Version: $Id: WordUtils.java 471626 2006-11-06 04:02:09Z bayard $

Author: Apache Jakarta Velocity Stephen Colebourne Henning P. Schmiedehausen Gary Gregory

Constructor Summary
WordUtils()

WordUtils instances should NOT be constructed in standard programming.

Method Summary
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 Stringinitials(String str)

Extracts the initial letters from each word in the String.

The first letter of the string and all first letters after whitespace are returned as a new string.

static Stringinitials(String str, char[] delimiters)

Extracts the initial letters from each word in the String.

The first letter of the string and all first letters after the defined delimiters are returned as a new string.

static StringswapCase(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).

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 Stringwrap(String str, int wrapLength)

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

New lines will be separated by the system property line separator.

static Stringwrap(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.

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

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.

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 capitalizeFully

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 (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 capitalizeFully

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

initials

public static String initials(String str)

Extracts the initial letters from each word in the String.

The first letter of the string and all first letters 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: (String,char[])

initials

public static String initials(String str, char[] delimiters)

Extracts the initial letters from each word in the String.

The first letter of the string and all first letters 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 letters, null if null String input

Since: 2.2

See Also: initials

swapCase

public static String swapCase(String str)

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

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

See Also: capitalize

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

See Also: capitalize

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