Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
org.apache.commons.lang.StringUtils
public class StringUtils
extends Object
String
that are
null
safe.
StringUtils
class defines certain words related to
String handling.
null
""
)' '
, char 32)Character.isWhitespace(char)
String.trim()
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
.
String
Field Summary | |
static String |
|
static int |
|
Constructor Summary | |
|
Method Summary | |
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static int |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static boolean |
|
static boolean |
|
static String |
|
static String |
|
static int |
|
static String |
|
static String |
|
static String |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static int |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String[] |
|
static String[] |
|
static String[] |
|
static String[] |
|
static String[] |
|
static String[] |
|
static String[] |
|
static String[] |
|
static String[] |
|
static String[] |
|
static String |
|
static String |
|
static String[] |
|
static String[] |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
static String |
|
public static final String EMPTY
The empty String""
.
- Since:
- 2.0
public static final int INDEX_NOT_FOUND
Represents a failed index search.
- Field Value:
- -1
- Since:
- 2.1
public StringUtils()
StringUtils
instances should NOT be constructed in standard programming. Instead, the class should be used asStringUtils.trim(" foo ");
. This constructor is public to permit tools that require a JavaBean instance to operate.
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 thanmaxWidth
characters long, return it.- Else abbreviate it to
(substring(str, 0, max-3) + "...")
.- If
maxWidth
is less than4
, throw anIllegalArgumentException
.- 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 nullmaxWidth
- maximum length of result String, must be at least 4
- Returns:
- abbreviated String,
null
if null String input
- Since:
- 2.0
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 likeabbreviate(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 thanmaxWidth
.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 nulloffset
- left edge of source StringmaxWidth
- maximum length of result String, must be at least 4
- Returns:
- abbreviated String,
null
if null String input
- Since:
- 2.0
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 perCharacter.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
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 byCharacter.isWhitespace(char)
. Anull
input String returnsnull
.
- Parameters:
str
- the String to capitalize, may be null
- Returns:
- capitalized String,
null
if null String input
public static String capitalize(String str)
Capitalizes a String changing the first letter to title case as perCharacter.toTitleCase(char)
. No other letters are changed. For a word based algorithm, seeWordUtils.capitalize(String)
. Anull
input String returnsnull
.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
public static String center(String str, int size)
Centers a String in a larger String of sizesize
using the space character (' '). If the size is less than the String length, the String is returned. Anull
String returnsnull
. A negative size is treated as zero. Equivalent tocenter(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 nullsize
- the int size of new String, negative treated as zero
- Returns:
- centered String,
null
if null String input
public static String center(String str, int size, String padStr)
Centers a String in a larger String of sizesize
. 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. Anull
String returnsnull
. 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 nullsize
- the int size of new String, negative treated as zeropadStr
- the String to pad the new String with, must not be null or empty
- Returns:
- centered String,
null
if null String input
public static String center(String str, int size, char padChar)
Centers a String in a larger String of sizesize
. 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. Anull
String returnsnull
. 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 nullsize
- the int size of new String, negative treated as zeropadChar
- the character to pad the new String with
- Returns:
- centered String,
null
if null String input
- Since:
- 2.0
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
public static String chomp(String str, String separator)
Removesseparator
from the end ofstr
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, usesubstringBeforeLast(String,String)
. This method usesString.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 nullseparator
- separator String, may be null
- Returns:
- String without trailing separator,
null
if null String input
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
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 nullsep
- the String to chomp, must not be null
- Returns:
- String without chomped ending
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
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
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, handlingnull
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:
String.trim()
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
public static boolean contains(String str, String searchStr)
Checks if String contains a search String, handlingnull
. This method usesString.indexOf(int)
. Anull
String will returnfalse
.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 nullsearchStr
- the String to find, may be null
- Returns:
- true if the String contains the search String, false if not or
null
string input
- Since:
- 2.0
public static boolean contains(String str, char searchChar)
Checks if String contains a search character, handlingnull
. This method usesString.indexOf(int)
. Anull
or empty ("") String will returnfalse
.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 nullsearchChar
- the character to find
- Returns:
- true if the String contains the search character, false if not or
null
string input
- Since:
- 2.0
public static boolean containsNone(String str, String invalidChars)
Checks that the String does not contain certain characters. Anull
String will returntrue
. Anull
invalid character array will returntrue
. 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 nullinvalidChars
- a String of invalid chars, may be null
- Returns:
- true if it contains none of the invalid chars, or is null
- Since:
- 2.0
public static boolean containsNone(String str, char[] invalidChars)
Checks that the String does not contain certain characters. Anull
String will returntrue
. Anull
invalid character array will returntrue
. 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 nullinvalidChars
- an array of invalid chars, may be null
- Returns:
- true if it contains none of the invalid chars, or is null
- Since:
- 2.0
public static boolean containsOnly(String str, String validChars)
Checks if the String contains only certain characters. Anull
String will returnfalse
. Anull
valid character String will returnfalse
. An empty String ("") always returnstrue
.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 nullvalidChars
- a String of valid chars, may be null
- Returns:
- true if it only contains valid chars and is non-null
- Since:
- 2.0
public static boolean containsOnly(String str, char[] valid)
Checks if the String contains only certain characters. Anull
String will returnfalse
. Anull
valid character array will returnfalse
. An empty String ("") always returnstrue
.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 nullvalid
- an array of valid chars, may be null
- Returns:
- true if it only contains valid chars and is non-null
public static int countMatches(String str, String sub)
Counts how many times the substring appears in the larger String. Anull
or empty ("") String input returns0
.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 nullsub
- the substring to count, may be null
- Returns:
- the number of occurrences, 0 if either String is
null
public static String defaultIfEmpty(String str, String defaultStr)
Returns either the passed in String, or if the String is empty ornull
, the value ofdefaultStr
.StringUtils.defaultIfEmpty(null, "NULL") = "NULL" StringUtils.defaultIfEmpty("", "NULL") = "NULL" StringUtils.defaultIfEmpty("bat", "NULL") = "bat"
- Parameters:
str
- the String to check, may be nulldefaultStr
- the default String to return if the input is empty ("") ornull
, may be null
- Returns:
- the passed in String, or the default
- See Also:
defaultString(String,String)
public static String defaultString(String str)
Returns either the passed in String, or if the String isnull
, 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)
public static String defaultString(String str, String defaultStr)
Returns either the passed in String, or if the String isnull
, the value ofdefaultStr
.StringUtils.defaultString(null, "NULL") = "NULL" StringUtils.defaultString("", "NULL") = "" StringUtils.defaultString("bat", "NULL") = "bat"
- Parameters:
str
- the String to check, may be nulldefaultStr
- the default String to return if the input isnull
, may be null
- Returns:
- the passed in String, or the default if it was
null
- See Also:
ObjectUtils.toString(Object,String)
,String.valueOf(Object)
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 byCharacter.isSpace(char)
. This is the only StringUtils method that uses theisSpace
definition. You are advised to usedeleteWhitespace(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 deprecatedisSpace
method.
- Parameters:
str
- the String to delete spaces from, may be null
- Returns:
- the String without 'spaces',
null
if null String input
public static String deleteWhitespace(String str)
Deletes all whitespaces from a String as defined byCharacter.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
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 nullstr2
- 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
public static boolean equals(String str1, String str2)
Compares two Strings, returningtrue
if they are equal.null
s are handled without exceptions. Twonull
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 nullstr2
- the second String, may be null
- Returns:
true
if the Strings are equal, case sensitive, or bothnull
- See Also:
String.equals(Object)
public static boolean equalsIgnoreCase(String str1, String str2)
Compares two Strings, returningtrue
if they are equal ignoring the case.null
s are handled without exceptions. Twonull
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 nullstr2
- the second String, may be null
- Returns:
true
if the Strings are equal, case insensitive, or bothnull
- See Also:
String.equalsIgnoreCase(String)
public static String escape(String str)
Deprecated. Use
StringEscapeUtils.escapeJava(String)
This method will be removed in Commons Lang 3.0Escapes any values it finds into their String form. So a tab becomes the characters'\\'
and't'
. As of Lang 2.0, this callsStringEscapeUtils.escapeJava(String)
behind the scenes.
- Parameters:
str
- String to escape values in
- Returns:
- String with escaped values
- See Also:
StringEscapeUtils.escapeJava(java.lang.String)
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 nullsep
- the String to chomp, must not be null
- Returns:
- String chomped
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.htmStringUtils.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 nullt
- the second String, must not be null
- Returns:
- result distance
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. Anull
input String returnsnull
. Anull
tag returnsnull
.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 nulltag
- the String before and after nested-string, may be null
- Returns:
- the nested String,
null
if no match
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. Anull
input String returnsnull
. Anull
open/close returnsnull
(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 nullopen
- the String before nested-string, may be nullclose
- the String after nested-string, may be null
- Returns:
- the nested String,
null
if no match
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 nullsep
- the String to chomp, must not be null
- Returns:
- String prechomped
public static int indexOf(String str, String searchStr)
Finds the first index within a String, handlingnull
. This method usesString.indexOf(String)
. Anull
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 nullsearchStr
- 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
public static int indexOf(String str, String searchStr, int startPos)
Finds the first index within a String, handlingnull
. This method usesString.indexOf(String, int)
. Anull
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 nullsearchStr
- the String to find, may be nullstartPos
- 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
public static int indexOf(String str, char searchChar)
Finds the first index within a String, handlingnull
. This method usesString.indexOf(int)
. Anull
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 nullsearchChar
- the character to find
- Returns:
- the first index of the search character, -1 if no match or
null
string input
- Since:
- 2.0
public static int indexOf(String str, char searchChar, int startPos)
Finds the first index within a String from a start position, handlingnull
. This method usesString.indexOf(int, int)
. Anull
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 nullsearchChar
- the character to findstartPos
- 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
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. Anull
String will return-1
. Anull
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 nullsearchChars
- 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
public static int indexOfAny(String str, String[] searchStrs)
Find the first index of any of a set of potential substrings. Anull
String will return-1
. Anull
or zero length search array will return-1
. Anull
search array entry will be ignored, but a search array containing "" will return0
ifstr
is not null. This method usesString.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 nullsearchStrs
- the Strings to search for, may be null
- Returns:
- the first index of any of the searchStrs in str, -1 if no match
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. Anull
String will return-1
. Anull
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 nullsearchChars
- 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
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. Anull
String will return-1
. Anull
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 nullsearchChars
- 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
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. Anull
String will return-1
. Anull
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 nullsearchChars
- 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
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 nullstr2
- the second String, may be null
- Returns:
- the index where str2 and str1 begin to differ; -1 if they are equal
- Since:
- 2.0
public static boolean isAlpha(String str)
Checks if the String contains only unicode letters.null
will returnfalse
. An empty String ("") will returntrue
.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
public static boolean isAlphaSpace(String str)
Checks if the String contains only unicode letters and space (' ').null
will returnfalse
An empty String ("") will returntrue
.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
public static boolean isAlphanumeric(String str)
Checks if the String contains only unicode letters or digits.null
will returnfalse
. An empty String ("") will returntrue
.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
public static boolean isAlphanumericSpace(String str)
Checks if the String contains only unicode letters, digits or space (' '
).null
will returnfalse
. An empty String ("") will returntrue
.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
public static boolean isAsciiPrintable(String str)
Checks if the string contains only ASCII printable characters.null
will returnfalse
. An empty String ("") will returntrue
.StringUtils.isAsciiPrintable(null) = false StringUtils.isAsciiPrintable("") = true StringUtils.isAsciiPrintable(" ") = true StringUtils.isAsciiPrintable("Ceki") = true StringUtils.isAsciiPrintable("ab2c") = true StringUtils.isAsciiPrintable("!ab-c~") = true StringUtils.isAsciiPrintable("\u0020") = true StringUtils.isAsciiPrintable("\u0021") = true StringUtils.isAsciiPrintable("\u007e") = true StringUtils.isAsciiPrintable("\u007f") = false StringUtils.isAsciiPrintable("Ceki G\u00fclc\u00fc") = false
- Parameters:
str
- the string to check, may be null
- Returns:
true
if every character is in the range 32 thru 126
- Since:
- 2.1
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
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 ") = falseNOTE: 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
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
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
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 returnfalse
. An empty String ("") will returntrue
.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
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 returnfalse
. An empty String ("") will returntrue
.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
public static boolean isWhitespace(String str)
Checks if the String contains only whitespace.null
will returnfalse
. An empty String ("") will returntrue
.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
public static String join(Iterator iterator, String separator)
Joins the elements of the providedIterator
into a single String containing the provided elements. No delimiter is added before or after the list. Anull
separator is the same as an empty String (""). See the examples here:join(Object[],String)
.
- Parameters:
iterator
- theIterator
of values to join together, may be nullseparator
- the separator character to use, null treated as ""
- Returns:
- the joined String,
null
if null iterator input
public static String join(Iterator iterator, char separator)
Joins the elements of the providedIterator
into a single String containing the provided elements. No delimiter is added before or after the list. Null objects or empty strings within the iteration are represented by empty strings. See the examples here:join(Object[],char)
.
- Parameters:
iterator
- theIterator
of values to join together, may be nullseparator
- the separator character to use
- Returns:
- the joined String,
null
if null iterator input
- Since:
- 2.0
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
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. Anull
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 nullseparator
- the separator character to use, null treated as ""
- Returns:
- the joined String,
null
if null array input
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 nullseparator
- the separator character to use
- Returns:
- the joined String,
null
if null array input
- Since:
- 2.0
public static int lastIndexOf(String str, String searchStr)
Finds the last index within a String, handlingnull
. This method usesString.lastIndexOf(String)
. Anull
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 nullsearchStr
- 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
public static int lastIndexOf(String str, String searchStr, int startPos)
Finds the first index within a String, handlingnull
. This method usesString.lastIndexOf(String, int)
. Anull
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 nullsearchStr
- the String to find, may be nullstartPos
- 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
public static int lastIndexOf(String str, char searchChar)
Finds the last index within a String, handlingnull
. This method usesString.lastIndexOf(int)
. Anull
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 nullsearchChar
- the character to find
- Returns:
- the last index of the search character, -1 if no match or
null
string input
- Since:
- 2.0
public static int lastIndexOf(String str, char searchChar, int startPos)
Finds the last index within a String from a start position, handlingnull
. This method usesString.lastIndexOf(int, int)
. Anull
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 nullsearchChar
- the character to findstartPos
- the start position
- Returns:
- the last index of the search character, -1 if no match or
null
string input
- Since:
- 2.0
public static int lastIndexOfAny(String str, String[] searchStrs)
Find the latest index of any of a set of potential substrings. Anull
String will return-1
. Anull
search array will return-1
. Anull
or zero length search array entry will be ignored, but a search array containing "" will return the length ofstr
ifstr
is not null. This method usesString.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 nullsearchStrs
- the Strings to search for, may be null
- Returns:
- the last index of any of the Strings, -1 if no match
public static String left(String str, int len)
Gets the leftmostlen
characters of a String. Iflen
characters are not available, or the String isnull
, 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 nulllen
- the length of the required String, must be zero or positive
- Returns:
- the leftmost characters,
null
if null String input
public static String leftPad(String str, int size)
Left pad a String with spaces (' '). The String is padded to the size ofsize
.
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 nullsize
- the size to pad to
- Returns:
- left padded String or original String if no padding is necessary,
null
if null String input
public static String leftPad(String str, int size, String padStr)
Left pad a String with a specified String. Pad to a size ofsize
.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 nullsize
- the size to pad topadStr
- 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
public static String leftPad(String str, int size, char padChar)
Left pad a String with a specified character. Pad to a size ofsize
.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 nullsize
- the size to pad topadChar
- 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
public static String lowerCase(String str)
Converts a String to lower case as perString.toLowerCase()
. Anull
input String returnsnull
.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
public static String mid(String str, int pos, int len)
Getslen
characters from the middle of a String. Iflen
characters are not available, the remainder of the String will be returned without an exception. If the String isnull
,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 nullpos
- the position to start from, negative treated as zerolen
- the length of the required String, must be zero or positive
- Returns:
- the middle characters,
null
if null String input
public static int ordinalIndexOf(String str, String searchStr, int ordinal)
Finds the n-th index within a String, handlingnull
. This method usesString.indexOf(String)
. Anull
String will return-1
.StringUtils.ordinalIndexOf(null, *, *) = -1 StringUtils.ordinalIndexOf(*, null, *) = -1 StringUtils.ordinalIndexOf("", "", *) = 0 StringUtils.ordinalIndexOf("aabaabaa", "a", 1) = 0 StringUtils.ordinalIndexOf("aabaabaa", "a", 2) = 1 StringUtils.ordinalIndexOf("aabaabaa", "b", 1) = 2 StringUtils.ordinalIndexOf("aabaabaa", "b", 2) = 5 StringUtils.ordinalIndexOf("aabaabaa", "ab", 1) = 1 StringUtils.ordinalIndexOf("aabaabaa", "ab", 2) = 4 StringUtils.ordinalIndexOf("aabaabaa", "", 1) = 0 StringUtils.ordinalIndexOf("aabaabaa", "", 2) = 0
- Parameters:
str
- the String to check, may be nullsearchStr
- the String to find, may be nullordinal
- the n-thsearchStr
to find
- Returns:
- the n-th index of the search String,
-1
(INDEX_NOT_FOUND
) if no match ornull
string input
- Since:
- 2.1
public static String overlay(String str, String overlay, int start, int end)
Overlays part of a String with another String. Anull
string input returnsnull
. 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 nulloverlay
- the String to overlay, may be nullstart
- the position to start overlaying atend
- the position to stop overlaying before
- Returns:
- overlayed String,
null
if null String input
- Since:
- 2.0
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 nulloverlay
- the String to overlay, may be nullstart
- the position to start overlaying at, must be validend
- the position to stop overlaying before, must be valid
- Returns:
- overlayed String,
null
if null String input
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 nullsep
- the String to chomp, must not be null
- Returns:
- String without chomped beginning
public static String remove(String str, String remove)
Removes all occurances of a substring from within the source string. Anull
source string will returnnull
. An empty ("") source string will return the empty string. Anull
remove string will return the source string. An empty ("") remove string will return the source string.StringUtils.remove(null, *) = null StringUtils.remove("", *) = "" StringUtils.remove(*, null) = * StringUtils.remove(*, "") = * StringUtils.remove("queued", "ue") = "qd" StringUtils.remove("queued", "zz") = "queued"
- Parameters:
str
- the source String to search, may be nullremove
- the String to search for and remove, may be null
- Returns:
- the substring with the string removed if found,
null
if null String input
- Since:
- 2.1
public static String remove(String str, char remove)
Removes all occurances of a character from within the source string. Anull
source string will returnnull
. An empty ("") source string will return the empty string.StringUtils.remove(null, *) = null StringUtils.remove("", *) = "" StringUtils.remove("queued", 'u') = "qeed" StringUtils.remove("queued", 'z') = "queued"
- Parameters:
str
- the source String to search, may be nullremove
- the char to search for and remove, may be null
- Returns:
- the substring with the char removed if found,
null
if null String input
- Since:
- 2.1
public static String removeEnd(String str, String remove)
Removes a substring only if it is at the end of a source string, otherwise returns the source string. Anull
source string will returnnull
. An empty ("") source string will return the empty string. Anull
search string will return the source string.StringUtils.removeEnd(null, *) = null StringUtils.removeEnd("", *) = "" StringUtils.removeEnd(*, null) = * StringUtils.removeEnd("www.domain.com", ".com.") = "www,domain" StringUtils.removeEnd("www.domain.com", ".com") = "www.domain" StringUtils.removeEnd("www.domain.com", "domain") = "www.domain.com" StringUtils.removeEnd("abc", "") = "abc"
- Parameters:
str
- the source String to search, may be nullremove
- the String to search for and remove, may be null
- Returns:
- the substring with the string removed if found,
null
if null String input
- Since:
- 2.1
public static String removeStart(String str, String remove)
Removes a substring only if it is at the begining of a source string, otherwise returns the source string. Anull
source string will returnnull
. An empty ("") source string will return the empty string. Anull
search string will return the source string.StringUtils.removeStart(null, *) = null StringUtils.removeStart("", *) = "" StringUtils.removeStart(*, null) = * StringUtils.removeStart("www.domain.com", "www.") = "domain.com" StringUtils.removeStart("domain.com", "www.") = "domain.com" StringUtils.removeStart("www.domain.com", "domain") = "www.domain.com" StringUtils.removeStart("abc", "") = "abc"
- Parameters:
str
- the source String to search, may be nullremove
- the String to search for and remove, may be null
- Returns:
- the substring with the string removed if found,
null
if null String input
- Since:
- 2.1
public static String repeat(String str, int repeat)
Repeat a Stringrepeat
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 nullrepeat
- 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
public static String replace(String text, String repl, String with)
Replaces all occurrences of a String within another String. Anull
reference passed to this method is a no-op.StringUtils.replace(null, *, *) = null StringUtils.replace("", *, *) = "" StringUtils.replace("any", null, *) = "any" StringUtils.replace("any", *, null) = "any" StringUtils.replace("any", "", *) = "any" StringUtils.replace("aba", "a", null) = "aba" StringUtils.replace("aba", "a", "") = "b" StringUtils.replace("aba", "a", "z") = "zbz"
- Parameters:
text
- text to search and replace in, may be nullrepl
- the String to search for, may be nullwith
- 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)
public static String replace(String text, String repl, String with, int max)
Replaces a String with another String inside a larger String, for the firstmax
values of the search String. Anull
reference passed to this method is a no-op.StringUtils.replace(null, *, *, *) = null StringUtils.replace("", *, *, *) = "" StringUtils.replace("any", null, *, *) = "any" StringUtils.replace("any", *, null, *) = "any" StringUtils.replace("any", "", *, *) = "any" StringUtils.replace("any", *, *, 0) = "any" StringUtils.replace("abaa", "a", null, -1) = "abaa" StringUtils.replace("abaa", "a", "", -1) = "b" 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 nullrepl
- the String to search for, may be nullwith
- the String to replace with, may be nullmax
- maximum number of values to replace, or-1
if no maximum
- Returns:
- the text with any replacements processed,
null
if null String input
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
. Anull
string input returnsnull
. 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 nullsearchChars
- a set of characters to search for, may be nullreplaceChars
- a set of characters to replace, may be null
- Returns:
- modified String,
null
if null string input
- Since:
- 2.0
public static String replaceChars(String str, char searchChar, char replaceChar)
Replaces all occurrences of a character in a String with another. This is a null-safe version ofString.replace(char, char)
. Anull
string input returnsnull
. 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 nullsearchChar
- the character to search for, may be nullreplaceChar
- the character to replace, may be null
- Returns:
- modified String,
null
if null string input
- Since:
- 2.0
public static String replaceOnce(String text, String repl, String with)
Replaces a String with another String inside a larger String, once. Anull
reference passed to this method is a no-op.StringUtils.replaceOnce(null, *, *) = null StringUtils.replaceOnce("", *, *) = "" StringUtils.replaceOnce("any", null, *) = "any" StringUtils.replaceOnce("any", *, null) = "any" StringUtils.replaceOnce("any", "", *) = "any" StringUtils.replaceOnce("aba", "a", null) = "aba" StringUtils.replaceOnce("aba", "a", "") = "ba" StringUtils.replaceOnce("aba", "a", "z") = "zba"
- Parameters:
text
- text to search and replace in, may be nullrepl
- the String to search for, may be nullwith
- 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)
public static String reverse(String str)
Reverses a String as perStringBuffer.reverse()
. Anull
String returnsnull
.StringUtils.reverse(null) = null StringUtils.reverse("") = "" StringUtils.reverse("bat") = "tab"
- Parameters:
str
- the String to reverse, may be null
- Returns:
- the reversed String,
null
if null String input
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 nullseparatorChar
- the separator character to use
- Returns:
- the reversed String,
null
if null String input
- Since:
- 2.0
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 nullseparatorChars
- the separator characters to use, null treated as whitespace
- Returns:
- the reversed String,
null
if null String input
public static String right(String str, int len)
Gets the rightmostlen
characters of a String. Iflen
characters are not available, or the String isnull
, 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 nulllen
- the length of the required String, must be zero or positive
- Returns:
- the rightmost characters,
null
if null String input
public static String rightPad(String str, int size)
Right pad a String with spaces (' '). The String is padded to the size ofsize
.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 nullsize
- the size to pad to
- Returns:
- right padded String or original String if no padding is necessary,
null
if null String input
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 ofsize
.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 nullsize
- the size to pad topadStr
- 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
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 ofsize
.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 nullsize
- the size to pad topadChar
- 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
public static String[] split(String str)
Splits the provided text into an array, using whitespace as the separator. Whitespace is defined byCharacter.isWhitespace(char)
. The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class. Anull
input String returnsnull
.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
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. For more control over the split use the StrTokenizer class. Anull
input String returnsnull
. Anull
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 nullseparatorChars
- the characters used as the delimiters,null
splits on whitespace
- Returns:
- an array of parsed Strings,
null
if null String input
public static String[] split(String str, String separatorChars, int max)
Splits the provided text into an array with a maximum length, separators specified. The separator is not included in the returned String array. Adjacent separators are treated as one separator. Anull
input String returnsnull
. Anull
separatorChars splits on whitespace. If more thanmax
delimited substrings are found, the last returned string includes all characters after the firstmax - 1
returned strings (including separator characters).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", "cd:ef"]
- Parameters:
str
- the String to parse, may be nullseparatorChars
- the characters used as the delimiters,null
splits on whitespacemax
- 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
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. For more control over the split use the StrTokenizer class. Anull
input String returnsnull
.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 nullseparatorChar
- the character used as the delimiter,null
splits on whitespace
- Returns:
- an array of parsed Strings,
null
if null String input
- Since:
- 2.0
public static String[] splitByWholeSeparator(String str, String separator)
Splits the provided text into an array, separator string specified. The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator. Anull
input String returnsnull
. Anull
separator splits on whitespace.StringUtils.split(null, *) = null StringUtils.split("", *) = [] StringUtils.split("ab de fg", null) = ["ab", "de", "fg"] StringUtils.split("ab de fg", null) = ["ab", "de", "fg"] StringUtils.split("ab:cd:ef", ":") = ["ab", "cd", "ef"] StringUtils.split("abstemiouslyaeiouyabstemiously", "aeiouy") = ["bst", "m", "sl", "bst", "m", "sl"] StringUtils.split("abstemiouslyaeiouyabstemiously", "aeiouy") = ["abstemiously", "abstemiously"]
- Parameters:
str
- the String to parse, may be nullseparator
- String containing the String to be used as a delimiter,null
splits on whitespace
- Returns:
- an array of parsed Strings,
null
if null String was input
public static String[] splitByWholeSeparator(String str, String separator, int max)
Splits the provided text into an array, separator string specified. Returns a maximum ofmax
substrings. The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator. Anull
input String returnsnull
. Anull
separator splits on whitespace.StringUtils.splitByWholeSeparator(null, *, *) = null StringUtils.splitByWholeSeparator("", *, *) = [] StringUtils.splitByWholeSeparator("ab de fg", null, 0) = ["ab", "de", "fg"] StringUtils.splitByWholeSeparator("ab de fg", null, 0) = ["ab", "de", "fg"] StringUtils.splitByWholeSeparator("ab:cd:ef", ":", 2) = ["ab", "cd"] StringUtils.splitByWholeSeparator("abstemiouslyaeiouyabstemiously", "aeiouy", 2) = ["bst", "m"] StringUtils.splitByWholeSeparator("abstemiouslyaeiouyabstemiously", "aeiouy", 2) = ["abstemiously", "abstemiously"]
- Parameters:
str
- the String to parse, may be nullseparator
- String containing the String to be used as a delimiter,null
splits on whitespacemax
- the maximum number of elements to include in the returned array. A zero or negative value implies no limit.
- Returns:
- an array of parsed Strings,
null
if null String was input
public static String[] splitPreserveAllTokens(String str)
Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer. Whitespace is defined byCharacter.isWhitespace(char)
. The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class. Anull
input String returnsnull
.StringUtils.splitPreserveAllTokens(null) = null StringUtils.splitPreserveAllTokens("") = [] StringUtils.splitPreserveAllTokens("abc def") = ["abc", "def"] StringUtils.splitPreserveAllTokens("abc def") = ["abc", "", "def"] StringUtils.splitPreserveAllTokens(" abc ") = ["", "abc", ""]
- Parameters:
str
- the String to parse, may benull
- Returns:
- an array of parsed Strings,
null
if null String input
- Since:
- 2.1
public static String[] splitPreserveAllTokens(String str, String separatorChars)
Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer. The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class. Anull
input String returnsnull
. Anull
separatorChars splits on whitespace.StringUtils.splitPreserveAllTokens(null, *) = null StringUtils.splitPreserveAllTokens("", *) = [] StringUtils.splitPreserveAllTokens("abc def", null) = ["abc", "def"] StringUtils.splitPreserveAllTokens("abc def", " ") = ["abc", "def"] StringUtils.splitPreserveAllTokens("abc def", " ") = ["abc", "", def"] StringUtils.splitPreserveAllTokens("ab:cd:ef", ":") = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab:cd:ef:", ":") = ["ab", "cd", "ef", ""] StringUtils.splitPreserveAllTokens("ab:cd:ef::", ":") = ["ab", "cd", "ef", "", ""] StringUtils.splitPreserveAllTokens("ab::cd:ef", ":") = ["ab", "", cd", "ef"] StringUtils.splitPreserveAllTokens(":cd:ef", ":") = ["", cd", "ef"] StringUtils.splitPreserveAllTokens("::cd:ef", ":") = ["", "", cd", "ef"] StringUtils.splitPreserveAllTokens(":cd:ef:", ":") = ["", cd", "ef", ""]
- Parameters:
str
- the String to parse, may benull
separatorChars
- the characters used as the delimiters,null
splits on whitespace
- Returns:
- an array of parsed Strings,
null
if null String input
- Since:
- 2.1
public static String[] splitPreserveAllTokens(String str, String separatorChars, int max)
Splits the provided text into an array with a maximum length, separators specified, preserving all tokens, including empty tokens created by adjacent separators. The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. Adjacent separators are treated as one separator. Anull
input String returnsnull
. Anull
separatorChars splits on whitespace. If more thanmax
delimited substrings are found, the last returned string includes all characters after the firstmax - 1
returned strings (including separator characters).StringUtils.splitPreserveAllTokens(null, *, *) = null StringUtils.splitPreserveAllTokens("", *, *) = [] StringUtils.splitPreserveAllTokens("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 0) = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 2) = ["ab", "cd:ef"] StringUtils.splitPreserveAllTokens("ab de fg", null, 2) = ["ab", " de fg"] StringUtils.splitPreserveAllTokens("ab de fg", null, 3) = ["ab", "", " de fg"] StringUtils.splitPreserveAllTokens("ab de fg", null, 4) = ["ab", "", "", "de fg"]
- Parameters:
str
- the String to parse, may benull
separatorChars
- the characters used as the delimiters,null
splits on whitespacemax
- 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
- Since:
- 2.1
public static String[] splitPreserveAllTokens(String str, char separatorChar)
Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer. The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class. Anull
input String returnsnull
.StringUtils.splitPreserveAllTokens(null, *) = null StringUtils.splitPreserveAllTokens("", *) = [] StringUtils.splitPreserveAllTokens("a.b.c", '.') = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a..b.c", '.') = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a:b:c", '.') = ["a:b:c"] StringUtils.splitPreserveAllTokens("a\tb\nc", null) = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a b c", ' ') = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a b c ", ' ') = ["a", "b", "c", ""] StringUtils.splitPreserveAllTokens("a b c ", ' ') = ["a", "b", "c", "", ""] StringUtils.splitPreserveAllTokens(" a b c", ' ') = ["", a", "b", "c"] StringUtils.splitPreserveAllTokens(" a b c", ' ') = ["", "", a", "b", "c"] StringUtils.splitPreserveAllTokens(" a b c ", ' ') = ["", a", "b", "c", ""]
- Parameters:
str
- the String to parse, may benull
separatorChar
- the character used as the delimiter,null
splits on whitespace
- Returns:
- an array of parsed Strings,
null
if null String input
- Since:
- 2.1
public static String strip(String str)
Strips whitespace from the start and end of a String. This is similar totrim(String)
but removes whitespace. Whitespace is defined byCharacter.isWhitespace(char)
. Anull
input String returnsnull
.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
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 toString.trim()
but allows the characters to be stripped to be controlled. Anull
input String returnsnull
. An empty string ("") input returns the empty string. If the stripChars String isnull
, whitespace is stripped as defined byCharacter.isWhitespace(char)
. Alternatively usestrip(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 nullstripChars
- the characters to remove, null treated as whitespace
- Returns:
- the stripped String,
null
if null String input
public static String[] stripAll(String[] strs)
Strips whitespace from the start and end of every String in an array. Whitespace is defined byCharacter.isWhitespace(char)
. A new array is returned each time, except for length zero. Anull
array will returnnull
. An empty array will return itself. Anull
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
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 byCharacter.isWhitespace(char)
. A new array is returned each time, except for length zero. Anull
array will returnnull
. An empty array will return itself. Anull
array entry will be ignored. Anull
stripChars will strip whitespace as defined byCharacter.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 nullstripChars
- the characters to remove, null treated as whitespace
- Returns:
- the stripped Strings,
null
if null array input
public static String stripEnd(String str, String stripChars)
Strips any of a set of characters from the end of a String. Anull
input String returnsnull
. An empty string ("") input returns the empty string. If the stripChars String isnull
, whitespace is stripped as defined byCharacter.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 nullstripChars
- the characters to remove, null treated as whitespace
- Returns:
- the stripped String,
null
if null String input
public static String stripStart(String str, String stripChars)
Strips any of a set of characters from the start of a String. Anull
input String returnsnull
. An empty string ("") input returns the empty string. If the stripChars String isnull
, whitespace is stripped as defined byCharacter.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 nullstripChars
- the characters to remove, null treated as whitespace
- Returns:
- the stripped String,
null
if null String input
public static String stripToEmpty(String str)
Strips whitespace from the start and end of a String returning an empty String ifnull
input. This is similar totrimToEmpty(String)
but removes whitespace. Whitespace is defined byCharacter.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
public static String stripToNull(String str)
Strips whitespace from the start and end of a String returningnull
if the String is empty ("") after the strip. This is similar totrimToNull(String)
but removes whitespace. Whitespace is defined byCharacter.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
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 startn
characters from the end of the String. Anull
String will returnnull
. 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 nullstart
- 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
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/endn
characters from the end of the String. The returned substring starts with the character in thestart
position and ends before theend
position. All position counting is zero-based -- i.e., to start at the beginning of the string usestart = 0
. Negative start and end positions can be used to specify offsets relative to the end of the String. Ifstart
is not strictly to the left ofend
, "" 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 nullstart
- the position to start from, negative means count back from the end of the String by this many charactersend
- 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
public static String substringAfter(String str, String separator)
Gets the substring after the first occurrence of a separator. The separator is not returned. Anull
string input will returnnull
. An empty ("") string input will return the empty string. Anull
separator will return the empty string if the input string is notnull
.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 nullseparator
- the String to search for, may be null
- Returns:
- the substring after the first occurrence of the separator,
null
if null String input
- Since:
- 2.0
public static String substringAfterLast(String str, String separator)
Gets the substring after the last occurrence of a separator. The separator is not returned. Anull
string input will returnnull
. An empty ("") string input will return the empty string. An empty ornull
separator will return the empty string if the input string is notnull
.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 nullseparator
- the String to search for, may be null
- Returns:
- the substring after the last occurrence of the separator,
null
if null String input
- Since:
- 2.0
public static String substringBefore(String str, String separator)
Gets the substring before the first occurrence of a separator. The separator is not returned. Anull
string input will returnnull
. An empty ("") string input will return the empty string. Anull
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 nullseparator
- the String to search for, may be null
- Returns:
- the substring before the first occurrence of the separator,
null
if null String input
- Since:
- 2.0
public static String substringBeforeLast(String str, String separator)
Gets the substring before the last occurrence of a separator. The separator is not returned. Anull
string input will returnnull
. An empty ("") string input will return the empty string. An empty ornull
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 nullseparator
- the String to search for, may be null
- Returns:
- the substring before the last occurrence of the separator,
null
if null String input
- Since:
- 2.0
public static String substringBetween(String str, String tag)
Gets the String that is nested in between two instances of the same String. Anull
input String returnsnull
. Anull
tag returnsnull
.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 nulltag
- the String before and after the substring, may be null
- Returns:
- the substring,
null
if no match
- Since:
- 2.0
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. Anull
input String returnsnull
. Anull
open/close returnsnull
(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 nullopen
- the String before the substring, may be nullclose
- the String after the substring, may be null
- Returns:
- the substring,
null
if no match
- Since:
- 2.0
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.For a word based algorithm, see
- Upper case character converts to Lower case
- Title case character converts to Lower case
- Lower case character converts to Upper case
WordUtils.swapCase(String)
. Anull
input String returnsnull
.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 algorithm. 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
public static String trim(String str)
Removes control characters (char <= 32) from both ends of this String, handlingnull
by returningnull
. The String is trimmed usingString.trim()
. Trim removes start and end characters <= 32. To strip whitespace usestrip(String)
. To trim your choice of characters, use thestrip(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
public 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 isnull
. The String is trimmed usingString.trim()
. Trim removes start and end characters <= 32. To strip whitespace usestripToEmpty(String)
.StringUtils.trimToEmpty(null) = "" StringUtils.trimToEmpty("") = "" StringUtils.trimToEmpty(" ") = "" StringUtils.trimToEmpty("abc") = "abc" StringUtils.trimToEmpty(" abc ") = "abc"
- Parameters:
str
- the String to be trimmed, may be null
- Returns:
- the trimmed String, or an empty String if
null
input
- Since:
- 2.0
public static String trimToNull(String str)
Removes control characters (char <= 32) from both ends of this String returningnull
if the String is empty ("") after the trim or if it isnull
. The String is trimmed usingString.trim()
. Trim removes start and end characters <= 32. To strip whitespace usestripToNull(String)
.StringUtils.trimToNull(null) = null StringUtils.trimToNull("") = null StringUtils.trimToNull(" ") = null StringUtils.trimToNull("abc") = "abc" StringUtils.trimToNull(" abc ") = "abc"
- 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
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 perCharacter.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
public static String uncapitalize(String str)
Uncapitalizes a String changing the first letter to title case as perCharacter.toLowerCase(char)
. No other letters are changed. For a word based algorithm, seeWordUtils.uncapitalize(String)
. Anull
input String returnsnull
.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
public static String upperCase(String str)
Converts a String to upper case as perString.toUpperCase()
. Anull
input String returnsnull
.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