org.apache.commons.lang

Class StringUtils


public class StringUtils
extends java.lang.Object

Operations on java.lang.String that are null safe.

The StringUtils class defines certain words related to String handling.

StringUtils handles null input Strings quietly. That is to say that a null input will return null. Where a boolean or int is being returned details vary by method.

A side effect of the null handling is that a NullPointerException should be considered a bug in StringUtils (except for deprecated methods).

Methods in this class give sample code to explain their operation. The symbol * is used to indicate any input including null.

Version:
$Id: StringUtils.java,v 1.107 2003/08/23 10:39:20 scolebourne Exp $

Authors:
Apache Jakarta Turbine
GenerationJavaCore
Jon S. Stevens
Daniel Rall
Greg Coladonato
Henri Yandell
Ed Korthof
Rand McNeely
Stephen Colebourne
Fredrik Westermarck
Holger Krauth
Alexander Day Chaffee
Henning P. Schmiedehausen
Arun Mammen Thomas
Gary Gregory
Phil Steitz

Since:
1.0

See Also:
java.lang.String

Field Summary

static String
EMPTY
The empty String "".

Constructor Summary

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

Method Summary

static String
abbreviate(String str, int maxWidth)
Abbreviates a String using ellipses.
static String
abbreviate(String str, int offset, int maxWidth)
Abbreviates a String using ellipses.
static String
capitalise(String str)
Deprecated. Use the standardly named capitalize(String).
static String
capitaliseAllWords(String str)
Deprecated. Use the relocated WordUtils.capitalize(String).
static String
capitalize(String str)
Capitalizes a String changing the first letter to title case as per Character.toTitleCase(char).
static String
center(String str, int size)
Centers a String in a larger String of size size using the space character (' ').
static String
center(String str, int size, String padStr)
Centers a String in a larger String of size size.
static String
center(String str, int size, char padChar)
Centers a String in a larger String of size size.
static String
chomp(String str)
Removes one newline from end of a String if it's there, otherwise leave it alone.
static String
chomp(String str, String separator)
Removes separator from the end of str if it's there, otherwise leave it alone.
static String
chompLast(String str)
Deprecated. Use chomp(String) instead.
static String
chompLast(String str, String sep)
Deprecated. Use chomp(String,String) instead.
static String
chop(String str)
Remove the last character from a String.
static String
chopNewline(String str)
Deprecated. Use chomp(String) instead.
static String
clean(String str)
Deprecated. Use the clearer named trimToEmpty(String).
static String
concatenate(Object[] array)
Deprecated. Use the better named join(Object[]) instead.
static boolean
contains(String str, String searchStr)
Find the first index within a String, handling null.
static boolean
contains(String str, char searchChar)
Checks if String contains a search character, handling null.
static boolean
containsNone(String str, String invalidChars)
Checks that the String does not contain certain characters.
static boolean
containsNone(String str, char[] invalidChars)
Checks that the String does not contain certain characters.
static boolean
containsOnly(String str, String validChars)
Checks if the String contains only certain characters.
static boolean
containsOnly(String str, char[] valid)
Checks if the String contains only certain characters.
static int
countMatches(String str, String sub)
Counts how many times the substring appears in the larger String.
static String
defaultString(String str)
Returns either the passed in String, or if the String is null, an empty String ("").
static String
defaultString(String str, String defaultStr)
Returns either the passed in String, or if the String is null, an empty String ("").
static String
deleteSpaces(String str)
Deprecated. Use the better localized deleteWhitespace(String).
static String
deleteWhitespace(String str)
Deletes all whitespaces from a String as defined by Character.isWhitespace(char).
static String
difference(String str1, String str2)
Compares two Strings, and returns the portion where they differ.
static boolean
equals(String str1, String str2)
Compares two Strings, returning true if they are equal.
static boolean
equalsIgnoreCase(String str1, String str2)
Compares two Strings, returning true if they are equal ignoring the case.
static String
escape(String str)
Deprecated. Use StringEscapeUtils.escapeJava(String) This method will be removed in Commons Lang 3.0
static String
getChomp(String str, String sep)
Deprecated. Use substringAfterLast(String,String) instead (although this doesn't include the separator) Method will be removed in Commons Lang 3.0.
static int
getLevenshteinDistance(String s, String t)
Find the Levenshtein distance between two Strings.
static String
getNestedString(String str, String tag)
Deprecated. Use the better named substringBetween(String,String).
static String
getNestedString(String str, String open, String close)
Deprecated. Use the better named substringBetween(String,String,String).
static String
getPrechomp(String str, String sep)
Deprecated. Use substringBefore(String,String) instead (although this doesn't include the separator).
static int
indexOf(String str, String searchStr)
Finds the first index within a String, handling null.
static int
indexOf(String str, String searchStr, int startPos)
Finds the first index within a String, handling null.
static int
indexOf(String str, char searchChar)
Finds the first index within a String, handling null.
static int
indexOf(String str, char searchChar, int startPos)
Finds the first index within a String from a start position, handling null.
static int
indexOfAny(String str, String searchChars)
Search a String to find the first index of any character in the given set of characters.
static int
indexOfAny(String str, String[] searchStrs)
Find the first index of any of a set of potential substrings.
static int
indexOfAny(String str, char[] searchChars)
Search a String to find the first index of any character in the given set of characters.
static int
indexOfAnyBut(String str, String searchChars)
Search a String to find the first index of any character not in the given set of characters.
static int
indexOfAnyBut(String str, char[] searchChars)
Search a String to find the first index of any character not in the given set of characters.
static int
indexOfDifference(String str1, String str2)
Compares two Strings, and returns the index at which the Strings begin to differ.
static boolean
isAlpha(String str)
Checks if the String contains only unicode letters.
static boolean
isAlphaSpace(String str)
Checks if the String contains only unicode letters and space (' ').
static boolean
isAlphanumeric(String str)
Checks if the String contains only unicode letters or digits.
static boolean
isAlphanumericSpace(String str)
Checks if the String contains only unicode letters, digits or space (' ').
static boolean
isBlank(String str)
Checks if a String is whitespace, empty ("") or null.
static boolean
isEmpty(String str)
Checks if a String is empty ("") or null.
static boolean
isNotBlank(String str)
Checks if a String is not empty (""), not null and not whitespace only.
static boolean
isNotEmpty(String str)
Checks if a String is not empty ("") and not null.
static boolean
isNumeric(String str)
Checks if the String contains only unicode digits.
static boolean
isNumericSpace(String str)
Checks if the String contains only unicode digits or space (' ').
static boolean
isWhitespace(String str)
Checks if the String contains only whitespace.
static String
join(Iterator iterator, String separator)
Joins the elements of the provided Iterator into a single String containing the provided elements.
static String
join(Iterator iterator, char separator)
Joins the elements of the provided Iterator into a single String containing the provided elements.
static String
join(Object[] array)
Joins the elements of the provided array into a single String containing the provided list of elements.
static String
join(Object[] array, String separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
static String
join(Object[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
static int
lastIndexOf(String str, String searchStr)
Finds the last index within a String, handling null.
static int
lastIndexOf(String str, String searchStr, int startPos)
Finds the first index within a String, handling null.
static int
lastIndexOf(String str, char searchChar)
Finds the last index within a String, handling null.
static int
lastIndexOf(String str, char searchChar, int startPos)
Finds the last index within a String from a start position, handling null.
static int
lastIndexOfAny(String str, String[] searchStrs)
Find the latest index of any of a set of potential substrings.
static String
left(String str, int len)
Gets the leftmost len characters of a String.
static String
leftPad(String str, int size)
Left pad a String with spaces (' ').
static String
leftPad(String str, int size, String padStr)
Left pad a String with a specified String.
static String
leftPad(String str, int size, char padChar)
Left pad a String with a specified character.
static String
lowerCase(String str)
Converts a String to lower case as per String.toLowerCase().
static String
mid(String str, int pos, int len)
Gets len characters from the middle of a String.
static String
overlay(String str, String overlay, int start, int end)
Overlays part of a String with another String.
static String
overlayString(String text, String overlay, int start, int end)
Deprecated. Use better named overlay(String,String,int,int) instead.
static String
prechomp(String str, String sep)
Deprecated. Use substringAfter(String,String) instead.
static String
repeat(String str, int repeat)
Repeat a String repeat times to form a new String.
static String
replace(String text, String repl, String with)
Replaces all occurances of a String within another String.
static String
replace(String text, String repl, String with, int max)
Replaces a String with another String inside a larger String, for the first max values of the search String.
static String
replaceChars(String str, String searchChars, String replaceChars)
Replaces multiple characters in a String in one go.
static String
replaceChars(String str, char searchChar, char replaceChar)
Replaces all occurrances of a character in a String with another.
static String
replaceOnce(String text, String repl, String with)
Replaces a String with another String inside a larger String, once.
static String
reverse(String str)
Reverses a String as per StringBuffer.reverse().
static String
reverseDelimited(String str, char separatorChar)
Reverses a String that is delimited by a specific character.
static String
reverseDelimitedString(String str, String separatorChars)
Deprecated. Use reverseDelimited(String,char) instead.
static String
right(String str, int len)
Gets the rightmost len characters of a String.
static String
rightPad(String str, int size)
Right pad a String with spaces (' ').
static String
rightPad(String str, int size, String padStr)
Right pad a String with a specified String.
static String
rightPad(String str, int size, char padChar)
Right pad a String with a specified character.
static String[]
split(String str)
Splits the provided text into an array, using whitespace as the separator.
static String[]
split(String str, String separatorChars)
Splits the provided text into an array, separators specified.
static String[]
split(String str, String separatorChars, int max)
Splits the provided text into an array, separators specified.
static String[]
split(String str, char separatorChar)
Splits the provided text into an array, separator specified.
static String
strip(String str)
Strips whitespace from the start and end of a String.
static String
strip(String str, String stripChars)
Strips any of a set of characters from the start and end of a String.
static String[]
stripAll(String[] strs)
Strips whitespace from the start and end of every String in an array.
static String[]
stripAll(String[] strs, String stripChars)
Strips any of a set of characters from the start and end of every String in an array.
static String
stripEnd(String str, String stripChars)
Strips any of a set of characters from the end of a String.
static String
stripStart(String str, String stripChars)
Strips any of a set of characters from the start of a String.
static String
stripToEmpty(String str)
Strips whitespace from the start and end of a String returning an empty String if null input.
static String
stripToNull(String str)
Strips whitespace from the start and end of a String returning null if the String is empty ("") after the strip.
static String
substring(String str, int start)
Gets a substring from the specified String avoiding exceptions.
static String
substring(String str, int start, int end)
Gets a substring from the specified String avoiding exceptions.
static String
substringAfter(String str, String separator)
Gets the substring after the first occurance of a separator.
static String
substringAfterLast(String str, String separator)
Gets the substring after the last occurance of a separator.
static String
substringBefore(String str, String separator)
Gets the substring before the first occurance of a separator.
static String
substringBeforeLast(String str, String separator)
Gets the substring before the last occurance of a separator.
static String
substringBetween(String str, String tag)
Gets the String that is nested in between two instances of the same String.
static String
substringBetween(String str, String open, String close)
Gets the String that is nested in between two Strings.
static String
swapCase(String str)
Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
static String
trim(String str)
Removes control characters (char <= 32) from both ends of this String, handling null by returning null.
static String
trimToEmpty(String str)
Removes control characters (char <= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if it is null.
static String
trimToNull(String str)
Removes control characters (char <= 32) from both ends of this String returning null if the String is empty ("") after the trim or if it is null.
static String
uncapitalise(String str)
Deprecated. Use the standardly named uncapitalize(String).
static String
uncapitalize(String str)
Uncapitalizes a String changing the first letter to title case as per Character.toLowerCase(char).
static String
upperCase(String str)
Converts a String to upper case as per String.toUpperCase().

Field Details

EMPTY

public static final String EMPTY
The empty String "".

Since:
2.0

Constructor Details

StringUtils

public StringUtils()
StringUtils instances should NOT be constructed in standard programming. Instead, the class should be used as StringUtils.trim(" foo ");.

This constructor is public to permit tools that require a JavaBean instance to operate.

Method Details

abbreviate

public static String abbreviate(String str,
                                int maxWidth)
Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "Now is the time for..."

Specifically:

  • If str is less than maxWidth characters long, return it.
  • Else abbreviate it to (substring(str, 0, max-3) + "...").
  • If maxWidth is less than 4, throw an IllegalArgumentException.
  • In no case will it return a String of length greater than maxWidth.
 StringUtils.abbreviate(null, *)      = null
 StringUtils.abbreviate("", 4)        = ""
 StringUtils.abbreviate("abcdefg", 6) = "abc..."
 StringUtils.abbreviate("abcdefg", 7) = "abcdefg"
 StringUtils.abbreviate("abcdefg", 8) = "abcdefg"
 StringUtils.abbreviate("abcdefg", 4) = "a..."
 StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException
 

Parameters:
str - the String to check, may be null
maxWidth - maximum length of result String, must be at least 4

Returns:
abbreviated String, null if null String input

Since:
2.0


abbreviate

public static String abbreviate(String str,
                                int offset,
                                int maxWidth)
Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "...is the time for..."

Works like abbreviate(String, int), but allows you to specify a "left edge" offset. Note that this left edge is not necessarily going to be the leftmost character in the result, or the first character following the ellipses, but it will appear somewhere in the result.

In no case will it return a String of length greater than maxWidth.

 StringUtils.abbreviate(null, *, *)                = null
 StringUtils.abbreviate("", 0, 4)                  = ""
 StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..."
 StringUtils.abbreviate("abcdefghijklmno", 0, 10)  = "abcdefg..."
 StringUtils.abbreviate("abcdefghijklmno", 1, 10)  = "abcdefg..."
 StringUtils.abbreviate("abcdefghijklmno", 4, 10)  = "abcdefg..."
 StringUtils.abbreviate("abcdefghijklmno", 5, 10)  = "...fghi..."
 StringUtils.abbreviate("abcdefghijklmno", 6, 10)  = "...ghij..."
 StringUtils.abbreviate("abcdefghijklmno", 8, 10)  = "...ijklmno"
 StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno"
 StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno"
 StringUtils.abbreviate("abcdefghij", 0, 3)        = IllegalArgumentException
 StringUtils.abbreviate("abcdefghij", 5, 6)        = IllegalArgumentException
 

Parameters:
str - the String to check, may be null
offset - left edge of source String
maxWidth - maximum length of result String, must be at least 4

Returns:
abbreviated String, null if null String input

Since:
2.0


capitalise

public static String capitalise(String str)

Deprecated. Use the standardly named capitalize(String). Method will be removed in Commons Lang 3.0.

Capitalizes a String changing the first letter to title case as per Character.toTitleCase(char). No other letters are changed.

Parameters:
str - the String to capitalize, may be null

Returns:
the capitalized String, null if null String input


capitaliseAllWords

public static String capitaliseAllWords(String str)

Deprecated. Use the relocated WordUtils.capitalize(String). Method will be removed in Commons Lang 3.0.

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

Parameters:
str - the String to capitalize, may be null

Returns:
capitalized String, null if null String input


capitalize

public static String capitalize(String str)
Capitalizes a String changing the first letter to title case as per Character.toTitleCase(char). No other letters are changed.

For a word based alorithm, see WordUtils.capitalize(String). A null input String returns null.

 StringUtils.capitalize(null)  = null
 StringUtils.capitalize("")    = ""
 StringUtils.capitalize("cat") = "Cat"
 StringUtils.capitalize("cAt") = "CAt"
 

Parameters:
str - the String to capitalize, may be null

Returns:
the capitalized String, null if null String input

Since:
2.0

See Also:
WordUtils.capitalize(String), uncapitalize(String)


center

public static String center(String str,
                            int size)
Centers a String in a larger String of size size using the space character (' ').

If the size is less than the String length, the String is returned. A null String returns null. A negative size is treated as zero.

Equivalent to center(str, size, " ").

 StringUtils.center(null, *)   = null
 StringUtils.center("", 4)     = "    "
 StringUtils.center("ab", -1)  = "ab"
 StringUtils.center("ab", 4)   = " ab "
 StringUtils.center("abcd", 2) = "abcd"
 StringUtils.center("a", 4)    = " a  "
 

Parameters:
str - the String to center, may be null
size - the int size of new String, negative treated as zero

Returns:
centered String, null if null String input


center

public static String center(String str,
                            int size,
                            String padStr)
Centers a String in a larger String of size size. Uses a supplied String as the value to pad the String with.

If the size is less than the String length, the String is returned. A null String returns null. A negative size is treated as zero.

 StringUtils.center(null, *, *)     = null
 StringUtils.center("", 4, " ")     = "    "
 StringUtils.center("ab", -1, " ")  = "ab"
 StringUtils.center("ab", 4, " ")   = " ab"
 StringUtils.center("abcd", 2, " ") = "abcd"
 StringUtils.center("a", 4, " ")    = " a  "
 StringUtils.center("a", 4, "yz")   = "yayz"
 StringUtils.center("abc", 7, null) = "  abc  "
 StringUtils.center("abc", 7, "")   = "  abc  "
 

Parameters:
str - the String to center, may be null
size - the int size of new String, negative treated as zero
padStr - the String to pad the new String with, must not be null or empty

Returns:
centered String, null if null String input


center

public static String center(String str,
                            int size,
                            char padChar)
Centers a String in a larger String of size size. Uses a supplied character as the value to pad the String with.

If the size is less than the String length, the String is returned. A null String returns null. A negative size is treated as zero.

 StringUtils.center(null, *, *)     = null
 StringUtils.center("", 4, ' ')     = "    "
 StringUtils.center("ab", -1, ' ')  = "ab"
 StringUtils.center("ab", 4, ' ')   = " ab"
 StringUtils.center("abcd", 2, ' ') = "abcd"
 StringUtils.center("a", 4, ' ')    = " a  "
 StringUtils.center("a", 4, 'y')    = "yayy"
 

Parameters:
str - the String to center, may be null
size - the int size of new String, negative treated as zero
padChar - the character to pad the new String with

Returns:
centered String, null if null String input

Since:
2.0


chomp

public static String chomp(String str)
Removes one newline from end of a String if it's there, otherwise leave it alone. A newline is "\n", "\r", or "\r\n".

NOTE: This method changed in 2.0. It now more closely matches Perl chomp.

 StringUtils.chomp(null)          = null
 StringUtils.chomp("")            = ""
 StringUtils.chomp("abc \r")      = "abc "
 StringUtils.chomp("abc\n")       = "abc"
 StringUtils.chomp("abc\r\n")     = "abc"
 StringUtils.chomp("abc\r\n\r\n") = "abc\r\n"
 StringUtils.chomp("abc\n\r")     = "abc\n"
 StringUtils.chomp("abc\n\rabc")  = "abc\n\rabc"
 StringUtils.chomp("\r")          = ""
 StringUtils.chomp("\n")          = ""
 StringUtils.chomp("\r\n")        = ""
 

Parameters:
str - the String to chomp a newline from, may be null

Returns:
String without newline, null if null String input


chomp

public static String chomp(String str,
                           String separator)
Removes separator from the end of str if it's there, otherwise leave it alone.

NOTE: This method changed in version 2.0. It now more closely matches Perl chomp. For the previous behavior, use substringBeforeLast(String,String). This method uses String.endsWith(String).

 StringUtils.chomp(null, *)         = null
 StringUtils.chomp("", *)           = ""
 StringUtils.chomp("foobar", "bar") = "foo"
 StringUtils.chomp("foobar", "baz") = "foobar"
 StringUtils.chomp("foo", "foo")    = ""
 StringUtils.chomp("foo ", "foo")   = "foo"
 StringUtils.chomp(" foo", "foo")   = " "
 StringUtils.chomp("foo", "foooo")  = "foo"
 StringUtils.chomp("foo", "")       = "foo"
 StringUtils.chomp("foo", null)     = "foo"
 

Parameters:
str - the String to chomp from, may be null
separator - separator String, may be null

Returns:
String without trailing separator, null if null String input


chompLast

public static String chompLast(String str)

Deprecated. Use chomp(String) instead. Method will be removed in Commons Lang 3.0.

Remove any "\n" if and only if it is at the end of the supplied String.

Parameters:
str - the String to chomp from, must not be null

Returns:
String without chomped ending


chompLast

public static String chompLast(String str,
                               String sep)

Deprecated. Use chomp(String,String) instead. Method will be removed in Commons Lang 3.0.

Remove a value if and only if the String ends with that value.

Parameters:
str - the String to chomp from, must not be null
sep - the String to chomp, must not be null

Returns:
String without chomped ending


chop

public static String chop(String str)
Remove the last character from a String.

If the String ends in \r\n, then remove both of them.

 StringUtils.chop(null)          = null
 StringUtils.chop("")            = ""
 StringUtils.chop("abc \r")      = "abc "
 StringUtils.chop("abc\n")       = "abc"
 StringUtils.chop("abc\r\n")     = "abc"
 StringUtils.chop("abc")         = "ab"
 StringUtils.chop("abc\nabc")    = "abc\nab"
 StringUtils.chop("a")           = ""
 StringUtils.chop("\r")          = ""
 StringUtils.chop("\n")          = ""
 StringUtils.chop("\r\n")        = ""
 

Parameters:
str - the String to chop last character from, may be null

Returns:
String without last character, null if null String input


chopNewline

public static String chopNewline(String str)

Deprecated. Use chomp(String) instead. Method will be removed in Commons Lang 3.0.

Removes \n from end of a String if it's there. If a \r precedes it, then remove that too.

Parameters:
str - the String to chop a newline from, must not be null

Returns:
String without newline


clean

public static String clean(String str)

Deprecated. Use the clearer named trimToEmpty(String). Method will be removed in Commons Lang 3.0.

Removes control characters (char <= 32) from both ends of this String, handling null by returning an empty String ("").
 StringUtils.clean(null)          = ""
 StringUtils.clean("")            = ""
 StringUtils.clean("abc")         = "abc"
 StringUtils.clean("    abc    ") = "abc"
 StringUtils.clean("     ")       = ""
 

Parameters:
str - the String to clean, may be null

Returns:
the trimmed text, never null

See Also:
java.lang.String.trim()


concatenate

public static String concatenate(Object[] array)

Deprecated. Use the better named join(Object[]) instead. Method will be removed in Commons Lang 3.0.

Concatenates elements of an array into a single String. Null objects or empty strings within the array are represented by empty strings.
 StringUtils.concatenate(null)            = null
 StringUtils.concatenate([])              = ""
 StringUtils.concatenate([null])          = ""
 StringUtils.concatenate(["a", "b", "c"]) = "abc"
 StringUtils.concatenate([null, "", "a"]) = "a"
 

Parameters:
array - the array of values to concatenate, may be null

Returns:
the concatenated String, null if null array input


contains

public static boolean contains(String str,
                               String searchStr)
Find the first index within a String, handling null. This method uses String.indexOf(int).

A null String will return false.

 StringUtils.contains(null, *)     = false
 StringUtils.contains(*, null)     = false
 StringUtils.contains("", "")      = true
 StringUtils.contains("abc", "")   = true
 StringUtils.contains("abc", "a")  = true
 StringUtils.contains("abc", "z")  = false
 

Parameters:
str - the String to check, may be null
searchStr - the String to find, may be null

Returns:
true if the String contains the search character, false if not or null string input

Since:
2.0


contains

public static boolean contains(String str,
                               char searchChar)
Checks if String contains a search character, handling null. This method uses String.indexOf(int).

A null or empty ("") String will return false.

 StringUtils.contains(null, *)    = false
 StringUtils.contains("", *)      = false
 StringUtils.contains("abc", 'a') = true
 StringUtils.contains("abc", 'z') = false
 

Parameters:
str - the String to check, may be null
searchChar - the character to find

Returns:
true if the String contains the search character, false if not or null string input

Since:
2.0


containsNone

public static boolean containsNone(String str,
                                   String invalidChars)
Checks that the String does not contain certain characters.

A null String will return true. A null invalid character array will return true. An empty String ("") always returns true.

 StringUtils.containsNone(null, *)       = true
 StringUtils.containsNone(*, null)       = true
 StringUtils.containsNone("", *)         = true
 StringUtils.containsNone("ab", "")      = true
 StringUtils.containsNone("abab", "xyz") = true
 StringUtils.containsNone("ab1", "xyz")  = true
 StringUtils.containsNone("abz", "xyz")  = false
 

Parameters:
str - the String to check, may be null
invalidChars - a String of invalid chars, may be null

Returns:
true if it contains none of the invalid chars, or is null

Since:
2.0


containsNone

public static boolean containsNone(String str,
                                   char[] invalidChars)
Checks that the String does not contain certain characters.

A null String will return true. A null invalid character array will return true. An empty String ("") always returns true.

 StringUtils.containsNone(null, *)       = true
 StringUtils.containsNone(*, null)       = true
 StringUtils.containsNone("", *)         = true
 StringUtils.containsNone("ab", '')      = true
 StringUtils.containsNone("abab", 'xyz') = true
 StringUtils.containsNone("ab1", 'xyz')  = true
 StringUtils.containsNone("abz", 'xyz')  = false
 

Parameters:
str - the String to check, may be null
invalidChars - an array of invalid chars, may be null

Returns:
true if it contains none of the invalid chars, or is null

Since:
2.0


containsOnly

public static boolean containsOnly(String str,
                                   String validChars)
Checks if the String contains only certain characters.

A null String will return false. A null valid character String will return false. An empty String ("") always returns true.

 StringUtils.containsOnly(null, *)       = false
 StringUtils.containsOnly(*, null)       = false
 StringUtils.containsOnly("", *)         = true
 StringUtils.containsOnly("ab", "")      = false
 StringUtils.containsOnly("abab", "abc") = true
 StringUtils.containsOnly("ab1", "abc")  = false
 StringUtils.containsOnly("abz", "abc")  = false
 

Parameters:
str - the String to check, may be null
validChars - a String of valid chars, may be null

Returns:
true if it only contains valid chars and is non-null

Since:
2.0


containsOnly

public static boolean containsOnly(String str,
                                   char[] valid)
Checks if the String contains only certain characters.

A null String will return false. A null valid character array will return false. An empty String ("") always returns true.

 StringUtils.containsOnly(null, *)       = false
 StringUtils.containsOnly(*, null)       = false
 StringUtils.containsOnly("", *)         = true
 StringUtils.containsOnly("ab", '')      = false
 StringUtils.containsOnly("abab", 'abc') = true
 StringUtils.containsOnly("ab1", 'abc')  = false
 StringUtils.containsOnly("abz", 'abc')  = false
 

Parameters:
str - the String to check, may be null
valid - an array of valid chars, may be null

Returns:
true if it only contains valid chars and is non-null


countMatches

public static int countMatches(String str,
                               String sub)
Counts how many times the substring appears in the larger String.

A null or empty ("") String input returns 0.

 StringUtils.countMatches(null, *)       = 0
 StringUtils.countMatches("", *)         = 0
 StringUtils.countMatches("abba", null)  = 0
 StringUtils.countMatches("abba", "")    = 0
 StringUtils.countMatches("abba", "a")   = 2
 StringUtils.countMatches("abba", "ab")  = 1
 StringUtils.countMatches("abba", "xxx") = 0
 

Parameters:
str - the String to check, may be null
sub - the substring to count, may be null

Returns:
the number of occurances, 0 if either String is null


defaultString

public static String defaultString(String str)
Returns either the passed in String, or if the String is null, an empty String ("").
 StringUtils.defaultString(null)  = ""
 StringUtils.defaultString("")    = ""
 StringUtils.defaultString("bat") = "bat"
 

Parameters:
str - the String to check, may be null

Returns:
the passed in String, or the empty String if it was null

See Also:
ObjectUtils.toString(Object), String.valueOf(Object)


defaultString

public static String defaultString(String str,
                                   String defaultStr)
Returns either the passed in String, or if the String is null, an empty String ("").
 StringUtils.defaultString(null, "null")  = "null"
 StringUtils.defaultString("", "null")    = ""
 StringUtils.defaultString("bat", "null") = "bat"
 

Parameters:
str - the String to check, may be null
defaultStr - the default String to return if the input is null, may be null

Returns:
the passed in String, or the default if it was null

See Also:
ObjectUtils.toString(Object,String), String.valueOf(Object)


deleteSpaces

public static String deleteSpaces(String str)

Deprecated. Use the better localized deleteWhitespace(String). Method will be removed in Commons Lang 3.0.

Deletes all 'space' characters from a String as defined by Character.isSpace(char).

This is the only StringUtils method that uses the isSpace definition. You are advised to use deleteWhitespace(String) instead as whitespace is much better localized.

 StringUtils.deleteSpaces(null)           = null
 StringUtils.deleteSpaces("")             = ""
 StringUtils.deleteSpaces("abc")          = "abc"
 StringUtils.deleteSpaces(" \t  abc \n ") = "abc"
 StringUtils.deleteSpaces("ab  c")        = "abc"
 StringUtils.deleteSpaces("a\nb\tc     ") = "abc"
 

Spaces are defined as {' ', '\t', '\r', '\n', '\b'} in line with the deprecated isSpace method.

Parameters:
str - the String to delete spaces from, may be null

Returns:
the String without 'spaces', null if null String input


deleteWhitespace

public static String deleteWhitespace(String str)
Deletes all whitespaces from a String as defined by Character.isWhitespace(char).
 StringUtils.deleteWhitespace(null)         = null
 StringUtils.deleteWhitespace("")           = ""
 StringUtils.deleteWhitespace("abc")        = "abc"
 StringUtils.deleteWhitespace("   ab  c  ") = "abc"
 

Parameters:
str - the String to delete whitespace from, may be null

Returns:
the String without whitespaces, null if null String input


difference

public static String difference(String str1,
                                String str2)
Compares two Strings, and returns the portion where they differ. (More precisely, return the remainder of the second String, starting from where it's different from the first.)

For example, difference("i am a machine", "i am a robot") -> "robot".

 StringUtils.difference(null, null) = null
 StringUtils.difference("", "") = ""
 StringUtils.difference("", "abc") = "abc"
 StringUtils.difference("abc", "") = ""
 StringUtils.difference("abc", "abc") = ""
 StringUtils.difference("ab", "abxyz") = "xyz"
 StringUtils.difference("abcde", "abxyz") = "xyz"
 StringUtils.difference("abcde", "xyz") = "xyz"
 

Parameters:
str1 - the first String, may be null
str2 - the second String, may be null

Returns:
the portion of str2 where it differs from str1; returns the empty String if they are equal

Since:
2.0


equals

public static boolean equals(String str1,
                             String str2)
Compares two Strings, returning true if they are equal.

nulls are handled without exceptions. Two null references are considered to be equal. The comparison is case sensitive.

 StringUtils.equals(null, null)   = true
 StringUtils.equals(null, "abc")  = false
 StringUtils.equals("abc", null)  = false
 StringUtils.equals("abc", "abc") = true
 StringUtils.equals("abc", "ABC") = false
 

Parameters:
str1 - the first String, may be null
str2 - the second String, may be null

Returns:
true if the Strings are equal, case sensitive, or both null

See Also:
java.lang.String.equals(Object)


equalsIgnoreCase

public static boolean equalsIgnoreCase(String str1,
                                       String str2)
Compares two Strings, returning true if they are equal ignoring the case.

nulls are handled without exceptions. Two null references are considered equal. Comparison is case insensitive.

 StringUtils.equalsIgnoreCase(null, null)   = true
 StringUtils.equalsIgnoreCase(null, "abc")  = false
 StringUtils.equalsIgnoreCase("abc", null)  = false
 StringUtils.equalsIgnoreCase("abc", "abc") = true
 StringUtils.equalsIgnoreCase("abc", "ABC") = true
 

Parameters:
str1 - the first String, may be null
str2 - the second String, may be null

Returns:
true if the Strings are equal, case insensitive, or both null

See Also:
java.lang.String.equalsIgnoreCase(String)


escape

public static String escape(String str)

Deprecated. Use StringEscapeUtils.escapeJava(String) This method will be removed in Commons Lang 3.0

Escapes any values it finds into their String form.

So a tab becomes the characters '\\' and 't'.

As of Lang 2.0, this calls StringEscapeUtils.escapeJava(String) behind the scenes.

Parameters:
str - String to escape values in

Returns:
String with escaped values

See Also:
StringEscapeUtils.escapeJava(java.lang.String)


getChomp

public static String getChomp(String str,
                              String sep)

Deprecated. Use substringAfterLast(String,String) instead (although this doesn't include the separator) Method will be removed in Commons Lang 3.0.

Remove everything and return the last value of a supplied String, and everything after it from a String.

Parameters:
str - the String to chomp from, must not be null
sep - the String to chomp, must not be null

Returns:
String chomped


getLevenshteinDistance

public static int getLevenshteinDistance(String s,
                                         String t)
Find the Levenshtein distance between two Strings.

This is the number of changes needed to change one String into another, where each change is a single character modification (deletion, insertion or substitution).

This implementation of the Levenshtein distance algorithm is from http://www.merriampark.com/ld.htm

 StringUtils.getLevenshteinDistance(null, *)             = IllegalArgumentException
 StringUtils.getLevenshteinDistance(*, null)             = IllegalArgumentException
 StringUtils.getLevenshteinDistance("","")               = 0
 StringUtils.getLevenshteinDistance("","a")              = 1
 StringUtils.getLevenshteinDistance("aaapppp", "")       = 7
 StringUtils.getLevenshteinDistance("frog", "fog")       = 1
 StringUtils.getLevenshteinDistance("fly", "ant")        = 3
 StringUtils.getLevenshteinDistance("elephant", "hippo") = 7
 StringUtils.getLevenshteinDistance("hippo", "elephant") = 7
 StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8
 StringUtils.getLevenshteinDistance("hello", "hallo")    = 1
 

Parameters:
s - the first String, must not be null
t - the second String, must not be null

Returns:
result distance


getNestedString

public static String getNestedString(String str,
                                     String tag)

Deprecated. Use the better named substringBetween(String,String). Method will be removed in Commons Lang 3.0.

Gets the String that is nested in between two instances of the same String.

A null input String returns null. A null tag returns null.

 StringUtils.getNestedString(null, *)            = null
 StringUtils.getNestedString("", "")             = ""
 StringUtils.getNestedString("", "tag")          = null
 StringUtils.getNestedString("tagabctag", null)  = null
 StringUtils.getNestedString("tagabctag", "")    = ""
 StringUtils.getNestedString("tagabctag", "tag") = "abc"
 

Parameters:
str - the String containing nested-string, may be null
tag - the String before and after nested-string, may be null

Returns:
the nested String, null if no match


getNestedString

public static String getNestedString(String str,
                                     String open,
                                     String close)

Deprecated. Use the better named substringBetween(String,String,String). Method will be removed in Commons Lang 3.0.

Gets the String that is nested in between two Strings. Only the first match is returned.

A null input String returns null. A null open/close returns null (no match). An empty ("") open/close returns an empty string.

 StringUtils.getNestedString(null, *, *)          = null
 StringUtils.getNestedString("", "", "")          = ""
 StringUtils.getNestedString("", "", "tag")       = null
 StringUtils.getNestedString("", "tag", "tag")    = null
 StringUtils.getNestedString("yabcz", null, null) = null
 StringUtils.getNestedString("yabcz", "", "")     = ""
 StringUtils.getNestedString("yabcz", "y", "z")   = "abc"
 StringUtils.getNestedString("yabczyabcz", "y", "z")   = "abc"
 

Parameters:
str - the String containing nested-string, may be null
open - the String before nested-string, may be null
close - the String after nested-string, may be null

Returns:
the nested String, null if no match


getPrechomp

public static String getPrechomp(String str,
                                 String sep)

Deprecated. Use substringBefore(String,String) instead (although this doesn't include the separator). Method will be removed in Commons Lang 3.0.

Remove and return everything before the first value of a supplied String from another String.

Parameters:
str - the String to chomp from, must not be null
sep - the String to chomp, must not be null

Returns:
String prechomped


indexOf

public static int indexOf(String str,
                          String searchStr)
Finds the first index within a String, handling null. This method uses String.indexOf(String).

A null String will return -1.

 StringUtils.indexOf(null, *)          = -1
 StringUtils.indexOf(*, null)          = -1
 StringUtils.indexOf("", "")           = 0
 StringUtils.indexOf("aabaabaa", "a")  = 0
 StringUtils.indexOf("aabaabaa", "b")  = 2
 StringUtils.indexOf("aabaabaa", "ab") = 1
 StringUtils.indexOf("aabaabaa", "")   = 0
 

Parameters:
str - the String to check, may be null
searchStr - the String to find, may be null

Returns:
the first index of the search String, -1 if no match or null string input

Since:
2.0


indexOf

public static int indexOf(String str,
                          String searchStr,
                          int startPos)
Finds the first index within a String, handling null. This method uses String.indexOf(String, int).

A null String will return -1. A negative start position is treated as zero. An empty ("") search String always matches. A start position greater than the string length only matches an empty search String.

 StringUtils.indexOf(null, *, *)          = -1
 StringUtils.indexOf(*, null, *)          = -1
 StringUtils.indexOf("", "", 0)           = 0
 StringUtils.indexOf("aabaabaa", "a", 0)  = 0
 StringUtils.indexOf("aabaabaa", "b", 0)  = 2
 StringUtils.indexOf("aabaabaa", "ab", 0) = 1
 StringUtils.indexOf("aabaabaa", "b", 3)  = 5
 StringUtils.indexOf("aabaabaa", "b", 9)  = -1
 StringUtils.indexOf("aabaabaa", "b", -1) = 2
 StringUtils.indexOf("aabaabaa", "", 2)   = 2
 StringUtils.indexOf("abc", "", 9)        = 3
 

Parameters:
str - the String to check, may be null
searchStr - the String to find, may be null
startPos - the start position, negative treated as zero

Returns:
the first index of the search String, -1 if no match or null string input

Since:
2.0


indexOf

public static int indexOf(String str,
                          char searchChar)
Finds the first index within a String, handling null. This method uses String.indexOf(int).

A null or empty ("") String will return -1.

 StringUtils.indexOf(null, *)         = -1
 StringUtils.indexOf("", *)           = -1
 StringUtils.indexOf("aabaabaa", 'a') = 0
 StringUtils.indexOf("aabaabaa", 'b') = 2
 

Parameters:
str - the String to check, may be null
searchChar - the character to find

Returns:
the first index of the search character, -1 if no match or null string input

Since:
2.0


indexOf

public static int indexOf(String str,
                          char searchChar,
                          int startPos)
Finds the first index within a String from a start position, handling null. This method uses String.indexOf(int, int).

A null or empty ("") String will return -1. A negative start position is treated as zero. A start position greater than the string length returns -1.

 StringUtils.indexOf(null, *, *)          = -1
 StringUtils.indexOf("", *, *)            = -1
 StringUtils.indexOf("aabaabaa", 'b', 0)  = 2
 StringUtils.indexOf("aabaabaa", 'b', 3)  = 5
 StringUtils.indexOf("aabaabaa", 'b', 9)  = -1
 StringUtils.indexOf("aabaabaa", 'b', -1) = 2
 

Parameters:
str - the String to check, may be null
searchChar - the character to find
startPos - the start position, negative treated as zero

Returns:
the first index of the search character, -1 if no match or null string input

Since:
2.0


indexOfAny

public static int indexOfAny(String str,
                             String searchChars)
Search a String to find the first index of any character in the given set of characters.

A null String will return -1. A null search string will return -1.

 StringUtils.indexOfAny(null, *)            = -1
 StringUtils.indexOfAny("", *)              = -1
 StringUtils.indexOfAny(*, null)            = -1
 StringUtils.indexOfAny(*, "")              = -1
 StringUtils.indexOfAny("zzabyycdxx", "za") = 0
 StringUtils.indexOfAny("zzabyycdxx", "by") = 3
 StringUtils.indexOfAny("aba","z")          = -1
 

Parameters:
str - the String to check, may be null
searchChars - the chars to search for, may be null

Returns:
the index of any of the chars, -1 if no match or null input

Since:
2.0


indexOfAny

public static int indexOfAny(String str,
                             String[] searchStrs)
Find the first index of any of a set of potential substrings.

A null String will return -1. A null or zero length search array will return -1. A null search array entry will be ignored, but a search array containing "" will return 0 if str is not null. This method uses String.indexOf(String).

 StringUtils.indexOfAny(null, *)                     = -1
 StringUtils.indexOfAny(*, null)                     = -1
 StringUtils.indexOfAny(*, [])                       = -1
 StringUtils.indexOfAny("zzabyycdxx", ["ab","cd"])   = 2
 StringUtils.indexOfAny("zzabyycdxx", ["cd","ab"])   = 2
 StringUtils.indexOfAny("zzabyycdxx", ["mn","op"])   = -1
 StringUtils.indexOfAny("zzabyycdxx", ["zab","aby"]) = 1
 StringUtils.indexOfAny("zzabyycdxx", [""])          = 0
 StringUtils.indexOfAny("", [""])                    = 0
 StringUtils.indexOfAny("", ["a"])                   = -1
 

Parameters:
str - the String to check, may be null
searchStrs - the Strings to search for, may be null

Returns:
the first index of any of the searchStrs in str, -1 if no match


indexOfAny

public static int indexOfAny(String str,
                             char[] searchChars)
Search a String to find the first index of any character in the given set of characters.

A null String will return -1. A null or zero length search array will return -1.

 StringUtils.indexOfAny(null, *)                = -1
 StringUtils.indexOfAny("", *)                  = -1
 StringUtils.indexOfAny(*, null)                = -1
 StringUtils.indexOfAny(*, [])                  = -1
 StringUtils.indexOfAny("zzabyycdxx",['z','a']) = 0
 StringUtils.indexOfAny("zzabyycdxx",['b','y']) = 3
 StringUtils.indexOfAny("aba", ['z'])           = -1
 

Parameters:
str - the String to check, may be null
searchChars - the chars to search for, may be null

Returns:
the index of any of the chars, -1 if no match or null input

Since:
2.0


indexOfAnyBut

public static int indexOfAnyBut(String str,
                                String searchChars)
Search a String to find the first index of any character not in the given set of characters.

A null String will return -1. A null search string will return -1.

 StringUtils.indexOfAnyBut(null, *)            = -1
 StringUtils.indexOfAnyBut("", *)              = -1
 StringUtils.indexOfAnyBut(*, null)            = -1
 StringUtils.indexOfAnyBut(*, "")              = -1
 StringUtils.indexOfAnyBut("zzabyycdxx", "za") = 3
 StringUtils.indexOfAnyBut("zzabyycdxx", "")   = 0
 StringUtils.indexOfAnyBut("aba","ab")         = -1
 

Parameters:
str - the String to check, may be null
searchChars - the chars to search for, may be null

Returns:
the index of any of the chars, -1 if no match or null input

Since:
2.0


indexOfAnyBut

public static int indexOfAnyBut(String str,
                                char[] searchChars)
Search a String to find the first index of any character not in the given set of characters.

A null String will return -1. A null or zero length search array will return -1.

 StringUtils.indexOfAnyBut(null, *)           = -1
 StringUtils.indexOfAnyBut("", *)             = -1
 StringUtils.indexOfAnyBut(*, null)           = -1
 StringUtils.indexOfAnyBut(*, [])             = -1
 StringUtils.indexOfAnyBut("zzabyycdxx",'za') = 3
 StringUtils.indexOfAnyBut("zzabyycdxx", '')  = 0
 StringUtils.indexOfAnyBut("aba", 'ab')       = -1
 

Parameters:
str - the String to check, may be null
searchChars - the chars to search for, may be null

Returns:
the index of any of the chars, -1 if no match or null input

Since:
2.0


indexOfDifference

public static int indexOfDifference(String str1,
                                    String str2)
Compares two Strings, and returns the index at which the Strings begin to differ.

For example, indexOfDifference("i am a machine", "i am a robot") -> 7

 StringUtils.indexOfDifference(null, null) = -1
 StringUtils.indexOfDifference("", "") = -1
 StringUtils.indexOfDifference("", "abc") = 0
 StringUtils.indexOfDifference("abc", "") = 0
 StringUtils.indexOfDifference("abc", "abc") = -1
 StringUtils.indexOfDifference("ab", "abxyz") = 2
 StringUtils.indexOfDifference("abcde", "abxyz") = 2
 StringUtils.indexOfDifference("abcde", "xyz") = 0
 

Parameters:
str1 - the first String, may be null
str2 - the second String, may be null

Returns:
the index where str2 and str1 begin to differ; -1 if they are equal

Since:
2.0


isAlpha

public static boolean isAlpha(String str)
Checks if the String contains only unicode letters.

null will return false. An empty String ("") will return true.

 StringUtils.isAlpha(null)   = false
 StringUtils.isAlpha("")     = true
 StringUtils.isAlpha("  ")   = false
 StringUtils.isAlpha("abc")  = true
 StringUtils.isAlpha("ab2c") = false
 StringUtils.isAlpha("ab-c") = false
 

Parameters:
str - the String to check, may be null

Returns:
true if only contains letters, and is non-null


isAlphaSpace

public static boolean isAlphaSpace(String str)
Checks if the String contains only unicode letters and space (' ').

null will return false An empty String ("") will return true.

 StringUtils.isAlphaSpace(null)   = false
 StringUtils.isAlphaSpace("")     = true
 StringUtils.isAlphaSpace("  ")   = true
 StringUtils.isAlphaSpace("abc")  = true
 StringUtils.isAlphaSpace("ab c") = true
 StringUtils.isAlphaSpace("ab2c") = false
 StringUtils.isAlphaSpace("ab-c") = false
 

Parameters:
str - the String to check, may be null

Returns:
true if only contains letters and space, and is non-null


isAlphanumeric

public static boolean isAlphanumeric(String str)
Checks if the String contains only unicode letters or digits.

null will return false. An empty String ("") will return true.

 StringUtils.isAlphanumeric(null)   = false
 StringUtils.isAlphanumeric("")     = true
 StringUtils.isAlphanumeric("  ")   = false
 StringUtils.isAlphanumeric("abc")  = true
 StringUtils.isAlphanumeric("ab c") = false
 StringUtils.isAlphanumeric("ab2c") = true
 StringUtils.isAlphanumeric("ab-c") = false
 

Parameters:
str - the String to check, may be null

Returns:
true if only contains letters or digits, and is non-null


isAlphanumericSpace

public static boolean isAlphanumericSpace(String str)
Checks if the String contains only unicode letters, digits or space (' ').

null will return false. An empty String ("") will return true.

 StringUtils.isAlphanumeric(null)   = false
 StringUtils.isAlphanumeric("")     = true
 StringUtils.isAlphanumeric("  ")   = true
 StringUtils.isAlphanumeric("abc")  = true
 StringUtils.isAlphanumeric("ab c") = true
 StringUtils.isAlphanumeric("ab2c") = true
 StringUtils.isAlphanumeric("ab-c") = false
 

Parameters:
str - the String to check, may be null

Returns:
true if only contains letters, digits or space, and is non-null


isBlank

public static boolean isBlank(String str)
Checks if a String is whitespace, empty ("") or null.
 StringUtils.isBlank(null)      = true
 StringUtils.isBlank("")        = true
 StringUtils.isBlank(" ")       = true
 StringUtils.isBlank("bob")     = false
 StringUtils.isBlank("  bob  ") = false
 

Parameters:
str - the String to check, may be null

Returns:
true if the String is null, empty or whitespace

Since:
2.0


isEmpty

public static boolean isEmpty(String str)
Checks if a String is empty ("") or null.
 StringUtils.isEmpty(null)      = true
 StringUtils.isEmpty("")        = true
 StringUtils.isEmpty(" ")       = false
 StringUtils.isEmpty("bob")     = false
 StringUtils.isEmpty("  bob  ") = false
 

NOTE: This method changed in Lang version 2.0. It no longer trims the String. That functionality is available in isBlank().

Parameters:
str - the String to check, may be null

Returns:
true if the String is empty or null


isNotBlank

public static boolean isNotBlank(String str)
Checks if a String is not empty (""), not null and not whitespace only.
 StringUtils.isNotBlank(null)      = false
 StringUtils.isNotBlank("")        = false
 StringUtils.isNotBlank(" ")       = false
 StringUtils.isNotBlank("bob")     = true
 StringUtils.isNotBlank("  bob  ") = true
 

Parameters:
str - the String to check, may be null

Returns:
true if the String is not empty and not null and not whitespace

Since:
2.0


isNotEmpty

public static boolean isNotEmpty(String str)
Checks if a String is not empty ("") and not null.
 StringUtils.isNotEmpty(null)      = false
 StringUtils.isNotEmpty("")        = false
 StringUtils.isNotEmpty(" ")       = true
 StringUtils.isNotEmpty("bob")     = true
 StringUtils.isNotEmpty("  bob  ") = true
 

Parameters:
str - the String to check, may be null

Returns:
true if the String is not empty and not null


isNumeric

public static boolean isNumeric(String str)
Checks if the String contains only unicode digits. A decimal point is not a unicode digit and returns false.

null will return false. An empty String ("") will return true.

 StringUtils.isNumeric(null)   = false
 StringUtils.isNumeric("")     = true
 StringUtils.isNumeric("  ")   = false
 StringUtils.isNumeric("123")  = true
 StringUtils.isNumeric("12 3") = false
 StringUtils.isNumeric("ab2c") = false
 StringUtils.isNumeric("12-3") = false
 StringUtils.isNumeric("12.3") = false
 

Parameters:
str - the String to check, may be null

Returns:
true if only contains digits, and is non-null


isNumericSpace

public static boolean isNumericSpace(String str)
Checks if the String contains only unicode digits or space (' '). A decimal point is not a unicode digit and returns false.

null will return false. An empty String ("") will return true.

 StringUtils.isNumeric(null)   = false
 StringUtils.isNumeric("")     = true
 StringUtils.isNumeric("  ")   = true
 StringUtils.isNumeric("123")  = true
 StringUtils.isNumeric("12 3") = true
 StringUtils.isNumeric("ab2c") = false
 StringUtils.isNumeric("12-3") = false
 StringUtils.isNumeric("12.3") = false
 

Parameters:
str - the String to check, may be null

Returns:
true if only contains digits or space, and is non-null


isWhitespace

public static boolean isWhitespace(String str)
Checks if the String contains only whitespace.

null will return false. An empty String ("") will return true.

 StringUtils.isWhitespace(null)   = false
 StringUtils.isWhitespace("")     = true
 StringUtils.isWhitespace("  ")   = true
 StringUtils.isWhitespace("abc")  = false
 StringUtils.isWhitespace("ab2c") = false
 StringUtils.isWhitespace("ab-c") = false
 

Parameters:
str - the String to check, may be null

Returns:
true if only contains whitespace, and is non-null

Since:
2.0


join

public static String join(Iterator iterator,
                          String separator)

Parameters:
iterator - the Iterator of values to join together, may be null
separator - the separator character to use, null treated as ""

Returns:
the joined String, null if null iterator input


join

public static String join(Iterator iterator,
                          char separator)

Parameters:
iterator - the Iterator of values to join together, may be null
separator - the separator character to use

Returns:
the joined String, null if null iterator input

Since:
2.0


join

public static String join(Object[] array)
Joins the elements of the provided array into a single String containing the provided list of elements.

No separator is added to the joined String. Null objects or empty strings within the array are represented by empty strings.

 StringUtils.join(null)            = null
 StringUtils.join([])              = ""
 StringUtils.join([null])          = ""
 StringUtils.join(["a", "b", "c"]) = "abc"
 StringUtils.join([null, "", "a"]) = "a"
 

Parameters:
array - the array of values to join together, may be null

Returns:
the joined String, null if null array input

Since:
2.0


join

public static String join(Object[] array,
                          String separator)
Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. A null separator is the same as an empty String (""). Null objects or empty strings within the array are represented by empty strings.

 StringUtils.join(null, *)                = null
 StringUtils.join([], *)                  = ""
 StringUtils.join([null], *)              = ""
 StringUtils.join(["a", "b", "c"], "--")  = "a--b--c"
 StringUtils.join(["a", "b", "c"], null)  = "abc"
 StringUtils.join(["a", "b", "c"], "")    = "abc"
 StringUtils.join([null, "", "a"], ',')   = ",,a"
 

Parameters:
array - the array of values to join together, may be null
separator - the separator character to use, null treated as ""

Returns:
the joined String, null if null array input


join

public static String join(Object[] array,
                          char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.

No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.

 StringUtils.join(null, *)               = null
 StringUtils.join([], *)                 = ""
 StringUtils.join([null], *)             = ""
 StringUtils.join(["a", "b", "c"], ';')  = "a;b;c"
 StringUtils.join(["a", "b", "c"], null) = "abc"
 StringUtils.join([null, "", "a"], ';')  = ";;a"
 

Parameters:
array - the array of values to join together, may be null
separator - the separator character to use

Returns:
the joined String, null if null array input

Since:
2.0


lastIndexOf

public static int lastIndexOf(String str,
                              String searchStr)
Finds the last index within a String, handling null. This method uses String.lastIndexOf(String).

A null String will return -1.

 StringUtils.lastIndexOf(null, *)          = -1
 StringUtils.lastIndexOf(*, null)          = -1
 StringUtils.lastIndexOf("", "")           = 0
 StringUtils.lastIndexOf("aabaabaa", "a")  = 0
 StringUtils.lastIndexOf("aabaabaa", "b")  = 2
 StringUtils.lastIndexOf("aabaabaa", "ab") = 1
 StringUtils.lastIndexOf("aabaabaa", "")   = 8
 

Parameters:
str - the String to check, may be null
searchStr - the String to find, may be null

Returns:
the last index of the search String, -1 if no match or null string input

Since:
2.0


lastIndexOf

public static int lastIndexOf(String str,
                              String searchStr,
                              int startPos)
Finds the first index within a String, handling null. This method uses String.lastIndexOf(String, int).

A null String will return -1. A negative start position returns -1. An empty ("") search String always matches unless the start position is negative. A start position greater than the string length searches the whole string.

 StringUtils.lastIndexOf(null, *, *)          = -1
 StringUtils.lastIndexOf(*, null, *)          = -1
 StringUtils.lastIndexOf("aabaabaa", "a", 8)  = 7
 StringUtils.lastIndexOf("aabaabaa", "b", 8)  = 5
 StringUtils.lastIndexOf("aabaabaa", "ab", 8) = 4
 StringUtils.lastIndexOf("aabaabaa", "b", 9)  = 5
 StringUtils.lastIndexOf("aabaabaa", "b", -1) = -1
 StringUtils.lastIndexOf("aabaabaa", "a", 0)  = 0
 StringUtils.lastIndexOf("aabaabaa", "b", 0)  = -1
 

Parameters:
str - the String to check, may be null
searchStr - the String to find, may be null
startPos - the start position, negative treated as zero

Returns:
the first index of the search String, -1 if no match or null string input

Since:
2.0


lastIndexOf

public static int lastIndexOf(String str,
                              char searchChar)
Finds the last index within a String, handling null. This method uses String.lastIndexOf(int).

A null or empty ("") String will return -1.

 StringUtils.lastIndexOf(null, *)         = -1
 StringUtils.lastIndexOf("", *)           = -1
 StringUtils.lastIndexOf("aabaabaa", 'a') = 7
 StringUtils.lastIndexOf("aabaabaa", 'b') = 5
 

Parameters:
str - the String to check, may be null
searchChar - the character to find

Returns:
the last index of the search character, -1 if no match or null string input

Since:
2.0


lastIndexOf

public static int lastIndexOf(String str,
                              char searchChar,
                              int startPos)
Finds the last index within a String from a start position, handling null. This method uses String.lastIndexOf(int, int).

A null or empty ("") String will return -1. A negative start position returns -1. A start position greater than the string length searches the whole string.

 StringUtils.lastIndexOf(null, *, *)          = -1
 StringUtils.lastIndexOf("", *,  *)           = -1
 StringUtils.lastIndexOf("aabaabaa", 'b', 8)  = 5
 StringUtils.lastIndexOf("aabaabaa", 'b', 4)  = 2
 StringUtils.lastIndexOf("aabaabaa", 'b', 0)  = -1
 StringUtils.lastIndexOf("aabaabaa", 'b', 9)  = 5
 StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1
 StringUtils.lastIndexOf("aabaabaa", 'a', 0)  = 0
 

Parameters:
str - the String to check, may be null
searchChar - the character to find
startPos - the start position

Returns:
the last index of the search character, -1 if no match or null string input

Since:
2.0


lastIndexOfAny

public static int lastIndexOfAny(String str,
                                 String[] searchStrs)
Find the latest index of any of a set of potential substrings.

A null String will return -1. A null search array will return -1. A null or zero length search array entry will be ignored, but a search array containing "" will return the length of str if str is not null. This method uses String.indexOf(String)

 StringUtils.lastIndexOfAny(null, *)                   = -1
 StringUtils.lastIndexOfAny(*, null)                   = -1
 StringUtils.lastIndexOfAny(*, [])                     = -1
 StringUtils.lastIndexOfAny(*, [null])                 = -1
 StringUtils.lastIndexOfAny("zzabyycdxx", ["ab","cd"]) = 6
 StringUtils.lastIndexOfAny("zzabyycdxx", ["cd","ab"]) = 6
 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1
 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1
 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn",""])   = 10
 

Parameters:
str - the String to check, may be null
searchStrs - the Strings to search for, may be null

Returns:
the last index of any of the Strings, -1 if no match


left

public static String left(String str,
                          int len)
Gets the leftmost len characters of a String.

If len characters are not available, or the String is null, the String will be returned without an exception. An exception is thrown if len is negative.

 StringUtils.left(null, *)    = null
 StringUtils.left(*, -ve)     = ""
 StringUtils.left("", *)      = ""
 StringUtils.left("abc", 0)   = ""
 StringUtils.left("abc", 2)   = "ab"
 StringUtils.left("abc", 4)   = "abc"
 

Parameters:
str - the String to get the leftmost characters from, may be null
len - the length of the required String, must be zero or positive

Returns:
the leftmost characters, null if null String input


leftPad

public static String leftPad(String str,
                             int size)
Left pad a String with spaces (' ').

The String is padded to the size of size.

 StringUtils.leftPad(null, *)   = null
 StringUtils.leftPad("", 3)     = "   "
 StringUtils.leftPad("bat", 3)  = "bat"
 StringUtils.leftPad("bat", 5)  = "  bat"
 StringUtils.leftPad("bat", 1)  = "bat"
 StringUtils.leftPad("bat", -1) = "bat"
 

Parameters:
str - the String to pad out, may be null
size - the size to pad to

Returns:
left padded String or original String if no padding is necessary, null if null String input


leftPad

public static String leftPad(String str,
                             int size,
                             String padStr)
Left pad a String with a specified String.

Pad to a size of size.

 StringUtils.leftPad(null, *, *)      = null
 StringUtils.leftPad("", 3, "z")      = "zzz"
 StringUtils.leftPad("bat", 3, "yz")  = "bat"
 StringUtils.leftPad("bat", 5, "yz")  = "yzbat"
 StringUtils.leftPad("bat", 8, "yz")  = "yzyzybat"
 StringUtils.leftPad("bat", 1, "yz")  = "bat"
 StringUtils.leftPad("bat", -1, "yz") = "bat"
 StringUtils.leftPad("bat", 5, null)  = "  bat"
 StringUtils.leftPad("bat", 5, "")    = "  bat"
 

Parameters:
str - the String to pad out, may be null
size - the size to pad to
padStr - the String to pad with, null or empty treated as single space

Returns:
left padded String or original String if no padding is necessary, null if null String input


leftPad

public static String leftPad(String str,
                             int size,
                             char padChar)
Left pad a String with a specified character.

Pad to a size of size.

 StringUtils.leftPad(null, *, *)     = null
 StringUtils.leftPad("", 3, 'z')     = "zzz"
 StringUtils.leftPad("bat", 3, 'z')  = "bat"
 StringUtils.leftPad("bat", 5, 'z')  = "zzbat"
 StringUtils.leftPad("bat", 1, 'z')  = "bat"
 StringUtils.leftPad("bat", -1, 'z') = "bat"
 

Parameters:
str - the String to pad out, may be null
size - the size to pad to
padChar - the character to pad with

Returns:
left padded String or original String if no padding is necessary, null if null String input

Since:
2.0


lowerCase

public static String lowerCase(String str)
Converts a String to lower case as per String.toLowerCase().

A null input String returns null.

 StringUtils.lowerCase(null)  = null
 StringUtils.lowerCase("")    = ""
 StringUtils.lowerCase("aBc") = "abc"
 

Parameters:
str - the String to lower case, may be null

Returns:
the lower cased String, null if null String input


mid

public static String mid(String str,
                         int pos,
                         int len)
Gets len characters from the middle of a String.

If len characters are not available, the remainder of the String will be returned without an exception. If the String is null, null will be returned. An exception is thrown if len is negative.

 StringUtils.mid(null, *, *)    = null
 StringUtils.mid(*, *, -ve)     = ""
 StringUtils.mid("", 0, *)      = ""
 StringUtils.mid("abc", 0, 2)   = "ab"
 StringUtils.mid("abc", 0, 4)   = "abc"
 StringUtils.mid("abc", 2, 4)   = "c"
 StringUtils.mid("abc", 4, 2)   = ""
 StringUtils.mid("abc", -2, 2)  = "ab"
 

Parameters:
str - the String to get the characters from, may be null
pos - the position to start from, negative treated as zero
len - the length of the required String, must be zero or positive

Returns:
the middle characters, null if null String input


overlay

public static String overlay(String str,
                             String overlay,
                             int start,
                             int end)
Overlays part of a String with another String.

A null string input returns null. A negative index is treated as zero. An index greater than the string length is treated as the string length. The start index is always the smaller of the two indices.

 StringUtils.overlay(null, *, *, *)            = null
 StringUtils.overlay("", "abc", 0, 0)          = "abc"
 StringUtils.overlay("abcdef", null, 2, 4)     = "abef"
 StringUtils.overlay("abcdef", "", 2, 4)       = "abef"
 StringUtils.overlay("abcdef", "", 4, 2)       = "abef"
 StringUtils.overlay("abcdef", "zzzz", 2, 4)   = "abzzzzef"
 StringUtils.overlay("abcdef", "zzzz", 4, 2)   = "abzzzzef"
 StringUtils.overlay("abcdef", "zzzz", -1, 4)  = "zzzzef"
 StringUtils.overlay("abcdef", "zzzz", 2, 8)   = "abzzzz"
 StringUtils.overlay("abcdef", "zzzz", -2, -3) = "zzzzabcdef"
 StringUtils.overlay("abcdef", "zzzz", 8, 10)  = "abcdefzzzz"
 

Parameters:
str - the String to do overlaying in, may be null
overlay - the String to overlay, may be null
start - the position to start overlaying at
end - the position to stop overlaying before

Returns:
overlayed String, null if null String input

Since:
2.0


overlayString

public static String overlayString(String text,
                                   String overlay,
                                   int start,
                                   int end)

Deprecated. Use better named overlay(String,String,int,int) instead. Method will be removed in Commons Lang 3.0.

Overlays part of a String with another String.
 StringUtils.overlayString(null, *, *, *)           = NullPointerException
 StringUtils.overlayString(*, null, *, *)           = NullPointerException
 StringUtils.overlayString("", "abc", 0, 0)         = "abc"
 StringUtils.overlayString("abcdef", null, 2, 4)    = "abef"
 StringUtils.overlayString("abcdef", "", 2, 4)      = "abef"
 StringUtils.overlayString("abcdef", "zzzz", 2, 4)  = "abzzzzef"
 StringUtils.overlayString("abcdef", "zzzz", 4, 2)  = "abcdzzzzcdef"
 StringUtils.overlayString("abcdef", "zzzz", -1, 4) = IndexOutOfBoundsException
 StringUtils.overlayString("abcdef", "zzzz", 2, 8)  = IndexOutOfBoundsException
 

Parameters:
text - the String to do overlaying in, may be null
overlay - the String to overlay, may be null
start - the position to start overlaying at, must be valid
end - the position to stop overlaying before, must be valid

Returns:
overlayed String, null if null String input


prechomp

public static String prechomp(String str,
                              String sep)

Deprecated. Use substringAfter(String,String) instead. Method will be removed in Commons Lang 3.0.

Remove the first value of a supplied String, and everything before it from a String.

Parameters:
str - the String to chomp from, must not be null
sep - the String to chomp, must not be null

Returns:
String without chomped beginning


repeat

public static String repeat(String str,
                            int repeat)
Repeat a String repeat times to form a new String.
 StringUtils.repeat(null, 2) = null
 StringUtils.repeat("", 0)   = ""
 StringUtils.repeat("", 2)   = ""
 StringUtils.repeat("a", 3)  = "aaa"
 StringUtils.repeat("ab", 2) = "abab"
 StringUtils.repeat("a", -2) = ""
 

Parameters:
str - the String to repeat, may be null
repeat - number of times to repeat str, negative treated as zero

Returns:
a new String consisting of the original String repeated, null if null String input


replace

public static String replace(String text,
                             String repl,
                             String with)
Replaces all occurances of a String within another String.

A null reference passed to this method is a no-op.

 StringUtils.replace(null, *, *)        = null
 StringUtils.replace("", *, *)          = ""
 StringUtils.replace("aba", null, null) = "aba"
 StringUtils.replace("aba", null, null) = "aba"
 StringUtils.replace("aba", "a", null)  = "aba"
 StringUtils.replace("aba", "a", "")    = "aba"
 StringUtils.replace("aba", "a", "z")   = "zbz"
 

Parameters:
text - text to search and replace in, may be null
repl - the String to search for, may be null
with - the String to replace with, may be null

Returns:
the text with any replacements processed, null if null String input

See Also:
replace(String text, String repl, String with, int max)


replace

public static String replace(String text,
                             String repl,
                             String with,
                             int max)
Replaces a String with another String inside a larger String, for the first max values of the search String.

A null reference passed to this method is a no-op.

 StringUtils.replace(null, *, *, *)         = null
 StringUtils.replace("", *, *, *)           = ""
 StringUtils.replace("abaa", null, null, 1) = "abaa"
 StringUtils.replace("abaa", null, null, 1) = "abaa"
 StringUtils.replace("abaa", "a", null, 1)  = "abaa"
 StringUtils.replace("abaa", "a", "", 1)    = "abaa"
 StringUtils.replace("abaa", "a", "z", 0)   = "abaa"
 StringUtils.replace("abaa", "a", "z", 1)   = "zbaa"
 StringUtils.replace("abaa", "a", "z", 2)   = "zbza"
 StringUtils.replace("abaa", "a", "z", -1)  = "zbzz"
 

Parameters:
text - text to search and replace in, may be null
repl - the String to search for, may be null
with - the String to replace with, may be null
max - maximum number of values to replace, or -1 if no maximum

Returns:
the text with any replacements processed, null if null String input


replaceChars

public static String replaceChars(String str,
                                  String searchChars,
                                  String replaceChars)
Replaces multiple characters in a String in one go. This method can also be used to delete characters.

For example:
replaceChars("hello", "ho", "jy") = jelly.

A null string input returns null. An empty ("") string input returns an empty string. A null or empty set of search characters returns the input string.

The length of the search characters should normally equal the length of the replace characters. If the search characters is longer, then the extra search characters are deleted. If the search characters is shorter, then the extra replace characters are ignored.

 StringUtils.replaceChars(null, *, *)           = null
 StringUtils.replaceChars("", *, *)             = ""
 StringUtils.replaceChars("abc", null, *)       = "abc"
 StringUtils.replaceChars("abc", "", *)         = "abc"
 StringUtils.replaceChars("abc", "b", null)     = "ac"
 StringUtils.replaceChars("abc", "b", "")       = "ac"
 StringUtils.replaceChars("abcba", "bc", "yz")  = "ayzya"
 StringUtils.replaceChars("abcba", "bc", "y")   = "ayya"
 StringUtils.replaceChars("abcba", "bc", "yzx") = "ayzya"
 

Parameters:
str - String to replace characters in, may be null
searchChars - a set of characters to search for, may be null
replaceChars - a set of characters to replace, may be null

Returns:
modified String, null if null string input

Since:
2.0


replaceChars

public static String replaceChars(String str,
                                  char searchChar,
                                  char replaceChar)
Replaces all occurrances of a character in a String with another. This is a null-safe version of String.replace(char, char).

A null string input returns null. An empty ("") string input returns an empty string.

 StringUtils.replaceChars(null, *, *)        = null
 StringUtils.replaceChars("", *, *)          = ""
 StringUtils.replaceChars("abcba", 'b', 'y') = "aycya"
 StringUtils.replaceChars("abcba", 'z', 'y') = "abcba"
 

Parameters:
str - String to replace characters in, may be null
searchChar - the character to search for, may be null
replaceChar - the character to replace, may be null

Returns:
modified String, null if null string input

Since:
2.0


replaceOnce

public static String replaceOnce(String text,
                                 String repl,
                                 String with)
Replaces a String with another String inside a larger String, once.

A null reference passed to this method is a no-op.

 StringUtils.replaceOnce(null, *, *)        = null
 StringUtils.replaceOnce("", *, *)          = ""
 StringUtils.replaceOnce("aba", null, null) = "aba"
 StringUtils.replaceOnce("aba", null, null) = "aba"
 StringUtils.replaceOnce("aba", "a", null)  = "aba"
 StringUtils.replaceOnce("aba", "a", "")    = "aba"
 StringUtils.replaceOnce("aba", "a", "z")   = "zba"
 

Parameters:
text - text to search and replace in, may be null
repl - the String to search for, may be null
with - the String to replace with, may be null

Returns:
the text with any replacements processed, null if null String input

See Also:
replace(String text, String repl, String with, int max)


reverse

public static String reverse(String str)

Parameters:
str - the String to reverse, may be null

Returns:
the reversed String, null if null String input


reverseDelimited

public static String reverseDelimited(String str,
                                      char separatorChar)
Reverses a String that is delimited by a specific character.

The Strings between the delimiters are not reversed. Thus java.lang.String becomes String.lang.java (if the delimiter is '.').

 StringUtils.reverseDelimited(null, *)      = null
 StringUtils.reverseDelimited("", *)        = ""
 StringUtils.reverseDelimited("a.b.c", 'x') = "a.b.c"
 StringUtils.reverseDelimited("a.b.c", ".") = "c.b.a"
 

Parameters:
str - the String to reverse, may be null
separatorChar - the separator character to use

Returns:
the reversed String, null if null String input

Since:
2.0


reverseDelimitedString

public static String reverseDelimitedString(String str,
                                            String separatorChars)

Deprecated. Use reverseDelimited(String,char) instead. This method is broken as the join doesn't know which char to use. Method will be removed in Commons Lang 3.0.

Reverses a String that is delimited by a specific character.

The Strings between the delimiters are not reversed. Thus java.lang.String becomes String.lang.java (if the delimiter is ".").

 StringUtils.reverseDelimitedString(null, *)       = null
 StringUtils.reverseDelimitedString("",*)          = ""
 StringUtils.reverseDelimitedString("a.b.c", null) = "a.b.c"
 StringUtils.reverseDelimitedString("a.b.c", ".")  = "c.b.a"
 

Parameters:
str - the String to reverse, may be null
separatorChars - the separator characters to use, null treated as whitespace

Returns:
the reversed String, null if null String input


right

public static String right(String str,
                           int len)
Gets the rightmost len characters of a String.

If len characters are not available, or the String is null, the String will be returned without an an exception. An exception is thrown if len is negative.

 StringUtils.right(null, *)    = null
 StringUtils.right(*, -ve)     = ""
 StringUtils.right("", *)      = ""
 StringUtils.right("abc", 0)   = ""
 StringUtils.right("abc", 2)   = "bc"
 StringUtils.right("abc", 4)   = "abc"
 

Parameters:
str - the String to get the rightmost characters from, may be null
len - the length of the required String, must be zero or positive

Returns:
the rightmost characters, null if null String input


rightPad

public static String rightPad(String str,
                              int size)
Right pad a String with spaces (' ').

The String is padded to the size of size.

 StringUtils.rightPad(null, *)   = null
 StringUtils.rightPad("", 3)     = "   "
 StringUtils.rightPad("bat", 3)  = "bat"
 StringUtils.rightPad("bat", 5)  = "bat  "
 StringUtils.rightPad("bat", 1)  = "bat"
 StringUtils.rightPad("bat", -1) = "bat"
 

Parameters:
str - the String to pad out, may be null
size - the size to pad to

Returns:
right padded String or original String if no padding is necessary, null if null String input


rightPad

public static String rightPad(String str,
                              int size,
                              String padStr)
Right pad a String with a specified String.

The String is padded to the size of size.

 StringUtils.rightPad(null, *, *)      = null
 StringUtils.rightPad("", 3, "z")      = "zzz"
 StringUtils.rightPad("bat", 3, "yz")  = "bat"
 StringUtils.rightPad("bat", 5, "yz")  = "batyz"
 StringUtils.rightPad("bat", 8, "yz")  = "batyzyzy"
 StringUtils.rightPad("bat", 1, "yz")  = "bat"
 StringUtils.rightPad("bat", -1, "yz") = "bat"
 StringUtils.rightPad("bat", 5, null)  = "bat  "
 StringUtils.rightPad("bat", 5, "")    = "bat  "
 

Parameters:
str - the String to pad out, may be null
size - the size to pad to
padStr - the String to pad with, null or empty treated as single space

Returns:
right padded String or original String if no padding is necessary, null if null String input


rightPad

public static String rightPad(String str,
                              int size,
                              char padChar)
Right pad a String with a specified character.

The String is padded to the size of size.

 StringUtils.rightPad(null, *, *)     = null
 StringUtils.rightPad("", 3, 'z')     = "zzz"
 StringUtils.rightPad("bat", 3, 'z')  = "bat"
 StringUtils.rightPad("bat", 5, 'z')  = "batzz"
 StringUtils.rightPad("bat", 1, 'z')  = "bat"
 StringUtils.rightPad("bat", -1, 'z') = "bat"
 

Parameters:
str - the String to pad out, may be null
size - the size to pad to
padChar - the character to pad with

Returns:
right padded String or original String if no padding is necessary, null if null String input

Since:
2.0


split

public static String[] split(String str)
Splits the provided text into an array, using whitespace as the separator. Whitespace is defined by Character.isWhitespace(char).

The separator is not included in the returned String array. Adjacent separators are treated as one separator.

A null input String returns null.

 StringUtils.split(null)       = null
 StringUtils.split("")         = []
 StringUtils.split("abc def")  = ["abc", "def"]
 StringUtils.split("abc  def") = ["abc", "def"]
 StringUtils.split(" abc ")    = ["abc"]
 

Parameters:
str - the String to parse, may be null

Returns:
an array of parsed Strings, null if null String input


split

public static String[] split(String str,
                             String separatorChars)
Splits the provided text into an array, separators specified. This is an alternative to using StringTokenizer.

The separator is not included in the returned String array. Adjacent separators are treated as one separator.

A null input String returns null. A null separatorChars splits on whitespace.

 StringUtils.split(null, *)         = null
 StringUtils.split("", *)           = []
 StringUtils.split("abc def", null) = ["abc", "def"]
 StringUtils.split("abc def", " ")  = ["abc", "def"]
 StringUtils.split("abc  def", " ") = ["abc", "def"]
 StringUtils.split("ab:cd:ef", ":") = ["ab", "cd", "ef"]
 

Parameters:
str - the String to parse, may be null
separatorChars - the characters used as the delimiters, null splits on whitespace

Returns:
an array of parsed Strings, null if null String input


split

public static String[] split(String str,
                             String separatorChars,
                             int max)
Splits the provided text into an array, separators specified. This is an alternative to using StringTokenizer.

The separator is not included in the returned String array. Adjacent separators are treated as one separator.

A null input String returns null. A null separatorChars splits on whitespace.

 StringUtils.split(null, *, *)            = null
 StringUtils.split("", *, *)              = []
 StringUtils.split("ab de fg", null, 0)   = ["ab", "cd", "ef"]
 StringUtils.split("ab   de fg", null, 0) = ["ab", "cd", "ef"]
 StringUtils.split("ab:cd:ef", ":", 0)    = ["ab", "cd", "ef"]
 StringUtils.split("ab:cd:ef", ":", 2)    = ["ab", "cdef"]
 

Parameters:
str - the String to parse, may be null
separatorChars - the characters used as the delimiters, null splits on whitespace
max - the maximum number of elements to include in the array. A zero or negative value implies no limit

Returns:
an array of parsed Strings, null if null String input


split

public static String[] split(String str,
                             char separatorChar)
Splits the provided text into an array, separator specified. This is an alternative to using StringTokenizer.

The separator is not included in the returned String array. Adjacent separators are treated as one separator.

A null input String returns null.

 StringUtils.split(null, *)         = null
 StringUtils.split("", *)           = []
 StringUtils.split("a.b.c", '.')    = ["a", "b", "c"]
 StringUtils.split("a..b.c", '.')   = ["a", "b", "c"]
 StringUtils.split("a:b:c", '.')    = ["a:b:c"]
 StringUtils.split("a\tb\nc", null) = ["a", "b", "c"]
 StringUtils.split("a b c", ' ')    = ["a", "b", "c"]
 

Parameters:
str - the String to parse, may be null
separatorChar - the character used as the delimiter, null splits on whitespace

Returns:
an array of parsed Strings, null if null String input

Since:
2.0


strip

public static String strip(String str)
Strips whitespace from the start and end of a String.

This is similar to trim(String) but removes whitespace. Whitespace is defined by Character.isWhitespace(char).

A null input String returns null.

 StringUtils.strip(null)     = null
 StringUtils.strip("")       = ""
 StringUtils.strip("   ")    = ""
 StringUtils.strip("abc")    = "abc"
 StringUtils.strip("  abc")  = "abc"
 StringUtils.strip("abc  ")  = "abc"
 StringUtils.strip(" abc ")  = "abc"
 StringUtils.strip(" ab c ") = "ab c"
 

Parameters:
str - the String to remove whitespace from, may be null

Returns:
the stripped String, null if null String input


strip

public static String strip(String str,
                           String stripChars)
Strips any of a set of characters from the start and end of a String. This is similar to String.trim() but allows the characters to be stripped to be controlled.

A null input String returns null. An empty string ("") input returns the empty string.

If the stripChars String is null, whitespace is stripped as defined by Character.isWhitespace(char). Alternatively use strip(String).

 StringUtils.strip(null, *)          = null
 StringUtils.strip("", *)            = ""
 StringUtils.strip("abc", null)      = "abc"
 StringUtils.strip("  abc", null)    = "abc"
 StringUtils.strip("abc  ", null)    = "abc"
 StringUtils.strip(" abc ", null)    = "abc"
 StringUtils.strip("  abcyx", "xyz") = "  abc"
 

Parameters:
str - the String to remove characters from, may be null
stripChars - the characters to remove, null treated as whitespace

Returns:
the stripped String, null if null String input


stripAll

public static String[] stripAll(String[] strs)
Strips whitespace from the start and end of every String in an array. Whitespace is defined by Character.isWhitespace(char).

A new array is returned each time, except for length zero. A null array will return null. An empty array will return itself. A null array entry will be ignored.

 StringUtils.stripAll(null)             = null
 StringUtils.stripAll([])               = []
 StringUtils.stripAll(["abc", "  abc"]) = ["abc", "abc"]
 StringUtils.stripAll(["abc  ", null])  = ["abc", null]
 

Parameters:
strs - the array to remove whitespace from, may be null

Returns:
the stripped Strings, null if null array input


stripAll

public static String[] stripAll(String[] strs,
                                String stripChars)
Strips any of a set of characters from the start and end of every String in an array. Whitespace is defined by Character.isWhitespace(char).

A new array is returned each time, except for length zero. A null array will return null. An empty array will return itself. A null array entry will be ignored. A null stripChars will strip whitespace as defined by Character.isWhitespace(char).

 StringUtils.stripAll(null, *)                = null
 StringUtils.stripAll([], *)                  = []
 StringUtils.stripAll(["abc", "  abc"], null) = ["abc", "abc"]
 StringUtils.stripAll(["abc  ", null], null)  = ["abc", null]
 StringUtils.stripAll(["abc  ", null], "yz")  = ["abc  ", null]
 StringUtils.stripAll(["yabcz", null], "yz")  = ["abc", null]
 

Parameters:
strs - the array to remove characters from, may be null
stripChars - the characters to remove, null treated as whitespace

Returns:
the stripped Strings, null if null array input


stripEnd

public static String stripEnd(String str,
                              String stripChars)
Strips any of a set of characters from the end of a String.

A null input String returns null. An empty string ("") input returns the empty string.

If the stripChars String is null, whitespace is stripped as defined by Character.isWhitespace(char).

 StringUtils.stripEnd(null, *)          = null
 StringUtils.stripEnd("", *)            = ""
 StringUtils.stripEnd("abc", "")        = "abc"
 StringUtils.stripEnd("abc", null)      = "abc"
 StringUtils.stripEnd("  abc", null)    = "  abc"
 StringUtils.stripEnd("abc  ", null)    = "abc"
 StringUtils.stripEnd(" abc ", null)    = " abc"
 StringUtils.stripEnd("  abcyx", "xyz") = "  abc"
 

Parameters:
str - the String to remove characters from, may be null
stripChars - the characters to remove, null treated as whitespace

Returns:
the stripped String, null if null String input


stripStart

public static String stripStart(String str,
                                String stripChars)
Strips any of a set of characters from the start of a String.

A null input String returns null. An empty string ("") input returns the empty string.

If the stripChars String is null, whitespace is stripped as defined by Character.isWhitespace(char).

 StringUtils.stripStart(null, *)          = null
 StringUtils.stripStart("", *)            = ""
 StringUtils.stripStart("abc", "")        = "abc"
 StringUtils.stripStart("abc", null)      = "abc"
 StringUtils.stripStart("  abc", null)    = "abc"
 StringUtils.stripStart("abc  ", null)    = "abc  "
 StringUtils.stripStart(" abc ", null)    = "abc "
 StringUtils.stripStart("yxabc  ", "xyz") = "abc  "
 

Parameters:
str - the String to remove characters from, may be null
stripChars - the characters to remove, null treated as whitespace

Returns:
the stripped String, null if null String input


stripToEmpty

public static String stripToEmpty(String str)
Strips whitespace from the start and end of a String returning an empty String if null input.

This is similar to trimToEmpty(String) but removes whitespace. Whitespace is defined by Character.isWhitespace(char).

 StringUtils.strip(null)     = ""
 StringUtils.strip("")       = ""
 StringUtils.strip("   ")    = ""
 StringUtils.strip("abc")    = "abc"
 StringUtils.strip("  abc")  = "abc"
 StringUtils.strip("abc  ")  = "abc"
 StringUtils.strip(" abc ")  = "abc"
 StringUtils.strip(" ab c ") = "ab c"
 

Parameters:
str - the String to be stripped, may be null

Returns:
the trimmed String, or an empty String if null input

Since:
2.0


stripToNull

public static String stripToNull(String str)
Strips whitespace from the start and end of a String returning null if the String is empty ("") after the strip.

This is similar to trimToNull(String) but removes whitespace. Whitespace is defined by Character.isWhitespace(char).

 StringUtils.strip(null)     = null
 StringUtils.strip("")       = null
 StringUtils.strip("   ")    = null
 StringUtils.strip("abc")    = "abc"
 StringUtils.strip("  abc")  = "abc"
 StringUtils.strip("abc  ")  = "abc"
 StringUtils.strip(" abc ")  = "abc"
 StringUtils.strip(" ab c ") = "ab c"
 

Parameters:
str - the String to be stripped, may be null

Returns:
the stripped String, null if whitespace, empty or null String input

Since:
2.0


substring

public static String substring(String str,
                               int start)
Gets a substring from the specified String avoiding exceptions.

A negative start position can be used to start n characters from the end of the String.

A null String will return null. An empty ("") String will return "".

 StringUtils.substring(null, *)   = null
 StringUtils.substring("", *)     = ""
 StringUtils.substring("abc", 0)  = "abc"
 StringUtils.substring("abc", 2)  = "c"
 StringUtils.substring("abc", 4)  = ""
 StringUtils.substring("abc", -2) = "bc"
 StringUtils.substring("abc", -4) = "abc"
 

Parameters:
str - the String to get the substring from, may be null
start - the position to start from, negative means count back from the end of the String by this many characters

Returns:
substring from start position, null if null String input


substring

public static String substring(String str,
                               int start,
                               int end)
Gets a substring from the specified String avoiding exceptions.

A negative start position can be used to start/end n characters from the end of the String.

The returned substring starts with the character in the start position and ends before the end position. All postion counting is zero-based -- i.e., to start at the beginning of the string use start = 0. Negative start and end positions can be used to specify offsets relative to the end of the String.

If start is not strictly to the left of end, "" is returned.

 StringUtils.substring(null, *, *)    = null
 StringUtils.substring("", * ,  *)    = "";
 StringUtils.substring("abc", 0, 2)   = "ab"
 StringUtils.substring("abc", 2, 0)   = ""
 StringUtils.substring("abc", 2, 4)   = "c"
 StringUtils.substring("abc", 4, 6)   = ""
 StringUtils.substring("abc", 2, 2)   = ""
 StringUtils.substring("abc", -2, -1) = "b"
 StringUtils.substring("abc", -4, 2)  = "ab"
 

Parameters:
str - the String to get the substring from, may be null
start - the position to start from, negative means count back from the end of the String by this many characters
end - the position to end at (exclusive), negative means count back from the end of the String by this many characters

Returns:
substring from start position to end positon, null if null String input


substringAfter

public static String substringAfter(String str,
                                    String separator)
Gets the substring after the first occurance of a separator. The separator is not returned.

A null string input will return null. An empty ("") string input will return the empty string. A null separator will return the empty string if the input string is not null.

 StringUtils.substringAfter(null, *)      = null
 StringUtils.substringAfter("", *)        = ""
 StringUtils.substringAfter(*, null)      = ""
 StringUtils.substringAfter("abc", "a")   = "bc"
 StringUtils.substringAfter("abcba", "b") = "cba"
 StringUtils.substringAfter("abc", "c")   = ""
 StringUtils.substringAfter("abc", "d")   = ""
 StringUtils.substringAfter("abc", "")    = "abc"
 

Parameters:
str - the String to get a substring from, may be null
separator - the String to search for, may be null

Returns:
the substring after the first occurance of the separator, null if null String input

Since:
2.0


substringAfterLast

public static String substringAfterLast(String str,
                                        String separator)
Gets the substring after the last occurance of a separator. The separator is not returned.

A null string input will return null. An empty ("") string input will return the empty string. An empty or null separator will return the empty string if the input string is not null.

 StringUtils.substringAfterLast(null, *)      = null
 StringUtils.substringAfterLast("", *)        = ""
 StringUtils.substringAfterLast(*, "")        = ""
 StringUtils.substringAfterLast(*, null)      = ""
 StringUtils.substringAfterLast("abc", "a")   = "bc"
 StringUtils.substringAfterLast("abcba", "b") = "a"
 StringUtils.substringAfterLast("abc", "c")   = ""
 StringUtils.substringAfterLast("a", "a")     = ""
 StringUtils.substringAfterLast("a", "z")     = ""
 

Parameters:
str - the String to get a substring from, may be null
separator - the String to search for, may be null

Returns:
the substring after the last occurance of the separator, null if null String input

Since:
2.0


substringBefore

public static String substringBefore(String str,
                                     String separator)
Gets the substring before the first occurance of a separator. The separator is not returned.

A null string input will return null. An empty ("") string input will return the empty string. A null separator will return the input string.

 StringUtils.substringBefore(null, *)      = null
 StringUtils.substringBefore("", *)        = ""
 StringUtils.substringBefore("abc", "a")   = ""
 StringUtils.substringBefore("abcba", "b") = "a"
 StringUtils.substringBefore("abc", "c")   = "ab"
 StringUtils.substringBefore("abc", "d")   = "abc"
 StringUtils.substringBefore("abc", "")    = ""
 StringUtils.substringBefore("abc", null)  = "abc"
 

Parameters:
str - the String to get a substring from, may be null
separator - the String to search for, may be null

Returns:
the substring before the first occurance of the separator, null if null String input

Since:
2.0


substringBeforeLast

public static String substringBeforeLast(String str,
                                         String separator)
Gets the substring before the last occurance of a separator. The separator is not returned.

A null string input will return null. An empty ("") string input will return the empty string. An empty or null separator will return the input string.

 StringUtils.substringBeforeLast(null, *)      = null
 StringUtils.substringBeforeLast("", *)        = ""
 StringUtils.substringBeforeLast("abcba", "b") = "abc"
 StringUtils.substringBeforeLast("abc", "c")   = "ab"
 StringUtils.substringBeforeLast("a", "a")     = ""
 StringUtils.substringBeforeLast("a", "z")     = "a"
 StringUtils.substringBeforeLast("a", null)    = "a"
 StringUtils.substringBeforeLast("a", "")      = "a"
 

Parameters:
str - the String to get a substring from, may be null
separator - the String to search for, may be null

Returns:
the substring before the last occurance of the separator, null if null String input

Since:
2.0


substringBetween

public static String substringBetween(String str,
                                      String tag)
Gets the String that is nested in between two instances of the same String.

A null input String returns null. A null tag returns null.

 StringUtils.substringBetween(null, *)            = null
 StringUtils.substringBetween("", "")             = ""
 StringUtils.substringBetween("", "tag")          = null
 StringUtils.substringBetween("tagabctag", null)  = null
 StringUtils.substringBetween("tagabctag", "")    = ""
 StringUtils.substringBetween("tagabctag", "tag") = "abc"
 

Parameters:
str - the String containing the substring, may be null
tag - the String before and after the substring, may be null

Returns:
the substring, null if no match

Since:
2.0


substringBetween

public static String substringBetween(String str,
                                      String open,
                                      String close)
Gets the String that is nested in between two Strings. Only the first match is returned.

A null input String returns null. A null open/close returns null (no match). An empty ("") open/close returns an empty string.

 StringUtils.substringBetween(null, *, *)          = null
 StringUtils.substringBetween("", "", "")          = ""
 StringUtils.substringBetween("", "", "tag")       = null
 StringUtils.substringBetween("", "tag", "tag")    = null
 StringUtils.substringBetween("yabcz", null, null) = null
 StringUtils.substringBetween("yabcz", "", "")     = ""
 StringUtils.substringBetween("yabcz", "y", "z")   = "abc"
 StringUtils.substringBetween("yabczyabcz", "y", "z")   = "abc"
 

Parameters:
str - the String containing the substring, may be null
open - the String before the substring, may be null
close - the String after the substring, may be null

Returns:
the substring, null if no match

Since:
2.0


swapCase

public static String swapCase(String str)
Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
  • Upper case character converts to Lower case
  • Title case character converts to Lower case
  • Lower case character converts to Upper case

For a word based alorithm, see WordUtils.swapCase(String). A null input String returns null.

 StringUtils.swapCase(null)                 = null
 StringUtils.swapCase("")                   = ""
 StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"
 

NOTE: This method changed in Lang version 2.0. It no longer performs a word based alorithm. If you only use ASCII, you will notice no change. That functionality is available in WordUtils.

Parameters:
str - the String to swap case, may be null

Returns:
the changed String, null if null String input


trim

public static String trim(String str)
Removes control characters (char <= 32) from both ends of this String, handling null by returning null.

The String is trimmed using String.trim(). Trim removes start and end characters <= 32. To strip whitespace use strip(String).

To trim your choice of characters, use the strip(String,String) methods.

 StringUtils.trim(null)          = null
 StringUtils.trim("")            = ""
 StringUtils.trim("     ")       = ""
 StringUtils.trim("abc")         = "abc"
 StringUtils.trim("    abc    ") = "abc"
 

Parameters:
str - the String to be trimmed, may be null

Returns:
the trimmed string, null if null String input


trimToEmpty

public static String trimToEmpty(String str)

Parameters:
str - the String to be trimmed, may be null

Returns:
the trimmed String, or an empty String if null input

Since:
2.0


trimToNull

public static String trimToNull(String str)

Parameters:
str - the String to be trimmed, may be null

Returns:
the trimmed String, null if only chars <= 32, empty or null String input

Since:
2.0


uncapitalise

public static String uncapitalise(String str)

Deprecated. Use the standardly named uncapitalize(String). Method will be removed in Commons Lang 3.0.

Uncapitalizes a String changing the first letter to title case as per Character.toLowerCase(char). No other letters are changed.

Parameters:
str - the String to uncapitalize, may be null

Returns:
the uncapitalized String, null if null String input


uncapitalize

public static String uncapitalize(String str)
Uncapitalizes a String changing the first letter to title case as per Character.toLowerCase(char). No other letters are changed.

For a word based alorithm, see WordUtils.uncapitalize(String). A null input String returns null.

 StringUtils.uncapitalize(null)  = null
 StringUtils.uncapitalize("")    = ""
 StringUtils.uncapitalize("Cat") = "cat"
 StringUtils.uncapitalize("CAT") = "cAT"
 

Parameters:
str - the String to uncapitalize, may be null

Returns:
the uncapitalized String, null if null String input

Since:
2.0

See Also:
WordUtils.uncapitalize(String), capitalize(String)


upperCase

public static String upperCase(String str)
Converts a String to upper case as per String.toUpperCase().

A null input String returns null.

 StringUtils.upperCase(null)  = null
 StringUtils.upperCase("")    = ""
 StringUtils.upperCase("aBc") = "ABC"
 

Parameters:
str - the String to upper case, may be null

Returns:
the upper cased String, null if null String input


Copyright © 2001-2003 - Apache Software Foundation