10726人阅读
工作（63）
java J2EE（39）
该系列工具类大部分出自 mons.lang3 或者其他开源框架中的工具包，StringUtils为lang工具包提供的字符串操作工具类，很多方法很合适平时开发使用，如果不想引用该jar包，可以直接把该类在自己项目中创建，源码如下：
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements.
See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the &License&); you may not use this file except in compliance with
* the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an &AS IS& BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
package mons.lang3;
import java.lang.reflect.InvocationTargetE
import java.lang.reflect.M
import java.util.ArrayL
import java.util.A
import java.util.I
import java.util.L
import java.util.L
import java.util.regex.P
* &p&Operations on {@link java.lang.String} that are
* {@code null} safe.&/p&
&li&&b&IsEmpty/IsBlank&/b&
- checks if a String contains text&/li&
&li&&b&Trim/Strip&/b&
- removes leading and trailing whitespace&/li&
&li&&b&Equals&/b&
- compares two strings null-safe&/li&
&li&&b&startsWith&/b&
- check if a String starts with a prefix null-safe&/li&
&li&&b&endsWith&/b&
- check if a String ends with a suffix null-safe&/li&
&li&&b&IndexOf/LastIndexOf/Contains&/b&
- null-safe index-of checks
&li&&b&IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut&/b&
- index-of any of a set of Strings&/li&
&li&&b&ContainsOnly/ContainsNone/ContainsAny&/b&
- does String contains only/none/any of these characters&/li&
&li&&b&Substring/Left/Right/Mid&/b&
- null-safe substring extractions&/li&
&li&&b&SubstringBefore/SubstringAfter/SubstringBetween&/b&
- substring extraction relative to other strings&/li&
&li&&b&Split/Join&/b&
- splits a String into an array of substrings and vice versa&/li&
&li&&b&Remove/Delete&/b&
- removes part of a String&/li&
&li&&b&Replace/Overlay&/b&
- Searches a String and replaces one String with another&/li&
&li&&b&Chomp/Chop&/b&
- removes the last part of a String&/li&
&li&&b&LeftPad/RightPad/Center/Repeat&/b&
- pads a String&/li&
&li&&b&UpperCase/LowerCase/SwapCase/Capitalize/Uncapitalize&/b&
- changes the case of a String&/li&
&li&&b&CountMatches&/b&
- counts the number of occurrences of one String in another&/li&
&li&&b&IsAlpha/IsNumeric/IsWhitespace/IsAsciiPrintable&/b&
- checks the characters in a String&/li&
&li&&b&DefaultString&/b&
- protects against a null input String&/li&
&li&&b&Reverse/ReverseDelimited&/b&
- reverses a String&/li&
&li&&b&Abbreviate&/b&
- abbreviates a string using ellipsis&/li&
&li&&b&Difference&/b&
- compares Strings and reports on their differences&/li&
&li&&b&LevenshteinDistance&/b&
- the number of changes needed to change one String into another&/li&
* &p&The {@code StringUtils} class defines certain words related to
* String handling.&/p&
&li&null - {@code null}&/li&
&li&empty - a zero-length string ({@code &&})&/li&
&li&space - the space character ({@code ' '}, char 32)&/li&
&li&whitespace - the characters defined by {@link Character#isWhitespace(char)}&/li&
&li&trim - the characters &= 32 as in {@link String#trim()}&/li&
* &p&{@code StringUtils} handles {@code null} input Strings quietly.
* That is to say that a {@code null} input will return {@code null}.
* Where a {@code boolean} or {@code int} is being returned
* details vary by method.&/p&
* &p&A side effect of the {@code null} handling is that a
* {@code NullPointerException} should be considered a bug in
* {@code StringUtils}.&/p&
* &p&Methods in this class give sample code to explain their operation.
* The symbol {@code *} is used to indicate any input including {@code null}.&/p&
* &p&#ThreadSafe#&/p&
* @see java.lang.String
* @since 1.0
* @version $Id: StringUtils.java 1-09-08 16:37:26Z sebb $
//@Immutable
public class StringUtils {
* The empty String {@code &&}.
* @since 2.0
public static final String EMPTY = &&;
* Represents a failed index search.
* @since 2.1
public static final int INDEX_NOT_FOUND = -1;
* &p&The maximum size to which the padding constant(s) can expand.&/p&
private static final int PAD_LIMIT = 8192;
* A regex pattern for recognizing blocks of whitespace characters.
private static final Pattern WHITESPACE_BLOCK = pile(&\\s+&);
* &p&{@code StringUtils} instances should NOT be constructed in
* standard programming. Instead, the class should be used as
* {@code StringUtils.trim(& foo &);}.&/p&
* &p&This constructor is public to permit tools that require a JavaBean
* instance to operate.&/p&
public StringUtils() {
// Empty checks
//-----------------------------------------------------------------------
* &p&Checks if a CharSequence is empty (&&) or null.&/p&
* StringUtils.isEmpty(null)
* StringUtils.isEmpty(&&)
* StringUtils.isEmpty(& &)
* StringUtils.isEmpty(&bob&)
* StringUtils.isEmpty(&
&) = false
* &p&NOTE: This method changed in Lang version 2.0.
* It no longer trims the CharSequence.
* That functionality is available in isBlank().&/p&
* @param cs
the CharSequence to check, may be null
* @return {@code true} if the CharSequence is empty or null
* @since 3.0 Changed signature from isEmpty(String) to isEmpty(CharSequence)
public static boolean isEmpty(CharSequence cs) {
return cs == null || cs.length() == 0;
* &p&Checks if a CharSequence is not empty (&&) and not null.&/p&
* StringUtils.isNotEmpty(null)
* StringUtils.isNotEmpty(&&)
* StringUtils.isNotEmpty(& &)
* StringUtils.isNotEmpty(&bob&)
* StringUtils.isNotEmpty(&
* @param cs
the CharSequence to check, may be null
* @return {@code true} if the CharSequence is not empty and not null
* @since 3.0 Changed signature from isNotEmpty(String) to isNotEmpty(CharSequence)
public static boolean isNotEmpty(CharSequence cs) {
return !StringUtils.isEmpty(cs);
* &p&Checks if a CharSequence is whitespace, empty (&&) or null.&/p&
* StringUtils.isBlank(null)
* StringUtils.isBlank(&&)
* StringUtils.isBlank(& &)
* StringUtils.isBlank(&bob&)
* StringUtils.isBlank(&
&) = false
* @param cs
the CharSequence to check, may be null
* @return {@code true} if the CharSequence is null, empty or whitespace
* @since 2.0
* @since 3.0 Changed signature from isBlank(String) to isBlank(CharSequence)
public static boolean isBlank(CharSequence cs) {
if (cs == null || (strLen = cs.length()) == 0) {
for (int i = 0; i & strL i++) {
if ((Character.isWhitespace(cs.charAt(i)) == false)) {
* &p&Checks if a CharSequence is not empty (&&), not null and not whitespace only.&/p&
* StringUtils.isNotBlank(null)
* StringUtils.isNotBlank(&&)
* StringUtils.isNotBlank(& &)
* StringUtils.isNotBlank(&bob&)
* StringUtils.isNotBlank(&
* @param cs
the CharSequence to check, may be null
* @return {@code true} if the CharSequence is
not empty and not null and not whitespace
* @since 2.0
* @since 3.0 Changed signature from isNotBlank(String) to isNotBlank(CharSequence)
public static boolean isNotBlank(CharSequence cs) {
return !StringUtils.isBlank(cs);
//-----------------------------------------------------------------------
* &p&Removes control characters (char &= 32) from both
* ends of this String, handling {@code null} by returning
* {@code null}.&/p&
* &p&The String is trimmed using {@link String#trim()}.
* Trim removes start and end characters &= 32.
* To strip whitespace use {@link #strip(String)}.&/p&
* &p&To trim your choice of characters, use the
* {@link #strip(String, String)} methods.&/p&
* StringUtils.trim(null)
* StringUtils.trim(&&)
* StringUtils.trim(&
* StringUtils.trim(&abc&)
* StringUtils.trim(&
&) = &abc&
* @param str
the String to be trimmed, may be null
* @return the trimmed string, {@code null} if null String input
public static String trim(String str) {
return str == null ? null : str.trim();
* &p&Removes control characters (char &= 32) from both
* ends of this String returning {@code null} if the String is
* empty (&&) after the trim or if it is {@code null}.
* &p&The String is trimmed using {@link String#trim()}.
* Trim removes start and end characters &= 32.
* To strip whitespace use {@link #stripToNull(String)}.&/p&
* StringUtils.trimToNull(null)
* StringUtils.trimToNull(&&)
* StringUtils.trimToNull(&
* StringUtils.trimToNull(&abc&)
* StringUtils.trimToNull(&
&) = &abc&
* @param str
the String to be trimmed, may be null
* @return the trimmed String,
{@code null} if only chars &= 32, empty or null String input
* @since 2.0
public static String trimToNull(String str) {
String ts = trim(str);
return isEmpty(ts) ? null :
* &p&Removes control characters (char &= 32) from both
* ends of this String returning an empty String (&&) if the String
* is empty (&&) after the trim or if it is {@code null}.
* &p&The String is trimmed using {@link String#trim()}.
* Trim removes start and end characters &= 32.
* To strip whitespace use {@link #stripToEmpty(String)}.&/p&
* StringUtils.trimToEmpty(null)
* StringUtils.trimToEmpty(&&)
* StringUtils.trimToEmpty(&
* StringUtils.trimToEmpty(&abc&)
* StringUtils.trimToEmpty(&
&) = &abc&
* @param str
the String to be trimmed, may be null
* @return the trimmed String, or an empty String if {@code null} input
* @since 2.0
public static String trimToEmpty(String str) {
return str == null ? EMPTY : str.trim();
// Stripping
//-----------------------------------------------------------------------
* &p&Strips whitespace from the start and end of a String.&/p&
* &p&This is similar to {@link #trim(String)} but removes whitespace.
* Whitespace is defined by {@link Character#isWhitespace(char)}.&/p&
* &p&A {@code null} input String returns {@code null}.&/p&
* StringUtils.strip(null)
* StringUtils.strip(&&)
* StringUtils.strip(&
* StringUtils.strip(&abc&)
* StringUtils.strip(&
* StringUtils.strip(&abc
* StringUtils.strip(& abc &)
* StringUtils.strip(& ab c &) = &ab c&
* @param str
the String to remove whitespace from, may be null
* @return the stripped String, {@code null} if null String input
public static String strip(String str) {
return strip(str, null);
* &p&Strips whitespace from the start and end of a String
* {@code null} if the String is empty (&&) after the strip.&/p&
* &p&This is similar to {@link #trimToNull(String)} but removes whitespace.
* Whitespace is defined by {@link Character#isWhitespace(char)}.&/p&
* StringUtils.stripToNull(null)
* StringUtils.stripToNull(&&)
* StringUtils.stripToNull(&
* StringUtils.stripToNull(&abc&)
* StringUtils.stripToNull(&
* StringUtils.stripToNull(&abc
* StringUtils.stripToNull(& abc &)
* StringUtils.stripToNull(& ab c &) = &ab c&
* @param str
the String to be stripped, may be null
* @return the stripped String,
{@code null} if whitespace, empty or null String input
* @since 2.0
public static String stripToNull(String str) {
if (str == null) {
str = strip(str, null);
return str.length() == 0 ? null :
* &p&Strips whitespace from the start and end of a String
* an empty String if {@code null} input.&/p&
* &p&This is similar to {@link #trimToEmpty(String)} but removes whitespace.
* Whitespace is defined by {@link Character#isWhitespace(char)}.&/p&
* StringUtils.stripToEmpty(null)
* StringUtils.stripToEmpty(&&)
* StringUtils.stripToEmpty(&
* StringUtils.stripToEmpty(&abc&)
* StringUtils.stripToEmpty(&
* StringUtils.stripToEmpty(&abc
* StringUtils.stripToEmpty(& abc &)
* StringUtils.stripToEmpty(& ab c &) = &ab c&
* @param str
the String to be stripped, may be null
* @return the trimmed String, or an empty String if {@code null} input
* @since 2.0
public static String stripToEmpty(String str) {
return str == null ? EMPTY : strip(str, null);
* &p&Strips any of a set of characters from the start and end of a String.
* This is similar to {@link String#trim()} but allows the characters
* to be stripped to be controlled.&/p&
* &p&A {@code null} input String returns {@code null}.
* An empty string (&&) input returns the empty string.&/p&
* &p&If the stripChars String is {@code null}, whitespace is
* stripped as defined by {@link Character#isWhitespace(char)}.
* Alternatively use {@link #strip(String)}.&/p&
* StringUtils.strip(null, *)
* StringUtils.strip(&&, *)
* StringUtils.strip(&abc&, null)
* StringUtils.strip(&
abc&, null)
* StringUtils.strip(&abc
* StringUtils.strip(& abc &, null)
* StringUtils.strip(&
abcyx&, &xyz&) = &
* @param str
the String to remove characters from, may be null
* @param stripChars
the characters to remove, null treated as whitespace
* @return the stripped String, {@code null} if null String input
public static String strip(String str, String stripChars) {
if (isEmpty(str)) {
str = stripStart(str, stripChars);
return stripEnd(str, stripChars);
* &p&Strips any of a set of characters from the start of a String.&/p&
* &p&A {@code null} input String returns {@code null}.
* An empty string (&&) input returns the empty string.&/p&
* &p&If the stripChars String is {@code null}, whitespace is
* stripped as defined by {@link Character#isWhitespace(char)}.&/p&
* StringUtils.stripStart(null, *)
* StringUtils.stripStart(&&, *)
* StringUtils.stripStart(&abc&, &&)
* StringUtils.stripStart(&abc&, null)
* StringUtils.stripStart(&
abc&, null)
* StringUtils.stripStart(&abc
* StringUtils.stripStart(& abc &, null)
* StringUtils.stripStart(&yxabc
&, &xyz&) = &abc
* @param str
the String to remove characters from, may be null
* @param stripChars
the characters to remove, null treated as whitespace
* @return the stripped String, {@code null} if null String input
public static String stripStart(String str, String stripChars) {
if (str == null || (strLen = str.length()) == 0) {
int start = 0;
if (stripChars == null) {
while ((start != strLen) && Character.isWhitespace(str.charAt(start))) {
} else if (stripChars.length() == 0) {
while ((start != strLen) && (stripChars.indexOf(str.charAt(start)) != INDEX_NOT_FOUND)) {
return str.substring(start);
* &p&Strips any of a set of characters from the end of a String.&/p&
* &p&A {@code null} input String returns {@code null}.
* An empty string (&&) input returns the empty string.&/p&
* &p&If the stripChars String is {@code null}, whitespace is
* stripped as defined by {@link Character#isWhitespace(char)}.&/p&
* StringUtils.stripEnd(null, *)
* StringUtils.stripEnd(&&, *)
* StringUtils.stripEnd(&abc&, &&)
* StringUtils.stripEnd(&abc&, null)
* StringUtils.stripEnd(&
abc&, null)
* StringUtils.stripEnd(&abc
* StringUtils.stripEnd(& abc &, null)
* StringUtils.stripEnd(&
abcyx&, &xyz&) = &
* StringUtils.stripEnd(&120.00&, &.0&)
* @param str
the String to remove characters from, may be null
* @param stripChars
the set of characters to remove, null treated as whitespace
* @return the stripped String, {@code null} if null String input
public static String stripEnd(String str, String stripChars) {
if (str == null || (end = str.length()) == 0) {
if (stripChars == null) {
while ((end != 0) && Character.isWhitespace(str.charAt(end - 1))) {
} else if (stripChars.length() == 0) {
while ((end != 0) && (stripChars.indexOf(str.charAt(end - 1)) != INDEX_NOT_FOUND)) {
return str.substring(0, end);
// StripAll
//-----------------------------------------------------------------------
* &p&Strips whitespace from the start and end of every String in an array.
* Whitespace is defined by {@link Character#isWhitespace(char)}.&/p&
* &p&A new array is returned each time, except for length zero.
* A {@code null} array will return {@code null}.
* An empty array will return itself.
* A {@code null} array entry will be ignored.&/p&
* StringUtils.stripAll(null)
* StringUtils.stripAll([])
* StringUtils.stripAll([&abc&, &
abc&]) = [&abc&, &abc&]
* StringUtils.stripAll([&abc
= [&abc&, null]
* @param strs
the array to remove whitespace from, may be null
* @return the stripped Strings, {@code null} if null array input
public static String[] stripAll(String... strs) {
return stripAll(strs, null);
* &p&Strips any of a set of characters from the start and end of every
* String in an array.&/p&
* Whitespace is defined by {@link Character#isWhitespace(char)}.&/p&
* &p&A new array is returned each time, except for length zero.
* A {@code null} array will return {@code null}.
* An empty array will return itself.
* A {@code null} array entry will be ignored.
* A {@code null} stripChars will strip whitespace as defined by
* {@link Character#isWhitespace(char)}.&/p&
* StringUtils.stripAll(null, *)
* StringUtils.stripAll([], *)
* StringUtils.stripAll([&abc&, &
abc&], null) = [&abc&, &abc&]
* StringUtils.stripAll([&abc
&, null], null)
= [&abc&, null]
* StringUtils.stripAll([&abc
&, null], &yz&)
* StringUtils.stripAll([&yabcz&, null], &yz&)
= [&abc&, null]
* @param strs
the array to remove characters from, may be null
* @param stripChars
the characters to remove, null treated as whitespace
* @return the stripped Strings, {@code null} if null array input
public static String[] stripAll(String[] strs, String stripChars) {
if (strs == null || (strsLen = strs.length) == 0) {
String[] newArr = new String[strsLen];
for (int i = 0; i & strsL i++) {
newArr[i] = strip(strs[i], stripChars);
return newA
* &p&Removes diacritics (~= accents) from a string. The case will not be altered.&/p&
* &p&For instance, 'à' will be replaced by 'a'.&/p&
* &p&Note that ligatures will be left as is.&/p&
* &p&This method will use the first available implementation of:
* Java 6's {@link java.text.Normalizer}, Java 1.3–1.5's {@code sun.text.Normalizer}&/p&
* StringUtils.stripAccents(null)
* StringUtils.stripAccents(&&)
* StringUtils.stripAccents(&control&)
= &control&
* StringUtils.stripAccents(&éclair&)
= &eclair&
* @param input String to be stripped
* @return input text with diacritics removed
* @since 3.0
// See also Lucene's ASCIIFoldingFilter (Lucene 2.9) that replaces accented characters by their unaccented equivalent (and uncommitted bug fix: https://issues.apache.org/jira/browse/LUCENE-1343?focusedCommentId=&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_).
public static String stripAccents(String input) {
if(input == null) {
String result =
if (java6NormalizeMethod != null) {
result = removeAccentsJava6(input);
} else if (sunDecomposeMethod != null) {
result = removeAccentsSUN(input);
throw new UnsupportedOperationException(
&The stripAccents(CharSequence) method requires at least&
+& Java6, but got: &+java6Exception
+&; or a Sun JVM: &+sunException);
// Note that none of the above methods correctly remove ligatures...
} catch(IllegalArgumentException iae) {
throw new RuntimeException(&IllegalArgumentException occurred&, iae);
} catch(IllegalAccessException iae) {
throw new RuntimeException(&IllegalAccessException occurred&, iae);
} catch(InvocationTargetException ite) {
throw new RuntimeException(&InvocationTargetException occurred&, ite);
} catch(SecurityException se) {
throw new RuntimeException(&SecurityException occurred&, se);
* Use {@code java.text.Normalizer#normalize(CharSequence, Normalizer.Form)}
* (but be careful, this class exists in Java 1.3, with an entirely different meaning!)
* @param text the text to be processed
* @return the processed string
* @throws IllegalAccessException may be thrown by a reflection call
* @throws InvocationTargetException if a reflection call throws an exception
* @throws IllegalStateException if the {@code Normalizer} class is not available
private static String removeAccentsJava6(CharSequence text)
throws IllegalAccessException, InvocationTargetException {
String decomposed = java.text.Normalizer.normalize(CharSequence, Normalizer.Form.NFD);
return java6Pattern.matcher(decomposed).replaceAll(&&);//$NON-NLS-1$
if (java6NormalizeMethod == null || java6NormalizerFormNFD == null) {
throw new IllegalStateException(&java.text.Normalizer is not available&, java6Exception);
result = (String) java6NormalizeMethod.invoke(null, new Object[] {text, java6NormalizerFormNFD});
result = java6Pattern.matcher(result).replaceAll(&&);//$NON-NLS-1$
* Use {@code sun.text.Normalizer#decompose(String, boolean, int)}
* @param text the text to be processed
* @return the processed string
* @throws IllegalAccessException may be thrown by a reflection call
* @throws InvocationTargetException if a reflection call throws an exception
* @throws IllegalStateException if the {@code Normalizer} class is not available
private static String removeAccentsSUN(CharSequence text)
throws IllegalAccessException, InvocationTargetException {
String decomposed = sun.text.Normalizer.decompose(text, false, 0);
return sunPattern.matcher(decomposed).replaceAll(&&);//$NON-NLS-1$
if (sunDecomposeMethod == null) {
throw new IllegalStateException(&sun.text.Normalizer is not available&, sunException);
result = (String) sunDecomposeMethod.invoke(null, new Object[] {text, Boolean.FALSE, Integer.valueOf(0)});
result = sunPattern.matcher(result).replaceAll(&&);//$NON-NLS-1$
// SUN internal, Java 1.3 -& Java 5
private static final Throwable sunE
private static final Method
sunDecomposeM
private static final Pattern sunPattern = pile(&\\p{InCombiningDiacriticalMarks}+&);//$NON-NLS-1$
// Java 6+
private static final Throwable java6E
private static final Method
java6NormalizeM
private static final Object
java6NormalizerFormNFD;
private static final Pattern java6Pattern = sunP
// Set up defaults for final static fields
Object _java6NormalizerFormNFD =
Method _java6NormalizeMethod =
Method _sunDecomposeMethod =
Throwable _java6Exception =
Throwable _sunException =
// java.text.Normalizer.normalize(CharSequence, Normalizer.Form.NFD);
// Be careful not to get Java 1.3 java.text.Normalizer!
Class&?& normalizerFormClass = Thread.currentThread().getContextClassLoader()
.loadClass(&java.text.Normalizer$Form&);//$NON-NLS-1$
_java6NormalizerFormNFD = normalizerFormClass.getField(&NFD&).get(null);//$NON-NLS-1$
Class&?& normalizerClass = Thread.currentThread().getContextClassLoader()
.loadClass(&java.text.Normalizer&);//$NON-NLS-1$
_java6NormalizeMethod = normalizerClass.getMethod(&normalize&,//$NON-NLS-1$
new Class[] {CharSequence.class, normalizerFormClass});//$NON-NLS-1$
} catch (Exception e1) {
// Only check for Sun method if Java 6 method is not available
_java6Exception = e1;
// sun.text.Normalizer.decompose(text, false, 0);
Class&?& normalizerClass = Thread.currentThread().getContextClassLoader()
.loadClass(&sun.text.Normalizer&);//$NON-NLS-1$
_sunDecomposeMethod = normalizerClass.getMethod(&decompose&,//$NON-NLS-1$
new Class[] {String.class, Boolean.TYPE, Integer.TYPE});//$NON-NLS-1$
} catch (Exception e2) {
_sunException = e2;
// Set up final static fields
java6Exception = _java6E
java6NormalizerFormNFD = _java6NormalizerFormNFD;
java6NormalizeMethod = _java6NormalizeM
sunException = _sunE
sunDecomposeMethod = _sunDecomposeM
//-----------------------------------------------------------------------
* &p&Compares two CharSequences, returning {@code true} if they are equal.&/p&
* &p&{@code null}s are handled without exceptions. Two {@code null}
* references are considered to be equal. The comparison is case sensitive.&/p&
* StringUtils.equals(null, null)
* StringUtils.equals(null, &abc&)
* StringUtils.equals(&abc&, null)
* StringUtils.equals(&abc&, &abc&) = true
* StringUtils.equals(&abc&, &ABC&) = false
* @see java.lang.String#equals(Object)
* @param cs1
the first CharSequence, may be null
* @param cs2
the second CharSequence, may be null
* @return {@code true} if the CharSequences are equal, case sensitive, or
both {@code null}
* @since 3.0 Changed signature from equals(String, String) to equals(CharSequence, CharSequence)
public static boolean equals(CharSequence cs1, CharSequence cs2) {
return cs1 == null ? cs2 == null : cs1.equals(cs2);
* &p&Compares two CharSequences, returning {@code true} if they are equal ignoring
* the case.&/p&
* &p&{@code null}s are handled without exceptions. Two {@code null}
* references are considered equal. Comparison is case insensitive.&/p&
* StringUtils.equalsIgnoreCase(null, null)
* StringUtils.equalsIgnoreCase(null, &abc&)
* StringUtils.equalsIgnoreCase(&abc&, null)
* StringUtils.equalsIgnoreCase(&abc&, &abc&) = true
* StringUtils.equalsIgnoreCase(&abc&, &ABC&) = true
* @param str1
the first CharSequence, may be null
* @param str2
the second CharSequence, may be null
* @return {@code true} if the CharSequence are equal, case insensitive, or
both {@code null}
* @since 3.0 Changed signature from equalsIgnoreCase(String, String) to equalsIgnoreCase(CharSequence, CharSequence)
public static boolean equalsIgnoreCase(CharSequence str1, CharSequence str2) {
if (str1 == null || str2 == null) {
return str1 == str2;
return CharSequenceUtils.regionMatches(str1, true, 0, str2, 0, Math.max(str1.length(), str2.length()));
// IndexOf
//-----------------------------------------------------------------------
* &p&Finds the first index within a CharSequence, handling {@code null}.
* This method uses {@link String#indexOf(int, int)} if possible.&/p&
* &p&A {@code null} or empty (&&) CharSequence will return {@code INDEX_NOT_FOUND (-1)}.&/p&
* StringUtils.indexOf(null, *)
* StringUtils.indexOf(&&, *)
* StringUtils.indexOf(&aabaabaa&, 'a') = 0
* StringUtils.indexOf(&aabaabaa&, 'b') = 2
* @param seq
the CharSequence to check, may be null
* @param searchChar
the character to find
* @return the first index of the search character,
-1 if no match or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from indexOf(String, int) to indexOf(CharSequence, int)
public static int indexOf(CharSequence seq, int searchChar) {
if (isEmpty(seq)) {
return INDEX_NOT_FOUND;
return CharSequenceUtils.indexOf(seq, searchChar, 0);
* &p&Finds the first index within a CharSequence from a start position,
* handling {@code null}.
* This method uses {@link String#indexOf(int, int)} if possible.&/p&
* &p&A {@code null} or empty (&&) CharSequence will return {@code (INDEX_NOT_FOUND) -1}.
* A negative start position is treated as zero.
* A start position greater than the string length returns {@code -1}.&/p&
* StringUtils.indexOf(null, *, *)
* StringUtils.indexOf(&&, *, *)
* StringUtils.indexOf(&aabaabaa&, 'b', 0)
* StringUtils.indexOf(&aabaabaa&, 'b', 3)
* StringUtils.indexOf(&aabaabaa&, 'b', 9)
* StringUtils.indexOf(&aabaabaa&, 'b', -1) = 2
* @param seq
the CharSequence to check, may be null
* @param searchChar
the character to find
* @param startPos
the start position, negative treated as zero
* @return the first index of the search character,
-1 if no match or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from indexOf(String, int, int) to indexOf(CharSequence, int, int)
public static int indexOf(CharSequence seq, int searchChar, int startPos) {
if (isEmpty(seq)) {
return INDEX_NOT_FOUND;
return CharSequenceUtils.indexOf(seq, searchChar, startPos);
* &p&Finds the first index within a CharSequence, handling {@code null}.
* This method uses {@link String#indexOf(String, int)} if possible.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.&/p&
* StringUtils.indexOf(null, *)
* StringUtils.indexOf(*, null)
* StringUtils.indexOf(&&, &&)
* StringUtils.indexOf(&&, *)
= -1 (except when * = &&)
* StringUtils.indexOf(&aabaabaa&, &a&)
* StringUtils.indexOf(&aabaabaa&, &b&)
* StringUtils.indexOf(&aabaabaa&, &ab&) = 1
* StringUtils.indexOf(&aabaabaa&, &&)
* @param seq
the CharSequence to check, may be null
* @param searchSeq
the CharSequence to find, may be null
* @return the first index of the search CharSequence,
-1 if no match or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from indexOf(String, String) to indexOf(CharSequence, CharSequence)
public static int indexOf(CharSequence seq, CharSequence searchSeq) {
if (seq == null || searchSeq == null) {
return INDEX_NOT_FOUND;
return CharSequenceUtils.indexOf(seq, searchSeq, 0);
* &p&Finds the first index within a CharSequence, handling {@code null}.
* This method uses {@link String#indexOf(String, int)} if possible.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A negative start position is treated as zero.
* An empty (&&) search CharSequence always matches.
* A start position greater than the string length only matches
* an empty search CharSequence.&/p&
* StringUtils.indexOf(null, *, *)
* StringUtils.indexOf(*, null, *)
* StringUtils.indexOf(&&, &&, 0)
* StringUtils.indexOf(&&, *, 0)
= -1 (except when * = &&)
* StringUtils.indexOf(&aabaabaa&, &a&, 0)
* StringUtils.indexOf(&aabaabaa&, &b&, 0)
* StringUtils.indexOf(&aabaabaa&, &ab&, 0) = 1
* StringUtils.indexOf(&aabaabaa&, &b&, 3)
* StringUtils.indexOf(&aabaabaa&, &b&, 9)
* StringUtils.indexOf(&aabaabaa&, &b&, -1) = 2
* StringUtils.indexOf(&aabaabaa&, &&, 2)
* StringUtils.indexOf(&abc&, &&, 9)
* @param seq
the CharSequence to check, may be null
* @param searchSeq
the CharSequence to find, may be null
* @param startPos
the start position, negative treated as zero
* @return the first index of the search CharSequence,
-1 if no match or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from indexOf(String, String, int) to indexOf(CharSequence, CharSequence, int)
public static int indexOf(CharSequence seq, CharSequence searchSeq, int startPos) {
if (seq == null || searchSeq == null) {
return INDEX_NOT_FOUND;
return CharSequenceUtils.indexOf(seq, searchSeq, startPos);
* &p&Finds the n-th index within a CharSequence, handling {@code null}.
* This method uses {@link String#indexOf(String)} if possible.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.&/p&
* StringUtils.ordinalIndexOf(null, *, *)
* StringUtils.ordinalIndexOf(*, null, *)
* StringUtils.ordinalIndexOf(&&, &&, *)
* StringUtils.ordinalIndexOf(&aabaabaa&, &a&, 1)
* StringUtils.ordinalIndexOf(&aabaabaa&, &a&, 2)
* StringUtils.ordinalIndexOf(&aabaabaa&, &b&, 1)
* StringUtils.ordinalIndexOf(&aabaabaa&, &b&, 2)
* StringUtils.ordinalIndexOf(&aabaabaa&, &ab&, 1) = 1
* StringUtils.ordinalIndexOf(&aabaabaa&, &ab&, 2) = 4
* StringUtils.ordinalIndexOf(&aabaabaa&, &&, 1)
* StringUtils.ordinalIndexOf(&aabaabaa&, &&, 2)
* &p&Note that 'head(CharSequence str, int n)' may be implemented as: &/p&
str.substring(0, lastOrdinalIndexOf(str, &\n&, n))
* @param str
the CharSequence to check, may be null
* @param searchStr
the CharSequence to find, may be null
* @param ordinal
the n-th {@code searchStr} to find
* @return the n-th index of the search CharSequence,
{@code -1} ({@code INDEX_NOT_FOUND}) if no match or {@code null} string input
* @since 2.1
* @since 3.0 Changed signature from ordinalIndexOf(String, String, int) to ordinalIndexOf(CharSequence, CharSequence, int)
public static int ordinalIndexOf(CharSequence str, CharSequence searchStr, int ordinal) {
return ordinalIndexOf(str, searchStr, ordinal, false);
* &p&Finds the n-th index within a String, handling {@code null}.
* This method uses {@link String#indexOf(String)} if possible.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.&/p&
* @param str
the CharSequence to check, may be null
* @param searchStr
the CharSequence to find, may be null
* @param ordinal
the n-th {@code searchStr} to find
* @param lastIndex true if lastOrdinalIndexOf() otherwise false if ordinalIndexOf()
* @return the n-th index of the search CharSequence,
{@code -1} ({@code INDEX_NOT_FOUND}) if no match or {@code null} string input
// Shared code between ordinalIndexOf(String,String,int) and lastOrdinalIndexOf(String,String,int)
private static int ordinalIndexOf(CharSequence str, CharSequence searchStr, int ordinal, boolean lastIndex) {
if (str == null || searchStr == null || ordinal &= 0) {
return INDEX_NOT_FOUND;
if (searchStr.length() == 0) {
return lastIndex ? str.length() : 0;
int found = 0;
int index = lastIndex ? str.length() : INDEX_NOT_FOUND;
if (lastIndex) {
index = CharSequenceUtils.lastIndexOf(str, searchStr, index - 1);
index = CharSequenceUtils.indexOf(str, searchStr, index + 1);
if (index & 0) {
} while (found & ordinal);
* &p&Case in-sensitive find of the first index within a CharSequence.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A negative start position is treated as zero.
* An empty (&&) search CharSequence always matches.
* A start position greater than the string length only matches
* an empty search CharSequence.&/p&
* StringUtils.indexOfIgnoreCase(null, *)
* StringUtils.indexOfIgnoreCase(*, null)
* StringUtils.indexOfIgnoreCase(&&, &&)
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &a&)
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &b&)
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &ab&) = 1
* @param str
the CharSequence to check, may be null
* @param searchStr
the CharSequence to find, may be null
* @return the first index of the search CharSequence,
-1 if no match or {@code null} string input
* @since 2.5
* @since 3.0 Changed signature from indexOfIgnoreCase(String, String) to indexOfIgnoreCase(CharSequence, CharSequence)
public static int indexOfIgnoreCase(CharSequence str, CharSequence searchStr) {
return indexOfIgnoreCase(str, searchStr, 0);
* &p&Case in-sensitive find of the first index within a CharSequence
* from the specified position.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A negative start position is treated as zero.
* An empty (&&) search CharSequence always matches.
* A start position greater than the string length only matches
* an empty search CharSequence.&/p&
* StringUtils.indexOfIgnoreCase(null, *, *)
* StringUtils.indexOfIgnoreCase(*, null, *)
* StringUtils.indexOfIgnoreCase(&&, &&, 0)
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &A&, 0)
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &B&, 0)
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &AB&, 0) = 1
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &B&, 3)
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &B&, 9)
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &B&, -1) = 2
* StringUtils.indexOfIgnoreCase(&aabaabaa&, &&, 2)
* StringUtils.indexOfIgnoreCase(&abc&, &&, 9)
* @param str
the CharSequence to check, may be null
* @param searchStr
the CharSequence to find, may be null
* @param startPos
the start position, negative treated as zero
* @return the first index of the search CharSequence,
-1 if no match or {@code null} string input
* @since 2.5
* @since 3.0 Changed signature from indexOfIgnoreCase(String, String, int) to indexOfIgnoreCase(CharSequence, CharSequence, int)
public static int indexOfIgnoreCase(CharSequence str, CharSequence searchStr, int startPos) {
if (str == null || searchStr == null) {
return INDEX_NOT_FOUND;
if (startPos & 0) {
startPos = 0;
int endLimit = (str.length() - searchStr.length()) + 1;
if (startPos & endLimit) {
return INDEX_NOT_FOUND;
if (searchStr.length() == 0) {
return startP
for (int i = startP i & endL i++) {
if (CharSequenceUtils.regionMatches(str, true, i, searchStr, 0, searchStr.length())) {
return INDEX_NOT_FOUND;
// LastIndexOf
//-----------------------------------------------------------------------
* &p&Finds the last index within a CharSequence, handling {@code null}.
* This method uses {@link String#lastIndexOf(int)} if possible.&/p&
* &p&A {@code null} or empty (&&) CharSequence will return {@code -1}.&/p&
* StringUtils.lastIndexOf(null, *)
* StringUtils.lastIndexOf(&&, *)
* StringUtils.lastIndexOf(&aabaabaa&, 'a') = 7
* StringUtils.lastIndexOf(&aabaabaa&, 'b') = 5
* @param seq
the CharSequence to check, may be null
* @param searchChar
the character to find
* @return the last index of the search character,
-1 if no match or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from lastIndexOf(String, int) to lastIndexOf(CharSequence, int)
public static int lastIndexOf(CharSequence seq, int searchChar) {
if (isEmpty(seq)) {
return INDEX_NOT_FOUND;
return CharSequenceUtils.lastIndexOf(seq, searchChar, seq.length());
* &p&Finds the last index within a CharSequence from a start position,
* handling {@code null}.
* This method uses {@link String#lastIndexOf(int, int)} if possible.&/p&
* &p&A {@code null} or empty (&&) CharSequence will return {@code -1}.
* A negative start position returns {@code -1}.
* A start position greater than the string length searches the whole string.&/p&
* StringUtils.lastIndexOf(null, *, *)
* StringUtils.lastIndexOf(&&, *,
* StringUtils.lastIndexOf(&aabaabaa&, 'b', 8)
* StringUtils.lastIndexOf(&aabaabaa&, 'b', 4)
* StringUtils.lastIndexOf(&aabaabaa&, 'b', 0)
* StringUtils.lastIndexOf(&aabaabaa&, 'b', 9)
* StringUtils.lastIndexOf(&aabaabaa&, 'b', -1) = -1
* StringUtils.lastIndexOf(&aabaabaa&, 'a', 0)
* @param seq
the CharSequence to check, may be null
* @param searchChar
the character to find
* @param startPos
the start position
* @return the last index of the search character,
-1 if no match or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from lastIndexOf(String, int, int) to lastIndexOf(CharSequence, int, int)
public static int lastIndexOf(CharSequence seq, int searchChar, int startPos) {
if (isEmpty(seq)) {
return INDEX_NOT_FOUND;
return CharSequenceUtils.lastIndexOf(seq, searchChar, startPos);
* &p&Finds the last index within a CharSequence, handling {@code null}.
* This method uses {@link String#lastIndexOf(String)} if possible.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.&/p&
* StringUtils.lastIndexOf(null, *)
* StringUtils.lastIndexOf(*, null)
* StringUtils.lastIndexOf(&&, &&)
* StringUtils.lastIndexOf(&aabaabaa&, &a&)
* StringUtils.lastIndexOf(&aabaabaa&, &b&)
* StringUtils.lastIndexOf(&aabaabaa&, &ab&) = 4
* StringUtils.lastIndexOf(&aabaabaa&, &&)
* @param seq
the CharSequence to check, may be null
* @param searchSeq
the CharSequence to find, may be null
* @return the last index of the search String,
-1 if no match or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from lastIndexOf(String, String) to lastIndexOf(CharSequence, CharSequence)
public static int lastIndexOf(CharSequence seq, CharSequence searchSeq) {
if (seq == null || searchSeq == null) {
return INDEX_NOT_FOUND;
return CharSequenceUtils.lastIndexOf(seq, searchSeq, seq.length());
* &p&Finds the n-th last index within a String, handling {@code null}.
* This method uses {@link String#lastIndexOf(String)}.&/p&
* &p&A {@code null} String will return {@code -1}.&/p&
* StringUtils.lastOrdinalIndexOf(null, *, *)
* StringUtils.lastOrdinalIndexOf(*, null, *)
* StringUtils.lastOrdinalIndexOf(&&, &&, *)
* StringUtils.lastOrdinalIndexOf(&aabaabaa&, &a&, 1)
* StringUtils.lastOrdinalIndexOf(&aabaabaa&, &a&, 2)
* StringUtils.lastOrdinalIndexOf(&aabaabaa&, &b&, 1)
* StringUtils.lastOrdinalIndexOf(&aabaabaa&, &b&, 2)
* StringUtils.lastOrdinalIndexOf(&aabaabaa&, &ab&, 1) = 4
* StringUtils.lastOrdinalIndexOf(&aabaabaa&, &ab&, 2) = 1
* StringUtils.lastOrdinalIndexOf(&aabaabaa&, &&, 1)
* StringUtils.lastOrdinalIndexOf(&aabaabaa&, &&, 2)
* &p&Note that 'tail(CharSequence str, int n)' may be implemented as: &/p&
str.substring(lastOrdinalIndexOf(str, &\n&, n) + 1)
* @param str
the CharSequence to check, may be null
* @param searchStr
the CharSequence to find, may be null
* @param ordinal
the n-th last {@code searchStr} to find
* @return the n-th last index of the search CharSequence,
{@code -1} ({@code INDEX_NOT_FOUND}) if no match or {@code null} string input
* @since 2.5
* @since 3.0 Changed signature from lastOrdinalIndexOf(String, String, int) to lastOrdinalIndexOf(CharSequence, CharSequence, int)
public static int lastOrdinalIndexOf(CharSequence str, CharSequence searchStr, int ordinal) {
return ordinalIndexOf(str, searchStr, ordinal, true);
* &p&Finds the first index within a CharSequence, handling {@code null}.
* This method uses {@link String#lastIndexOf(String, int)} if possible.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A negative start position returns {@code -1}.
* An empty (&&) search CharSequence always matches unless the start position is negative.
* A start position greater than the string length searches the whole string.&/p&
* StringUtils.lastIndexOf(null, *, *)
* StringUtils.lastIndexOf(*, null, *)
* StringUtils.lastIndexOf(&aabaabaa&, &a&, 8)
* StringUtils.lastIndexOf(&aabaabaa&, &b&, 8)
* StringUtils.lastIndexOf(&aabaabaa&, &ab&, 8) = 4
* StringUtils.lastIndexOf(&aabaabaa&, &b&, 9)
* StringUtils.lastIndexOf(&aabaabaa&, &b&, -1) = -1
* StringUtils.lastIndexOf(&aabaabaa&, &a&, 0)
* StringUtils.lastIndexOf(&aabaabaa&, &b&, 0)
* @param seq
the CharSequence to check, may be null
* @param searchSeq
the CharSequence to find, may be null
* @param startPos
the start position, negative treated as zero
* @return the first index of the search CharSequence,
-1 if no match or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from lastIndexOf(String, String, int) to lastIndexOf(CharSequence, CharSequence, int)
public static int lastIndexOf(CharSequence seq, CharSequence searchSeq, int startPos) {
if (seq == null || searchSeq == null) {
return INDEX_NOT_FOUND;
return CharSequenceUtils.lastIndexOf(seq, searchSeq, startPos);
* &p&Case in-sensitive find of the last index within a CharSequence.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A negative start position returns {@code -1}.
* An empty (&&) search CharSequence always matches unless the start position is negative.
* A start position greater than the string length searches the whole string.&/p&
* StringUtils.lastIndexOfIgnoreCase(null, *)
* StringUtils.lastIndexOfIgnoreCase(*, null)
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &A&)
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &B&)
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &AB&) = 4
* @param str
the CharSequence to check, may be null
* @param searchStr
the CharSequence to find, may be null
* @return the first index of the search CharSequence,
-1 if no match or {@code null} string input
* @since 2.5
* @since 3.0 Changed signature from lastIndexOfIgnoreCase(String, String) to lastIndexOfIgnoreCase(CharSequence, CharSequence)
public static int lastIndexOfIgnoreCase(CharSequence str, CharSequence searchStr) {
if (str == null || searchStr == null) {
return INDEX_NOT_FOUND;
return lastIndexOfIgnoreCase(str, searchStr, str.length());
* &p&Case in-sensitive find of the last index within a CharSequence
* from the specified position.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A negative start position returns {@code -1}.
* An empty (&&) search CharSequence always matches unless the start position is negative.
* A start position greater than the string length searches the whole string.&/p&
* StringUtils.lastIndexOfIgnoreCase(null, *, *)
* StringUtils.lastIndexOfIgnoreCase(*, null, *)
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &A&, 8)
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &B&, 8)
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &AB&, 8) = 4
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &B&, 9)
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &B&, -1) = -1
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &A&, 0)
* StringUtils.lastIndexOfIgnoreCase(&aabaabaa&, &B&, 0)
* @param str
the CharSequence to check, may be null
* @param searchStr
the CharSequence to find, may be null
* @param startPos
the start position
* @return the first index of the search CharSequence,
-1 if no match or {@code null} input
* @since 2.5
* @since 3.0 Changed signature from lastIndexOfIgnoreCase(String, String, int) to lastIndexOfIgnoreCase(CharSequence, CharSequence, int)
public static int lastIndexOfIgnoreCase(CharSequence str, CharSequence searchStr, int startPos) {
if (str == null || searchStr == null) {
return INDEX_NOT_FOUND;
if (startPos & (str.length() - searchStr.length())) {
startPos = str.length() - searchStr.length();
if (startPos & 0) {
return INDEX_NOT_FOUND;
if (searchStr.length() == 0) {
return startP
for (int i = startP i &= 0; i--) {
if (CharSequenceUtils.regionMatches(str, true, i, searchStr, 0, searchStr.length())) {
return INDEX_NOT_FOUND;
// Contains
//-----------------------------------------------------------------------
* &p&Checks if CharSequence contains a search character, handling {@code null}.
* This method uses {@link String#indexOf(int)} if possible.&/p&
* &p&A {@code null} or empty (&&) CharSequence will return {@code false}.&/p&
* StringUtils.contains(null, *)
* StringUtils.contains(&&, *)
* StringUtils.contains(&abc&, 'a') = true
* StringUtils.contains(&abc&, 'z') = false
* @param seq
the CharSequence to check, may be null
* @param searchChar
the character to find
* @return true if the CharSequence contains the search character,
false if not or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from contains(String, int) to contains(CharSequence, int)
public static boolean contains(CharSequence seq, int searchChar) {
if (isEmpty(seq)) {
return CharSequenceUtils.indexOf(seq, searchChar, 0) &= 0;
* &p&Checks if CharSequence contains a search CharSequence, handling {@code null}.
* This method uses {@link String#indexOf(String)} if possible.&/p&
* &p&A {@code null} CharSequence will return {@code false}.&/p&
* StringUtils.contains(null, *)
* StringUtils.contains(*, null)
* StringUtils.contains(&&, &&)
* StringUtils.contains(&abc&, &&)
* StringUtils.contains(&abc&, &a&)
* StringUtils.contains(&abc&, &z&)
* @param seq
the CharSequence to check, may be null
* @param searchSeq
the CharSequence to find, may be null
* @return true if the CharSequence contains the search CharSequence,
false if not or {@code null} string input
* @since 2.0
* @since 3.0 Changed signature from contains(String, String) to contains(CharSequence, CharSequence)
public static boolean contains(CharSequence seq, CharSequence searchSeq) {
if (seq == null || searchSeq == null) {
return CharSequenceUtils.indexOf(seq, searchSeq, 0) &= 0;
* &p&Checks if CharSequence contains a search CharSequence irrespective of case,
* handling {@code null}. Case-insensitivity is defined as by
* {@link String#equalsIgnoreCase(String)}.
* &p&A {@code null} CharSequence will return {@code false}.&/p&
* 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
* StringUtils.contains(&abc&, &A&) = true
* StringUtils.contains(&abc&, &Z&) = false
* @param str
the CharSequence to check, may be null
* @param searchStr
the CharSequence to find, may be null
* @return true if the CharSequence contains the search CharSequence irrespective of
* case or false if not or {@code null} string input
* @since 3.0 Changed signature from containsIgnoreCase(String, String) to containsIgnoreCase(CharSequence, CharSequence)
public static boolean containsIgnoreCase(CharSequence str, CharSequence searchStr) {
if (str == null || searchStr == null) {
int len = searchStr.length();
int max = str.length() -
for (int i = 0; i &= i++) {
if (CharSequenceUtils.regionMatches(str, true, i, searchStr, 0, len)) {
* Check whether the given CharSequence contains any whitespace characters.
* @param seq the CharSequence to check (may be {@code null})
* @return {@code true} if the CharSequence is not empty and
* contains at least 1 whitespace character
* @see java.lang.Character#isWhitespace
* @since 3.0
// From org.springframework.util.StringUtils, under Apache License 2.0
public static boolean containsWhitespace(CharSequence seq) {
if (isEmpty(seq)) {
int strLen = seq.length();
for (int i = 0; i & strL i++) {
if (Character.isWhitespace(seq.charAt(i))) {
// IndexOfAny chars
//-----------------------------------------------------------------------
* &p&Search a CharSequence to find the first index of any
* character in the given set of characters.&/p&
* &p&A {@code null} String will return {@code -1}.
* A {@code null} or zero length search array will return {@code -1}.&/p&
* StringUtils.indexOfAny(null, *)
* StringUtils.indexOfAny(&&, *)
* StringUtils.indexOfAny(*, null)
* StringUtils.indexOfAny(*, [])
* StringUtils.indexOfAny(&zzabyycdxx&,['z','a']) = 0
* StringUtils.indexOfAny(&zzabyycdxx&,['b','y']) = 3
* StringUtils.indexOfAny(&aba&, ['z'])
* @param cs
the CharSequence to check, may be null
* @param searchChars
the chars to search for, may be null
* @return the index of any of the chars, -1 if no match or null input
* @since 2.0
* @since 3.0 Changed signature from indexOfAny(String, char[]) to indexOfAny(CharSequence, char...)
public static int indexOfAny(CharSequence cs, char... searchChars) {
if (isEmpty(cs) || ArrayUtils.isEmpty(searchChars)) {
return INDEX_NOT_FOUND;
int csLen = cs.length();
int csLast = csLen - 1;
int searchLen = searchChars.
int searchLast = searchLen - 1;
for (int i = 0; i & csL i++) {
char ch = cs.charAt(i);
for (int j = 0; j & searchL j++) {
if (searchChars[j] == ch) {
if (i & csLast && j & searchLast && Character.isHighSurrogate(ch)) {
// ch is a supplementary character
if (searchChars[j + 1] == cs.charAt(i + 1)) {
return INDEX_NOT_FOUND;
* &p&Search a CharSequence to find the first index of any
* character in the given set of characters.&/p&
* &p&A {@code null} String will return {@code -1}.
* A {@code null} search string will return {@code -1}.&/p&
* StringUtils.indexOfAny(null, *)
* StringUtils.indexOfAny(&&, *)
* StringUtils.indexOfAny(*, null)
* StringUtils.indexOfAny(*, &&)
* StringUtils.indexOfAny(&zzabyycdxx&, &za&) = 0
* StringUtils.indexOfAny(&zzabyycdxx&, &by&) = 3
* StringUtils.indexOfAny(&aba&,&z&)
* @param cs
the CharSequence to check, may be null
* @param searchChars
the chars to search for, may be null
* @return the index of any of the chars, -1 if no match or null input
* @since 2.0
* @since 3.0 Changed signature from indexOfAny(String, String) to indexOfAny(CharSequence, String)
public static int indexOfAny(CharSequence cs, String searchChars) {
if (isEmpty(cs) || isEmpty(searchChars)) {
return INDEX_NOT_FOUND;
return indexOfAny(cs, searchChars.toCharArray());
// ContainsAny
//-----------------------------------------------------------------------
* &p&Checks if the CharSequence contains any character in the given
* set of characters.&/p&
* &p&A {@code null} CharSequence will return {@code false}.
* A {@code null} or zero length search array will return {@code false}.&/p&
* StringUtils.containsAny(null, *)
* StringUtils.containsAny(&&, *)
* StringUtils.containsAny(*, null)
* StringUtils.containsAny(*, [])
* StringUtils.containsAny(&zzabyycdxx&,['z','a']) = true
* StringUtils.containsAny(&zzabyycdxx&,['b','y']) = true
* StringUtils.containsAny(&aba&, ['z'])
* @param cs
the CharSequence to check, may be null
* @param searchChars
the chars to search for, may be null
* @return the {@code true} if any of the chars are found,
* {@code false} if no match or null input
* @since 2.4
* @since 3.0 Changed signature from containsAny(String, char[]) to containsAny(CharSequence, char...)
public static boolean containsAny(CharSequence cs, char... searchChars) {
if (isEmpty(cs) || ArrayUtils.isEmpty(searchChars)) {
int csLength = cs.length();
int searchLength = searchChars.
int csLast = csLength - 1;
int searchLast = searchLength - 1;
for (int i = 0; i & csL i++) {
char ch = cs.charAt(i);
for (int j = 0; j & searchL j++) {
if (searchChars[j] == ch) {
if (Character.isHighSurrogate(ch)) {
if (j == searchLast) {
// missing low surrogate, fine, like String.indexOf(String)
if (i & csLast && searchChars[j + 1] == cs.charAt(i + 1)) {
// ch is in the Basic Multilingual Plane
* Checks if the CharSequence contains any character in the given set of characters.
* A {@code null} CharSequence will return {@code false}. A {@code null} search CharSequence will return
* {@code false}.
* StringUtils.containsAny(null, *)
* StringUtils.containsAny(&&, *)
* StringUtils.containsAny(*, null)
* StringUtils.containsAny(*, &&)
* StringUtils.containsAny(&zzabyycdxx&, &za&) = true
* StringUtils.containsAny(&zzabyycdxx&, &by&) = true
* StringUtils.containsAny(&aba&,&z&)
* @param cs
the CharSequence to check, may be null
* @param searchChars
the chars to search for, may be null
* @return the {@code true} if any of the chars are found, {@code false} if no match or null input
* @since 2.4
* @since 3.0 Changed signature from containsAny(String, String) to containsAny(CharSequence, CharSequence)
public static boolean containsAny(CharSequence cs, CharSequence searchChars) {
if (searchChars == null) {
return containsAny(cs, CharSequenceUtils.toCharArray(searchChars));
// IndexOfAnyBut chars
//-----------------------------------------------------------------------
* &p&Searches a CharSequence to find the first index of any
* character not in the given set of characters.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A {@code null} or zero length search array will return {@code -1}.&/p&
* StringUtils.indexOfAnyBut(null, *)
* StringUtils.indexOfAnyBut(&&, *)
* StringUtils.indexOfAnyBut(*, null)
* StringUtils.indexOfAnyBut(*, [])
* StringUtils.indexOfAnyBut(&zzabyycdxx&, new char[] {'z', 'a'} ) = 3
* StringUtils.indexOfAnyBut(&aba&, new char[] {'z'} )
* StringUtils.indexOfAnyBut(&aba&, new char[] {'a', 'b'} )
* @param cs
the CharSequence to check, may be null
* @param searchChars
the chars to search for, may be null
* @return the index of any of the chars, -1 if no match or null input
* @since 2.0
* @since 3.0 Changed signature from indexOfAnyBut(String, char[]) to indexOfAnyBut(CharSequence, char...)
public static int indexOfAnyBut(CharSequence cs, char... searchChars) {
if (isEmpty(cs) || ArrayUtils.isEmpty(searchChars)) {
return INDEX_NOT_FOUND;
int csLen = cs.length();
int csLast = csLen - 1;
int searchLen = searchChars.
int searchLast = searchLen - 1;
for (int i = 0; i & csL i++) {
char ch = cs.charAt(i);
for (int j = 0; j & searchL j++) {
if (searchChars[j] == ch) {
if (i & csLast && j & searchLast && Character.isHighSurrogate(ch)) {
if (searchChars[j + 1] == cs.charAt(i + 1)) {
return INDEX_NOT_FOUND;
* &p&Search a CharSequence to find the first index of any
* character not in the given set of characters.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A {@code null} or empty search string will return {@code -1}.&/p&
* StringUtils.indexOfAnyBut(null, *)
* StringUtils.indexOfAnyBut(&&, *)
* StringUtils.indexOfAnyBut(*, null)
* StringUtils.indexOfAnyBut(*, &&)
* StringUtils.indexOfAnyBut(&zzabyycdxx&, &za&) = 3
* StringUtils.indexOfAnyBut(&zzabyycdxx&, &&)
* StringUtils.indexOfAnyBut(&aba&,&ab&)
* @param seq
the CharSequence to check, may be null
* @param searchChars
the chars to search for, may be null
* @return the index of any of the chars, -1 if no match or null input
* @since 2.0
* @since 3.0 Changed signature from indexOfAnyBut(String, String) to indexOfAnyBut(CharSequence, CharSequence)
public static int indexOfAnyBut(CharSequence seq, CharSequence searchChars) {
if (isEmpty(seq) || isEmpty(searchChars)) {
return INDEX_NOT_FOUND;
int strLen = seq.length();
for (int i = 0; i & strL i++) {
char ch = seq.charAt(i);
boolean chFound = CharSequenceUtils.indexOf(searchChars, ch, 0) &= 0;
if (i + 1 & strLen && Character.isHighSurrogate(ch)) {
char ch2 = seq.charAt(i + 1);
if (chFound && CharSequenceUtils.indexOf(searchChars, ch2, 0) & 0) {
if (!chFound) {
return INDEX_NOT_FOUND;
// ContainsOnly
//-----------------------------------------------------------------------
* &p&Checks if the CharSequence contains only certain characters.&/p&
* &p&A {@code null} CharSequence will return {@code false}.
* A {@code null} valid character array will return {@code false}.
* An empty CharSequence (length()=0) always returns {@code true}.&/p&
* StringUtils.containsOnly(null, *)
* StringUtils.containsOnly(*, null)
* StringUtils.containsOnly(&&, *)
* StringUtils.containsOnly(&ab&, '')
* StringUtils.containsOnly(&abab&, 'abc') = true
* StringUtils.containsOnly(&ab1&, 'abc')
* StringUtils.containsOnly(&abz&, 'abc')
* @param cs
the String to check, may be null
* @param valid
an array of valid chars, may be null
* @return true if it only contains valid chars and is non-null
* @since 3.0 Changed signature from containsOnly(String, char[]) to containsOnly(CharSequence, char...)
public static boolean containsOnly(CharSequence cs, char... valid) {
// All these pre-checks are to maintain API with an older version
if (valid == null || cs == null) {
if (cs.length() == 0) {
if (valid.length == 0) {
return indexOfAnyBut(cs, valid) == INDEX_NOT_FOUND;
* &p&Checks if the CharSequence contains only certain characters.&/p&
* &p&A {@code null} CharSequence will return {@code false}.
* A {@code null} valid character String will return {@code false}.
* An empty String (length()=0) always returns {@code true}.&/p&
* StringUtils.containsOnly(null, *)
* StringUtils.containsOnly(*, null)
* StringUtils.containsOnly(&&, *)
* StringUtils.containsOnly(&ab&, &&)
* StringUtils.containsOnly(&abab&, &abc&) = true
* StringUtils.containsOnly(&ab1&, &abc&)
* StringUtils.containsOnly(&abz&, &abc&)
* @param cs
the CharSequence to check, may be null
* @param validChars
a String of valid chars, may be null
* @return true if it only contains valid chars and is non-null
* @since 2.0
* @since 3.0 Changed signature from containsOnly(String, String) to containsOnly(CharSequence, String)
public static boolean containsOnly(CharSequence cs, String validChars) {
if (cs == null || validChars == null) {
return containsOnly(cs, validChars.toCharArray());
// ContainsNone
//-----------------------------------------------------------------------
* &p&Checks that the CharSequence does not contain certain characters.&/p&
* &p&A {@code null} CharSequence will return {@code true}.
* A {@code null} invalid character array will return {@code true}.
* An empty CharSequence (length()=0) always returns true.&/p&
* StringUtils.containsNone(null, *)
* StringUtils.containsNone(*, null)
* StringUtils.containsNone(&&, *)
* StringUtils.containsNone(&ab&, '')
* StringUtils.containsNone(&abab&, 'xyz') = true
* StringUtils.containsNone(&ab1&, 'xyz')
* StringUtils.containsNone(&abz&, 'xyz')
* @param cs
the CharSequence to check, may be null
* @param searchChars
an array of invalid chars, may be null
* @return true if it contains none of the invalid chars, or is null
* @since 2.0
* @since 3.0 Changed signature from containsNone(String, char[]) to containsNone(CharSequence, char...)
public static boolean containsNone(CharSequence cs, char... searchChars) {
if (cs == null || searchChars == null) {
int csLen = cs.length();
int csLast = csLen - 1;
int searchLen = searchChars.
int searchLast = searchLen - 1;
for (int i = 0; i & csL i++) {
char ch = cs.charAt(i);
for (int j = 0; j & searchL j++) {
if (searchChars[j] == ch) {
if (Character.isHighSurrogate(ch)) {
if (j == searchLast) {
// missing low surrogate, fine, like String.indexOf(String)
if (i & csLast && searchChars[j + 1] == cs.charAt(i + 1)) {
// ch is in the Basic Multilingual Plane
* &p&Checks that the CharSequence does not contain certain characters.&/p&
* &p&A {@code null} CharSequence will return {@code true}.
* A {@code null} invalid character array will return {@code true}.
* An empty String (&&) always returns true.&/p&
* StringUtils.containsNone(null, *)
* StringUtils.containsNone(*, null)
* StringUtils.containsNone(&&, *)
* StringUtils.containsNone(&ab&, &&)
* StringUtils.containsNone(&abab&, &xyz&) = true
* StringUtils.containsNone(&ab1&, &xyz&)
* StringUtils.containsNone(&abz&, &xyz&)
* @param cs
the CharSequence to check, may be null
* @param invalidChars
a String of invalid chars, may be null
* @return true if it contains none of the invalid chars, or is null
* @since 2.0
* @since 3.0 Changed signature from containsNone(String, String) to containsNone(CharSequence, String)
public static boolean containsNone(CharSequence cs, String invalidChars) {
if (cs == null || invalidChars == null) {
return containsNone(cs, invalidChars.toCharArray());
// IndexOfAny strings
//-----------------------------------------------------------------------
* &p&Find the first index of any of a set of potential substrings.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A {@code null} or zero length search array will return {@code -1}.
* A {@code null} search array entry will be ignored, but a search
* array containing && will return {@code 0} if {@code str} is not
* null. This method uses {@link String#indexOf(String)} if possible.&/p&
* StringUtils.indexOfAny(null, *)
* StringUtils.indexOfAny(*, null)
* StringUtils.indexOfAny(*, [])
* StringUtils.indexOfAny(&zzabyycdxx&, [&ab&,&cd&])
* StringUtils.indexOfAny(&zzabyycdxx&, [&cd&,&ab&])
* StringUtils.indexOfAny(&zzabyycdxx&, [&mn&,&op&])
* StringUtils.indexOfAny(&zzabyycdxx&, [&zab&,&aby&]) = 1
* StringUtils.indexOfAny(&zzabyycdxx&, [&&])
* StringUtils.indexOfAny(&&, [&&])
* StringUtils.indexOfAny(&&, [&a&])
* @param str
the CharSequence to check, may be null
* @param searchStrs
the CharSequences to search for, may be null
* @return the first index of any of the searchStrs in str, -1 if no match
* @since 3.0 Changed signature from indexOfAny(String, String[]) to indexOfAny(CharSequence, CharSequence...)
public static int indexOfAny(CharSequence str, CharSequence... searchStrs) {
if (str == null || searchStrs == null) {
return INDEX_NOT_FOUND;
int sz = searchStrs.
// String's can't have a MAX_VALUEth index.
int ret = Integer.MAX_VALUE;
int tmp = 0;
for (int i = 0; i & i++) {
CharSequence search = searchStrs[i];
if (search == null) {
tmp = CharSequenceUtils.indexOf(str, search, 0);
if (tmp == INDEX_NOT_FOUND) {
if (tmp & ret) {
return (ret == Integer.MAX_VALUE) ? INDEX_NOT_FOUND :
* &p&Find the latest index of any of a set of potential substrings.&/p&
* &p&A {@code null} CharSequence will return {@code -1}.
* A {@code null} search array will return {@code -1}.
* A {@code null} or zero length search array entry will be ignored,
* but a search array containing && will return the length of {@code str}
* if {@code str} is not null. This method uses {@link String#indexOf(String)} if possible&/p&
* StringUtils.lastIndexOfAny(null, *)
* StringUtils.lastIndexOfAny(*, null)
* StringUtils.lastIndexOfAny(*, [])
* StringUtils.lastIndexOfAny(*, [null])
* 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&,&&])
* @param str
the CharSequence to check, may be null
* @param searchStrs
the CharSequences to search for, may be null
* @return the last index of any of the CharSequences, -1 if no match
* @since 3.0 Changed signature from lastIndexOfAny(String, String[]) to lastIndexOfAny(CharSequence, CharSequence)
public static int lastIndexOfAny(CharSequence str, CharSequence... searchStrs) {
if (str == null || searchStrs == null) {
return INDEX_NOT_FOUND;
int sz = searchStrs.
int ret = INDEX_NOT_FOUND;
int tmp = 0;
for (int i = 0; i & i++) {
CharSequence search = searchStrs[i];
if (search == null) {
tmp = CharSequenceUtils.lastIndexOf(str, search, str.length());
if (tmp & ret) {
// Substring
//-----------------------------------------------------------------------
* &p&Gets a substring from the specified String avoiding exceptions.&/p&
* &p&A negative start position can be used to start {@code n}
* characters from the end of the String.&/p&
* &p&A {@code null} String will return {@code null}.
* An empty (&&) String will return &&.&/p&
* StringUtils.substring(null, *)
* StringUtils.substring(&&, *)
* StringUtils.substring(&abc&, 0)
* StringUtils.substring(&abc&, 2)
* StringUtils.substring(&abc&, 4)
* StringUtils.substring(&abc&, -2) = &bc&
* StringUtils.substring(&abc&, -4) = &abc&
* @param str
the String to get the substring from, may be null
* @param start
the position to start from, negative means
count back from the end of the String by this many characters
* @return substring from start position, {@code null} if null String input
public static String substring(String str, int start) {
if (str == null) {
// handle negatives, which means last n characters
if (start & 0) {
start = str.length() + // remember start is negative
if (start & 0) {
start = 0;
if (start & str.length()) {
return EMPTY;
return str.substring(start);
* &p&Gets a substring from the specified String avoiding exceptions.&/p&
* &p&A negative start position can be used to start/end {@code n}
* characters from the end of the String.&/p&
* &p&The returned substring starts with the character in the {@code start}
* position and ends before the {@code end} position. All position counting is
* zero-based -- i.e., to start at the beginning of the string use
* {@code start = 0}. Negative start and end positions can be used to
* specify offsets relative to the end of the String.&/p&
* &p&If {@code start} is not strictly to the left of {@code end}, &&
* is returned.&/p&
* StringUtils.substring(null, *, *)
* StringUtils.substring(&&, * ,
* StringUtils.substring(&abc&, 0, 2)
* StringUtils.substring(&abc&, 2, 0)
* StringUtils.substring(&abc&, 2, 4)
* StringUtils.substring(&abc&, 4, 6)
* StringUtils.substring(&abc&, 2, 2)
* StringUtils.substring(&abc&, -2, -1) = &b&
* StringUtils.substring(&abc&, -4, 2)
* @param str
the String to get the substring from, may be null
* @param start
the position to start from, negative means
count back from the end of the String by this many characters
* @param end
the position t}