net.hasor.utils.StringUtils Maven / Gradle / Ivy
/*
* 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 net.hasor.utils;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Locale;
/**
* Operations on {@link String} that are
* null safe.
*
*
* - IsEmpty/IsBlank
* - checks if a String contains text
* - Trim/Strip
* - removes leading and trailing whitespace
* - Equals
* - compares two strings null-safe
* - startsWith
* - check if a String starts with a prefix null-safe
* - endsWith
* - check if a String ends with a suffix null-safe
* - IndexOf/LastIndexOf/Contains
* - null-safe index-of checks
*
- IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut
* - index-of any of a set of Strings
* - ContainsOnly/ContainsNone/ContainsAny
* - does String contains only/none/any of these characters
* - Substring/Left/Right/Mid
* - null-safe substring extractions
* - SubstringBefore/SubstringAfter/SubstringBetween
* - substring extraction relative to other strings
* - Split/Join
* - splits a String into an array of substrings and vice versa
* - Remove/Delete
* - removes part of a String
* - Replace/Overlay
* - Searches a String and replaces one String with another
* - Chomp/Chop
* - removes the last part of a String
* - LeftPad/RightPad/Center/Repeat
* - pads a String
* - UpperCase/LowerCase/SwapCase/Capitalize/Uncapitalize
* - changes the case of a String
* - CountMatches
* - counts the number of occurrences of one String in another
* - IsAlpha/IsNumeric/IsWhitespace/IsAsciiPrintable
* - checks the characters in a String
* - DefaultString
* - protects against a null input String
* - Reverse/ReverseDelimited
* - reverses a String
* - Abbreviate
* - abbreviates a string using ellipsis
* - Difference
* - compares Strings and reports on their differences
* - LevensteinDistance
* - the number of changes needed to change one String into another
*
*
* The StringUtils class defines certain words related to
* String handling.
*
*
* - null -
null
* - empty - a zero-length string (
"")
* - space - the space character (
' ', char 32)
* - whitespace - the characters defined by {@link Character#isWhitespace(char)}
* - trim - the characters <= 32 as in {@link 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.
*
* #ThreadSafe#
* @see String
* @author Apache Software Foundation
* @author Apache Jakarta Turbine
* @author Jon S. Stevens
* @author Daniel L. Rall
* @author Greg Coladonato
* @author Ed Korthof
* @author Rand McNeely
* @author Fredrik Westermarck
* @author Holger Krauth
* @author Alexander Day Chaffee
* @author Henning P. Schmiedehausen
* @author Arun Mammen Thomas
* @author Gary Gregory
* @author Phil Steitz
* @author Al Chou
* @author Michael Davey
* @author Reuben Sivan
* @author Chris Hyzer
* @author Scott Johnson
* @since 1.0
* @version $Id: StringUtils.java 1058365 2011-01-13 00:04:49Z niallp $
*/
//@Immutable
public class StringUtils {
// Performance testing notes (JDK 1.4, Jul03, scolebourne)
// Whitespace:
// Character.isWhitespace() is faster than WHITESPACE.indexOf()
// where WHITESPACE is a string of all whitespace characters
//
// Character access:
// String.charAt(n) versus toCharArray(), then array[n]
// String.charAt(n) is about 15% worse for a 10K string
// They are about equal for a length 50 string
// String.charAt(n) is about 4 times better for a length 3 string
// String.charAt(n) is best bet overall
//
// Append:
// String.concat about twice as fast as StringBuffer.append
// (not sure who tested this)
/**
* The empty String "".
* @since 2.0
*/
public static final String EMPTY = "";
/**
* Represents a failed index search.
* @since 2.1
*/
public static final int INDEX_NOT_FOUND = -1;
/**
* The maximum size to which the padding constant(s) can expand.
*/
private static final int PAD_LIMIT = 8192;
/**
* StringUtils instances should NOT be constructed in
* standard programming. Instead, the class should be used as
* StringUtils.trim(" foo ");.
*
* This constructor is public to permit tools that require a JavaBean
* instance to operate.
*/
public StringUtils() {
super();
}
// Empty checks
//-----------------------------------------------------------------------
/**
* Checks if a String is empty ("") or null.
*
*
* StringUtils.isEmpty(null) = true
* StringUtils.isEmpty("") = true
* StringUtils.isEmpty(" ") = false
* StringUtils.isEmpty("bob") = false
* StringUtils.isEmpty(" bob ") = false
*
*
* NOTE: This method changed in Lang version 2.0.
* It no longer trims the String.
* That functionality is available in isBlank().
*
* @param str the String to check, may be null
* @return true if the String is empty or null
*/
public static boolean isEmpty(final String str) {
return str == null || str.length() == 0;
}
/**
* 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
*
*
* @param str the String to check, may be null
* @return true if the String is not empty and not null
*/
public static boolean isNotEmpty(final String str) {
return !StringUtils.isEmpty(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
*
*
* @param str the String to check, may be null
* @return true if the String is null, empty or whitespace
* @since 2.0
*/
public static boolean isBlank(final String str) {
int strLen;
if (str == null || (strLen = str.length()) == 0) {
return true;
}
for (int i = 0; i < strLen; i++) {
if (Character.isWhitespace(str.charAt(i)) == false) {
return false;
}
}
return true;
}
/**
* 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
*
*
* @param str the String to check, may be null
* @return true if the String is
* not empty and not null and not whitespace
* @since 2.0
*/
public static boolean isNotBlank(final String str) {
return !StringUtils.isBlank(str);
}
// Trim
//-----------------------------------------------------------------------
/**
* Removes control characters (char <= 32) from both
* ends of this String, handling null by returning
* null.
*
* The String is trimmed using {@link String#trim()}.
* Trim removes start and end characters <= 32.
* To strip whitespace use {@link #strip(String)}.
*
* To trim your choice of characters, use the
* {@link #strip(String, String)} methods.
*
*
* StringUtils.trim(null) = null
* StringUtils.trim("") = ""
* StringUtils.trim(" ") = ""
* StringUtils.trim("abc") = "abc"
* StringUtils.trim(" abc ") = "abc"
*
*
* @param str the String to be trimmed, may be null
* @return the trimmed string, null if null String input
*/
public static String trim(final String str) {
return str == null ? null : str.trim();
}
/**
* Removes control characters (char <= 32) from both
* ends of this String returning null if the String is
* empty ("") after the trim or if it is null.
*
*
The String is trimmed using {@link String#trim()}.
* Trim removes start and end characters <= 32.
* To strip whitespace use {@link #stripToNull(String)}.
*
*
* StringUtils.trimToNull(null) = null
* StringUtils.trimToNull("") = null
* StringUtils.trimToNull(" ") = null
* StringUtils.trimToNull("abc") = "abc"
* StringUtils.trimToNull(" abc ") = "abc"
*
*
* @param str the String to be trimmed, may be null
* @return the trimmed String,
* null if only chars <= 32, empty or null String input
* @since 2.0
*/
public static String trimToNull(final String str) {
String ts = StringUtils.trim(str);
return StringUtils.isEmpty(ts) ? null : ts;
}
/**
* Removes control characters (char <= 32) from both
* ends of this String returning an empty String ("") if the String
* is empty ("") after the trim or if it is null.
*
*
The String is trimmed using {@link String#trim()}.
* Trim removes start and end characters <= 32.
* To strip whitespace use {@link #stripToEmpty(String)}.
*
*
* StringUtils.trimToEmpty(null) = ""
* StringUtils.trimToEmpty("") = ""
* StringUtils.trimToEmpty(" ") = ""
* StringUtils.trimToEmpty("abc") = "abc"
* StringUtils.trimToEmpty(" abc ") = "abc"
*
*
* @param str the String to be trimmed, may be null
* @return the trimmed String, or an empty String if null input
* @since 2.0
*/
public static String trimToEmpty(final String str) {
return str == null ? StringUtils.EMPTY : str.trim();
}
// Stripping
//-----------------------------------------------------------------------
/**
* Strips whitespace from the start and end of a String.
*
* This is similar to {@link #trim(String)} but removes whitespace.
* Whitespace is defined by {@link Character#isWhitespace(char)}.
*
* A null input String returns null.
*
*
* StringUtils.strip(null) = null
* StringUtils.strip("") = ""
* StringUtils.strip(" ") = ""
* StringUtils.strip("abc") = "abc"
* StringUtils.strip(" abc") = "abc"
* StringUtils.strip("abc ") = "abc"
* StringUtils.strip(" abc ") = "abc"
* StringUtils.strip(" ab c ") = "ab c"
*
*
* @param str the String to remove whitespace from, may be null
* @return the stripped String, null if null String input
*/
public static String strip(final String str) {
return StringUtils.strip(str, null);
}
/**
* Strips whitespace from the start and end of a String returning
* null if the String is empty ("") after the strip.
*
* This is similar to {@link #trimToNull(String)} but removes whitespace.
* Whitespace is defined by {@link Character#isWhitespace(char)}.
*
*
* StringUtils.stripToNull(null) = null
* StringUtils.stripToNull("") = null
* StringUtils.stripToNull(" ") = null
* StringUtils.stripToNull("abc") = "abc"
* StringUtils.stripToNull(" abc") = "abc"
* StringUtils.stripToNull("abc ") = "abc"
* StringUtils.stripToNull(" abc ") = "abc"
* StringUtils.stripToNull(" ab c ") = "ab c"
*
*
* @param str the String to be stripped, may be null
* @return the stripped String,
* null if whitespace, empty or null String input
* @since 2.0
*/
public static String stripToNull(String str) {
if (str == null) {
return null;
}
str = StringUtils.strip(str, null);
return str.length() == 0 ? null : str;
}
/**
* Strips whitespace from the start and end of a String returning
* an empty String if null input.
*
* This is similar to {@link #trimToEmpty(String)} but removes whitespace.
* Whitespace is defined by {@link Character#isWhitespace(char)}.
*
*
* StringUtils.stripToEmpty(null) = ""
* StringUtils.stripToEmpty("") = ""
* StringUtils.stripToEmpty(" ") = ""
* StringUtils.stripToEmpty("abc") = "abc"
* StringUtils.stripToEmpty(" abc") = "abc"
* StringUtils.stripToEmpty("abc ") = "abc"
* StringUtils.stripToEmpty(" abc ") = "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 null input
* @since 2.0
*/
public static String stripToEmpty(final String str) {
return str == null ? StringUtils.EMPTY : StringUtils.strip(str, null);
}
/**
* 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.
*
* A null input String returns null.
* An empty string ("") input returns the empty string.
*
* If the stripChars String is null, whitespace is
* stripped as defined by {@link Character#isWhitespace(char)}.
* Alternatively use {@link #strip(String)}.
*
*
* StringUtils.strip(null, *) = null
* StringUtils.strip("", *) = ""
* StringUtils.strip("abc", null) = "abc"
* StringUtils.strip(" abc", null) = "abc"
* StringUtils.strip("abc ", null) = "abc"
* StringUtils.strip(" abc ", null) = "abc"
* StringUtils.strip(" abcyx", "xyz") = " abc"
*
*
* @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, null if null String input
*/
public static String strip(String str, final String stripChars) {
if (StringUtils.isEmpty(str)) {
return str;
}
str = StringUtils.stripStart(str, stripChars);
return StringUtils.stripEnd(str, stripChars);
}
/**
* Strips any of a set of characters from the start of a String.
*
* A null input String returns null.
* An empty string ("") input returns the empty string.
*
* If the stripChars String is null, whitespace is
* stripped as defined by {@link Character#isWhitespace(char)}.
*
*
* StringUtils.stripStart(null, *) = null
* StringUtils.stripStart("", *) = ""
* StringUtils.stripStart("abc", "") = "abc"
* StringUtils.stripStart("abc", null) = "abc"
* StringUtils.stripStart(" abc", null) = "abc"
* StringUtils.stripStart("abc ", null) = "abc "
* StringUtils.stripStart(" abc ", null) = "abc "
* StringUtils.stripStart("yxabc ", "xyz") = "abc "
*
*
* @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, null if null String input
*/
public static String stripStart(final String str, final String stripChars) {
int strLen;
if (str == null || (strLen = str.length()) == 0) {
return str;
}
int start = 0;
if (stripChars == null) {
while (start != strLen && Character.isWhitespace(str.charAt(start))) {
start++;
}
} else if (stripChars.length() == 0) {
return str;
} else {
while (start != strLen && stripChars.indexOf(str.charAt(start)) != StringUtils.INDEX_NOT_FOUND) {
start++;
}
}
return str.substring(start);
}
/**
* Strips any of a set of characters from the end of a String.
*
* A null input String returns null.
* An empty string ("") input returns the empty string.
*
* If the stripChars String is null, whitespace is
* stripped as defined by {@link Character#isWhitespace(char)}.
*
*
* StringUtils.stripEnd(null, *) = null
* StringUtils.stripEnd("", *) = ""
* StringUtils.stripEnd("abc", "") = "abc"
* StringUtils.stripEnd("abc", null) = "abc"
* StringUtils.stripEnd(" abc", null) = " abc"
* StringUtils.stripEnd("abc ", null) = "abc"
* StringUtils.stripEnd(" abc ", null) = " abc"
* StringUtils.stripEnd(" abcyx", "xyz") = " abc"
* StringUtils.stripEnd("120.00", ".0") = "12"
*
*
* @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, null if null String input
*/
public static String stripEnd(final String str, final String stripChars) {
int end;
if (str == null || (end = str.length()) == 0) {
return str;
}
if (stripChars == null) {
while (end != 0 && Character.isWhitespace(str.charAt(end - 1))) {
end--;
}
} else if (stripChars.length() == 0) {
return str;
} else {
while (end != 0 && stripChars.indexOf(str.charAt(end - 1)) != StringUtils.INDEX_NOT_FOUND) {
end--;
}
}
return str.substring(0, end);
}
// StripAll
//-----------------------------------------------------------------------
/**
* Strips whitespace from the start and end of every String in an array.
* Whitespace is defined by {@link Character#isWhitespace(char)}.
*
* A new array is returned each time, except for length zero.
* A null array will return null.
* An empty array will return itself.
* A null array entry will be ignored.
*
*
* StringUtils.stripAll(null) = null
* StringUtils.stripAll([]) = []
* StringUtils.stripAll(["abc", " abc"]) = ["abc", "abc"]
* StringUtils.stripAll(["abc ", null]) = ["abc", null]
*
*
* @param strs the array to remove whitespace from, may be null
* @return the stripped Strings, null if null array input
*/
public static String[] stripAll(final String[] strs) {
return StringUtils.stripAll(strs, null);
}
/**
* Strips any of a set of characters from the start and end of every
* String in an array.
* Whitespace is defined by {@link Character#isWhitespace(char)}.
*
* A new array is returned each time, except for length zero.
* A null array will return null.
* An empty array will return itself.
* A null array entry will be ignored.
* A null stripChars will strip whitespace as defined by
* {@link Character#isWhitespace(char)}.
*
*
* StringUtils.stripAll(null, *) = null
* StringUtils.stripAll([], *) = []
* StringUtils.stripAll(["abc", " abc"], null) = ["abc", "abc"]
* StringUtils.stripAll(["abc ", null], null) = ["abc", null]
* StringUtils.stripAll(["abc ", null], "yz") = ["abc ", null]
* StringUtils.stripAll(["yabcz", null], "yz") = ["abc", null]
*
*
* @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, null if null array input
*/
public static String[] stripAll(final String[] strs, final String stripChars) {
int strsLen;
if (strs == null || (strsLen = strs.length) == 0) {
return strs;
}
String[] newArr = new String[strsLen];
for (int i = 0; i < strsLen; i++) {
newArr[i] = StringUtils.strip(strs[i], stripChars);
}
return newArr;
}
// Equals
//-----------------------------------------------------------------------
/**
* Compares two Strings, returning true if they are equal.
*
* nulls are handled without exceptions. Two null
* references are considered to be equal. The comparison is case sensitive.
*
*
* StringUtils.equals(null, null) = true
* StringUtils.equals(null, "abc") = false
* StringUtils.equals("abc", null) = false
* StringUtils.equals("abc", "abc") = true
* StringUtils.equals("abc", "ABC") = false
*
*
* @see String#equals(Object)
* @param str1 the first String, may be null
* @param str2 the second String, may be null
* @return true if the Strings are equal, case sensitive, or
* both null
*/
public static boolean equals(final String str1, final String str2) {
return str1 == null ? str2 == null : str1.equals(str2);
}
/**
* Compares two Strings, returning true if they are equal ignoring
* the case.
*
* nulls are handled without exceptions. Two null
* references are considered equal. Comparison is case insensitive.
*
*
* StringUtils.equalsIgnoreCase(null, null) = true
* StringUtils.equalsIgnoreCase(null, "abc") = false
* StringUtils.equalsIgnoreCase("abc", null) = false
* StringUtils.equalsIgnoreCase("abc", "abc") = true
* StringUtils.equalsIgnoreCase("abc", "ABC") = true
*
*
* @see String#equalsIgnoreCase(String)
* @param str1 the first String, may be null
* @param str2 the second String, may be null
* @return true if the Strings are equal, case insensitive, or
* both null
*/
public static boolean equalsIgnoreCase(final String str1, final String str2) {
return str1 == null ? str2 == null : str1.equalsIgnoreCase(str2);
}
// IndexOf
//-----------------------------------------------------------------------
/**
* Finds the first index within a String, handling null.
* This method uses {@link String#indexOf(int)}.
*
* A null or empty ("") String will return INDEX_NOT_FOUND (-1).
*
*
* StringUtils.indexOf(null, *) = -1
* StringUtils.indexOf("", *) = -1
* StringUtils.indexOf("aabaabaa", 'a') = 0
* StringUtils.indexOf("aabaabaa", 'b') = 2
*
*
* @param str the String to check, may be null
* @param searchChar the character to find
* @return the first index of the search character,
* -1 if no match or null string input
* @since 2.0
*/
public static int indexOf(final String str, final char searchChar) {
if (StringUtils.isEmpty(str)) {
return StringUtils.INDEX_NOT_FOUND;
}
return str.indexOf(searchChar);
}
/**
* Finds the first index within a String from a start position,
* handling null.
* This method uses {@link String#indexOf(int, int)}.
*
* A null or empty ("") String will return (INDEX_NOT_FOUND) -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
*
*
* @param str the String 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 null string input
* @since 2.0
*/
public static int indexOf(final String str, final char searchChar, final int startPos) {
if (StringUtils.isEmpty(str)) {
return StringUtils.INDEX_NOT_FOUND;
}
return str.indexOf(searchChar, startPos);
}
/**
* Finds the first index within a String, handling null.
* This method uses {@link String#indexOf(String)}.
*
* A null String will return -1.
*
*
* StringUtils.indexOf(null, *) = -1
* StringUtils.indexOf(*, null) = -1
* StringUtils.indexOf("", "") = 0
* StringUtils.indexOf("", *) = -1 (except when * = "")
* StringUtils.indexOf("aabaabaa", "a") = 0
* StringUtils.indexOf("aabaabaa", "b") = 2
* StringUtils.indexOf("aabaabaa", "ab") = 1
* StringUtils.indexOf("aabaabaa", "") = 0
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @return the first index of the search String,
* -1 if no match or null string input
* @since 2.0
*/
public static int indexOf(final String str, final String searchStr) {
if (str == null || searchStr == null) {
return StringUtils.INDEX_NOT_FOUND;
}
return str.indexOf(searchStr);
}
/**
* Finds the n-th index within a String, handling null.
* This method uses {@link String#indexOf(String)}.
*
* A null 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
*
*
* Note that 'head(String str, int n)' may be implemented as:
*
*
* str.substring(0, lastOrdinalIndexOf(str, "\n", n))
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @param ordinal the n-th searchStr to find
* @return the n-th index of the search String,
* -1 (INDEX_NOT_FOUND) if no match or null string input
* @since 2.1
*/
public static int ordinalIndexOf(final String str, final String searchStr, final int ordinal) {
return StringUtils.ordinalIndexOf(str, searchStr, ordinal, false);
}
/**
* Finds the n-th index within a String, handling null.
* This method uses {@link String#indexOf(String)}.
*
* A null String will return -1.
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @param ordinal the n-th searchStr to find
* @param lastIndex true if lastOrdinalIndexOf() otherwise false if ordinalIndexOf()
* @return the n-th index of the search String,
* -1 (INDEX_NOT_FOUND) if no match or null string input
*/
// Shared code between ordinalIndexOf(String,String,int) and lastOrdinalIndexOf(String,String,int)
private static int ordinalIndexOf(final String str, final String searchStr, final int ordinal, final boolean lastIndex) {
if (str == null || searchStr == null || ordinal <= 0) {
return StringUtils.INDEX_NOT_FOUND;
}
if (searchStr.length() == 0) {
return lastIndex ? str.length() : 0;
}
int found = 0;
int index = lastIndex ? str.length() : StringUtils.INDEX_NOT_FOUND;
do {
if (lastIndex) {
index = str.lastIndexOf(searchStr, index - 1);
} else {
index = str.indexOf(searchStr, index + 1);
}
if (index < 0) {
return index;
}
found++;
} while (found < ordinal);
return index;
}
/**
* Finds the first index within a String, handling null.
* This method uses {@link String#indexOf(String, int)}.
*
* A null String will return -1.
* A negative start position is treated as zero.
* An empty ("") search String always matches.
* A start position greater than the string length only matches
* an empty search String.
*
*
* StringUtils.indexOf(null, *, *) = -1
* StringUtils.indexOf(*, null, *) = -1
* StringUtils.indexOf("", "", 0) = 0
* StringUtils.indexOf("", *, 0) = -1 (except when * = "")
* 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
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @param startPos the start position, negative treated as zero
* @return the first index of the search String,
* -1 if no match or null string input
* @since 2.0
*/
public static int indexOf(final String str, final String searchStr, final int startPos) {
if (str == null || searchStr == null) {
return StringUtils.INDEX_NOT_FOUND;
}
// JDK1.2/JDK1.3 have a bug, when startPos > str.length for "", hence
if (searchStr.length() == 0 && startPos >= str.length()) {
return str.length();
}
return str.indexOf(searchStr, startPos);
}
/**
* Case in-sensitive find of the first index within a String.
*
* A null String will return -1.
* A negative start position is treated as zero.
* An empty ("") search String always matches.
* A start position greater than the string length only matches
* an empty search String.
*
*
* StringUtils.indexOfIgnoreCase(null, *) = -1
* StringUtils.indexOfIgnoreCase(*, null) = -1
* StringUtils.indexOfIgnoreCase("", "") = 0
* StringUtils.indexOfIgnoreCase("aabaabaa", "a") = 0
* StringUtils.indexOfIgnoreCase("aabaabaa", "b") = 2
* StringUtils.indexOfIgnoreCase("aabaabaa", "ab") = 1
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @return the first index of the search String,
* -1 if no match or null string input
* @since 2.5
*/
public static int indexOfIgnoreCase(final String str, final String searchStr) {
return StringUtils.indexOfIgnoreCase(str, searchStr, 0);
}
/**
* Case in-sensitive find of the first index within a String
* from the specified position.
*
* A null String will return -1.
* A negative start position is treated as zero.
* An empty ("") search String always matches.
* A start position greater than the string length only matches
* an empty search String.
*
*
* StringUtils.indexOfIgnoreCase(null, *, *) = -1
* StringUtils.indexOfIgnoreCase(*, null, *) = -1
* StringUtils.indexOfIgnoreCase("", "", 0) = 0
* StringUtils.indexOfIgnoreCase("aabaabaa", "A", 0) = 0
* StringUtils.indexOfIgnoreCase("aabaabaa", "B", 0) = 2
* StringUtils.indexOfIgnoreCase("aabaabaa", "AB", 0) = 1
* StringUtils.indexOfIgnoreCase("aabaabaa", "B", 3) = 5
* StringUtils.indexOfIgnoreCase("aabaabaa", "B", 9) = -1
* StringUtils.indexOfIgnoreCase("aabaabaa", "B", -1) = 2
* StringUtils.indexOfIgnoreCase("aabaabaa", "", 2) = 2
* StringUtils.indexOfIgnoreCase("abc", "", 9) = 3
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @param startPos the start position, negative treated as zero
* @return the first index of the search String,
* -1 if no match or null string input
* @since 2.5
*/
public static int indexOfIgnoreCase(final String str, final String searchStr, int startPos) {
if (str == null || searchStr == null) {
return StringUtils.INDEX_NOT_FOUND;
}
if (startPos < 0) {
startPos = 0;
}
int endLimit = str.length() - searchStr.length() + 1;
if (startPos > endLimit) {
return StringUtils.INDEX_NOT_FOUND;
}
if (searchStr.length() == 0) {
return startPos;
}
for (int i = startPos; i < endLimit; i++) {
if (str.regionMatches(true, i, searchStr, 0, searchStr.length())) {
return i;
}
}
return StringUtils.INDEX_NOT_FOUND;
}
// LastIndexOf
//-----------------------------------------------------------------------
/**
* Finds the last index within a String, handling null.
* This method uses {@link String#lastIndexOf(int)}.
*
* A null or empty ("") String will return -1.
*
*
* StringUtils.lastIndexOf(null, *) = -1
* StringUtils.lastIndexOf("", *) = -1
* StringUtils.lastIndexOf("aabaabaa", 'a') = 7
* StringUtils.lastIndexOf("aabaabaa", 'b') = 5
*
*
* @param str the String to check, may be null
* @param searchChar the character to find
* @return the last index of the search character,
* -1 if no match or null string input
* @since 2.0
*/
public static int lastIndexOf(final String str, final char searchChar) {
if (StringUtils.isEmpty(str)) {
return StringUtils.INDEX_NOT_FOUND;
}
return str.lastIndexOf(searchChar);
}
/**
* Finds the last index within a String from a start position,
* handling null.
* This method uses {@link String#lastIndexOf(int, int)}.
*
* A null or empty ("") String will return -1.
* A negative start position returns -1.
* A start position greater than the string length searches the whole string.
*
*
* StringUtils.lastIndexOf(null, *, *) = -1
* StringUtils.lastIndexOf("", *, *) = -1
* StringUtils.lastIndexOf("aabaabaa", 'b', 8) = 5
* StringUtils.lastIndexOf("aabaabaa", 'b', 4) = 2
* StringUtils.lastIndexOf("aabaabaa", 'b', 0) = -1
* StringUtils.lastIndexOf("aabaabaa", 'b', 9) = 5
* StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1
* StringUtils.lastIndexOf("aabaabaa", 'a', 0) = 0
*
*
* @param str the String 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 null string input
* @since 2.0
*/
public static int lastIndexOf(final String str, final char searchChar, final int startPos) {
if (StringUtils.isEmpty(str)) {
return StringUtils.INDEX_NOT_FOUND;
}
return str.lastIndexOf(searchChar, startPos);
}
/**
* Finds the last index within a String, handling null.
* This method uses {@link String#lastIndexOf(String)}.
*
* A null String will return -1.
*
*
* StringUtils.lastIndexOf(null, *) = -1
* StringUtils.lastIndexOf(*, null) = -1
* StringUtils.lastIndexOf("", "") = 0
* StringUtils.lastIndexOf("aabaabaa", "a") = 7
* StringUtils.lastIndexOf("aabaabaa", "b") = 5
* StringUtils.lastIndexOf("aabaabaa", "ab") = 4
* StringUtils.lastIndexOf("aabaabaa", "") = 8
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @return the last index of the search String,
* -1 if no match or null string input
* @since 2.0
*/
public static int lastIndexOf(final String str, final String searchStr) {
if (str == null || searchStr == null) {
return StringUtils.INDEX_NOT_FOUND;
}
return str.lastIndexOf(searchStr);
}
/**
* Finds the n-th last index within a String, handling null.
* This method uses {@link String#lastIndexOf(String)}.
*
* A null String will return -1.
*
*
* StringUtils.lastOrdinalIndexOf(null, *, *) = -1
* StringUtils.lastOrdinalIndexOf(*, null, *) = -1
* StringUtils.lastOrdinalIndexOf("", "", *) = 0
* StringUtils.lastOrdinalIndexOf("aabaabaa", "a", 1) = 7
* StringUtils.lastOrdinalIndexOf("aabaabaa", "a", 2) = 6
* StringUtils.lastOrdinalIndexOf("aabaabaa", "b", 1) = 5
* StringUtils.lastOrdinalIndexOf("aabaabaa", "b", 2) = 2
* StringUtils.lastOrdinalIndexOf("aabaabaa", "ab", 1) = 4
* StringUtils.lastOrdinalIndexOf("aabaabaa", "ab", 2) = 1
* StringUtils.lastOrdinalIndexOf("aabaabaa", "", 1) = 8
* StringUtils.lastOrdinalIndexOf("aabaabaa", "", 2) = 8
*
*
* Note that 'tail(String str, int n)' may be implemented as:
*
*
* str.substring(lastOrdinalIndexOf(str, "\n", n) + 1)
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @param ordinal the n-th last searchStr to find
* @return the n-th last index of the search String,
* -1 (INDEX_NOT_FOUND) if no match or null string input
* @since 2.5
*/
public static int lastOrdinalIndexOf(final String str, final String searchStr, final int ordinal) {
return StringUtils.ordinalIndexOf(str, searchStr, ordinal, true);
}
/**
* Finds the first index within a String, handling null.
* This method uses {@link String#lastIndexOf(String, int)}.
*
* A null String will return -1.
* A negative start position returns -1.
* An empty ("") search String always matches unless the start position is negative.
* A start position greater than the string length searches the whole string.
*
*
* StringUtils.lastIndexOf(null, *, *) = -1
* StringUtils.lastIndexOf(*, null, *) = -1
* StringUtils.lastIndexOf("aabaabaa", "a", 8) = 7
* StringUtils.lastIndexOf("aabaabaa", "b", 8) = 5
* StringUtils.lastIndexOf("aabaabaa", "ab", 8) = 4
* StringUtils.lastIndexOf("aabaabaa", "b", 9) = 5
* StringUtils.lastIndexOf("aabaabaa", "b", -1) = -1
* StringUtils.lastIndexOf("aabaabaa", "a", 0) = 0
* StringUtils.lastIndexOf("aabaabaa", "b", 0) = -1
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @param startPos the start position, negative treated as zero
* @return the first index of the search String,
* -1 if no match or null string input
* @since 2.0
*/
public static int lastIndexOf(final String str, final String searchStr, final int startPos) {
if (str == null || searchStr == null) {
return StringUtils.INDEX_NOT_FOUND;
}
return str.lastIndexOf(searchStr, startPos);
}
/**
* Case in-sensitive find of the last index within a String.
*
* A null String will return -1.
* A negative start position returns -1.
* An empty ("") search String always matches unless the start position is negative.
* A start position greater than the string length searches the whole string.
*
*
* StringUtils.lastIndexOfIgnoreCase(null, *) = -1
* StringUtils.lastIndexOfIgnoreCase(*, null) = -1
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A") = 7
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B") = 5
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "AB") = 4
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @return the first index of the search String,
* -1 if no match or null string input
* @since 2.5
*/
public static int lastIndexOfIgnoreCase(final String str, final String searchStr) {
if (str == null || searchStr == null) {
return StringUtils.INDEX_NOT_FOUND;
}
return StringUtils.lastIndexOfIgnoreCase(str, searchStr, str.length());
}
/**
* Case in-sensitive find of the last index within a String
* from the specified position.
*
* A null String will return -1.
* A negative start position returns -1.
* An empty ("") search String always matches unless the start position is negative.
* A start position greater than the string length searches the whole string.
*
*
* StringUtils.lastIndexOfIgnoreCase(null, *, *) = -1
* StringUtils.lastIndexOfIgnoreCase(*, null, *) = -1
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A", 8) = 7
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 8) = 5
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "AB", 8) = 4
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 9) = 5
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", -1) = -1
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A", 0) = 0
* StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B", 0) = -1
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @param startPos the start position
* @return the first index of the search String,
* -1 if no match or null string input
* @since 2.5
*/
public static int lastIndexOfIgnoreCase(final String str, final String searchStr, int startPos) {
if (str == null || searchStr == null) {
return StringUtils.INDEX_NOT_FOUND;
}
if (startPos > str.length() - searchStr.length()) {
startPos = str.length() - searchStr.length();
}
if (startPos < 0) {
return StringUtils.INDEX_NOT_FOUND;
}
if (searchStr.length() == 0) {
return startPos;
}
for (int i = startPos; i >= 0; i--) {
if (str.regionMatches(true, i, searchStr, 0, searchStr.length())) {
return i;
}
}
return StringUtils.INDEX_NOT_FOUND;
}
// Contains
//-----------------------------------------------------------------------
/**
* Checks if String contains a search character, handling null.
* This method uses {@link String#indexOf(int)}.
*
* A null or empty ("") String will return false.
*
*
* StringUtils.contains(null, *) = false
* StringUtils.contains("", *) = false
* StringUtils.contains("abc", 'a') = true
* StringUtils.contains("abc", 'z') = false
*
*
* @param str the String to check, may be null
* @param searchChar the character to find
* @return true if the String contains the search character,
* false if not or null string input
* @since 2.0
*/
public static boolean contains(final String str, final char searchChar) {
if (StringUtils.isEmpty(str)) {
return false;
}
return str.indexOf(searchChar) >= 0;
}
/**
* Checks if String contains a search String, handling null.
* This method uses {@link String#indexOf(String)}.
*
* A null String will return false.
*
*
* StringUtils.contains(null, *) = false
* StringUtils.contains(*, null) = false
* StringUtils.contains("", "") = true
* StringUtils.contains("abc", "") = true
* StringUtils.contains("abc", "a") = true
* StringUtils.contains("abc", "z") = false
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @return true if the String contains the search String,
* false if not or null string input
* @since 2.0
*/
public static boolean contains(final String str, final String searchStr) {
if (str == null || searchStr == null) {
return false;
}
return str.indexOf(searchStr) >= 0;
}
/**
* Checks if String contains a search String irrespective of case,
* handling null. Case-insensitivity is defined as by
* {@link String#equalsIgnoreCase(String)}.
*
*
A null String will return false.
*
*
* StringUtils.contains(null, *) = false
* StringUtils.contains(*, null) = false
* StringUtils.contains("", "") = true
* StringUtils.contains("abc", "") = true
* StringUtils.contains("abc", "a") = true
* StringUtils.contains("abc", "z") = false
* StringUtils.contains("abc", "A") = true
* StringUtils.contains("abc", "Z") = false
*
*
* @param str the String to check, may be null
* @param searchStr the String to find, may be null
* @return true if the String contains the search String irrespective of
* case or false if not or null string input
*/
public static boolean containsIgnoreCase(final String str, final String searchStr) {
if (str == null || searchStr == null) {
return false;
}
int len = searchStr.length();
int max = str.length() - len;
for (int i = 0; i <= max; i++) {
if (str.regionMatches(true, i, searchStr, 0, len)) {
return true;
}
}
return false;
}
// IndexOfAny chars
//-----------------------------------------------------------------------
/**
* Search a String to find the first index of any
* character in the given set of characters.
*
* A null String will return -1.
* A null or zero length search array will return -1.
*
*
* StringUtils.indexOfAny(null, *) = -1
* StringUtils.indexOfAny("", *) = -1
* StringUtils.indexOfAny(*, null) = -1
* StringUtils.indexOfAny(*, []) = -1
* StringUtils.indexOfAny("zzabyycdxx",['z','a']) = 0
* StringUtils.indexOfAny("zzabyycdxx",['b','y']) = 3
* StringUtils.indexOfAny("aba", ['z']) = -1
*
*
* @param str the String 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
*/
public static int indexOfAny(final String str, final char[] searchChars) {
if (StringUtils.isEmpty(str) || ArrayUtils.isEmpty(searchChars)) {
return StringUtils.INDEX_NOT_FOUND;
}
int csLen = str.length();
int csLast = csLen - 1;
int searchLen = searchChars.length;
int searchLast = searchLen - 1;
for (int i = 0; i < csLen; i++) {
char ch = str.charAt(i);
for (int j = 0; j < searchLen; j++) {
if (searchChars[j] == ch) {
if (i < csLast && j < searchLast && CharUtils.isHighSurrogate(ch)) {
// ch is a supplementary character
if (searchChars[j + 1] == str.charAt(i + 1)) {
return i;
}
} else {
return i;
}
}
}
}
return StringUtils.INDEX_NOT_FOUND;
}
/**
* Search a String to find the first index of any
* character in the given set of characters.
*
* A null String will return -1.
* A null search string will return -1.
*
*
* StringUtils.indexOfAny(null, *) = -1
* StringUtils.indexOfAny("", *) = -1
* StringUtils.indexOfAny(*, null) = -1
* StringUtils.indexOfAny(*, "") = -1
* StringUtils.indexOfAny("zzabyycdxx", "za") = 0
* StringUtils.indexOfAny("zzabyycdxx", "by") = 3
* StringUtils.indexOfAny("aba","z") = -1
*
*
* @param str the String 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
*/
public static int indexOfAny(final String str, final String searchChars) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(searchChars)) {
return StringUtils.INDEX_NOT_FOUND;
}
return StringUtils.indexOfAny(str, searchChars.toCharArray());
}
// ContainsAny
//-----------------------------------------------------------------------
/**
* Checks if the String contains any character in the given
* set of characters.
*
* A null String will return false.
* A null or zero length search array will return false.
*
*
* StringUtils.containsAny(null, *) = false
* StringUtils.containsAny("", *) = false
* StringUtils.containsAny(*, null) = false
* StringUtils.containsAny(*, []) = false
* StringUtils.containsAny("zzabyycdxx",['z','a']) = true
* StringUtils.containsAny("zzabyycdxx",['b','y']) = true
* StringUtils.containsAny("aba", ['z']) = false
*
*
* @param str the String to check, may be null
* @param searchChars the chars to search for, may be null
* @return the true if any of the chars are found,
* false if no match or null input
* @since 2.4
*/
public static boolean containsAny(final String str, final char[] searchChars) {
if (StringUtils.isEmpty(str) || ArrayUtils.isEmpty(searchChars)) {
return false;
}
int csLength = str.length();
int searchLength = searchChars.length;
int csLast = csLength - 1;
int searchLast = searchLength - 1;
for (int i = 0; i < csLength; i++) {
char ch = str.charAt(i);
for (int j = 0; j < searchLength; j++) {
if (searchChars[j] == ch) {
if (CharUtils.isHighSurrogate(ch)) {
if (j == searchLast) {
// missing low surrogate, fine, like String.indexOf(String)
return true;
}
if (i < csLast && searchChars[j + 1] == str.charAt(i + 1)) {
return true;
}
} else {
// ch is in the Basic Multilingual Plane
return true;
}
}
}
}
return false;
}
/**
*
* Checks if the String contains any character in the given set of characters.
*
*
*
* A null String will return false. A null search string will return
* false.
*
*
*
* StringUtils.containsAny(null, *) = false
* StringUtils.containsAny("", *) = false
* StringUtils.containsAny(*, null) = false
* StringUtils.containsAny(*, "") = false
* StringUtils.containsAny("zzabyycdxx", "za") = true
* StringUtils.containsAny("zzabyycdxx", "by") = true
* StringUtils.containsAny("aba","z") = false
*
*
* @param str
* the String to check, may be null
* @param searchChars
* the chars to search for, may be null
* @return the true if any of the chars are found, false if no match or null input
* @since 2.4
*/
public static boolean containsAny(final String str, final String searchChars) {
if (searchChars == null) {
return false;
}
return StringUtils.containsAny(str, searchChars.toCharArray());
}
// IndexOfAnyBut chars
//-----------------------------------------------------------------------
/**
* Search a String to find the first index of any
* character not in the given set of characters.
*
* A null String will return -1.
* A null or zero length search array will return -1.
*
*
* StringUtils.indexOfAnyBut(null, *) = -1
* StringUtils.indexOfAnyBut("", *) = -1
* StringUtils.indexOfAnyBut(*, null) = -1
* StringUtils.indexOfAnyBut(*, []) = -1
* StringUtils.indexOfAnyBut("zzabyycdxx", new char[] {'z', 'a'} ) = 3
* StringUtils.indexOfAnyBut("aba", new char[] {'z'} ) = 0
* StringUtils.indexOfAnyBut("aba", new char[] {'a', 'b'} ) = -1
*
*
* @param str the String 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
*/
public static int indexOfAnyBut(final String str, final char[] searchChars) {
if (StringUtils.isEmpty(str) || ArrayUtils.isEmpty(searchChars)) {
return StringUtils.INDEX_NOT_FOUND;
}
int csLen = str.length();
int csLast = csLen - 1;
int searchLen = searchChars.length;
int searchLast = searchLen - 1;
outer:
for (int i = 0; i < csLen; i++) {
char ch = str.charAt(i);
for (int j = 0; j < searchLen; j++) {
if (searchChars[j] == ch) {
if (i < csLast && j < searchLast && CharUtils.isHighSurrogate(ch)) {
if (searchChars[j + 1] == str.charAt(i + 1)) {
continue outer;
}
} else {
continue outer;
}
}
}
return i;
}
return StringUtils.INDEX_NOT_FOUND;
}
/**
* Search a String to find the first index of any
* character not in the given set of characters.
*
* A null String will return -1.
* A null or empty 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", "") = -1
* StringUtils.indexOfAnyBut("aba","ab") = -1
*
*
* @param str the String 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
*/
public static int indexOfAnyBut(final String str, final String searchChars) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(searchChars)) {
return StringUtils.INDEX_NOT_FOUND;
}
int strLen = str.length();
for (int i = 0; i < strLen; i++) {
char ch = str.charAt(i);
boolean chFound = searchChars.indexOf(ch) >= 0;
if (i + 1 < strLen && CharUtils.isHighSurrogate(ch)) {
char ch2 = str.charAt(i + 1);
if (chFound && searchChars.indexOf(ch2) < 0) {
return i;
}
} else {
if (!chFound) {
return i;
}
}
}
return StringUtils.INDEX_NOT_FOUND;
}
// ContainsOnly
//-----------------------------------------------------------------------
/**
* Checks if the String contains only certain characters.
*
* A null String will return false.
* A null valid character array will return false.
* An empty String (length()=0) always returns true.
*
*
* StringUtils.containsOnly(null, *) = false
* StringUtils.containsOnly(*, null) = false
* StringUtils.containsOnly("", *) = true
* StringUtils.containsOnly("ab", '') = false
* StringUtils.containsOnly("abab", 'abc') = true
* StringUtils.containsOnly("ab1", 'abc') = false
* StringUtils.containsOnly("abz", 'abc') = false
*
*
* @param str 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
*/
public static boolean containsOnly(final String str, final char[] valid) {
// All these pre-checks are to maintain API with an older version
if (valid == null || str == null) {
return false;
}
if (str.length() == 0) {
return true;
}
if (valid.length == 0) {
return false;
}
return StringUtils.indexOfAnyBut(str, valid) == StringUtils.INDEX_NOT_FOUND;
}
/**
* Checks if the String contains only certain characters.
*
* A null String will return false.
* A null valid character String will return false.
* An empty String (length()=0) always returns true.
*
*
* StringUtils.containsOnly(null, *) = false
* StringUtils.containsOnly(*, null) = false
* StringUtils.containsOnly("", *) = true
* StringUtils.containsOnly("ab", "") = false
* StringUtils.containsOnly("abab", "abc") = true
* StringUtils.containsOnly("ab1", "abc") = false
* StringUtils.containsOnly("abz", "abc") = false
*
*
* @param str the String 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
*/
public static boolean containsOnly(final String str, final String validChars) {
if (str == null || validChars == null) {
return false;
}
return StringUtils.containsOnly(str, validChars.toCharArray());
}
// ContainsNone
//-----------------------------------------------------------------------
/**
* Checks that the String does not contain certain characters.
*
* A null String will return true.
* A null invalid character array will return true.
* An empty String (length()=0) 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
*
*
* @param str the String 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
*/
public static boolean containsNone(final String str, final char[] searchChars) {
if (str == null || searchChars == null) {
return true;
}
int csLen = str.length();
int csLast = csLen - 1;
int searchLen = searchChars.length;
int searchLast = searchLen - 1;
for (int i = 0; i < csLen; i++) {
char ch = str.charAt(i);
for (int j = 0; j < searchLen; j++) {
if (searchChars[j] == ch) {
if (CharUtils.isHighSurrogate(ch)) {
if (j == searchLast) {
// missing low surrogate, fine, like String.indexOf(String)
return false;
}
if (i < csLast && searchChars[j + 1] == str.charAt(i + 1)) {
return false;
}
} else {
// ch is in the Basic Multilingual Plane
return false;
}
}
}
}
return true;
}
/**
* Checks that the String does not contain certain characters.
*
* A null String will return true.
* A null invalid character array will return true.
* An empty String ("") always returns true.
*
*
* StringUtils.containsNone(null, *) = true
* StringUtils.containsNone(*, null) = true
* StringUtils.containsNone("", *) = true
* StringUtils.containsNone("ab", "") = true
* StringUtils.containsNone("abab", "xyz") = true
* StringUtils.containsNone("ab1", "xyz") = true
* StringUtils.containsNone("abz", "xyz") = false
*
*
* @param str the String 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
*/
public static boolean containsNone(final String str, final String invalidChars) {
if (str == null || invalidChars == null) {
return true;
}
return StringUtils.containsNone(str, invalidChars.toCharArray());
}
// IndexOfAny strings
//-----------------------------------------------------------------------
/**
* Find the first index of any of a set of potential substrings.
*
* A null String will return -1.
* A null or zero length search array will return -1.
* A null search array entry will be ignored, but a search
* array containing "" will return 0 if str is not
* null. This method uses {@link String#indexOf(String)}.
*
*
* StringUtils.indexOfAny(null, *) = -1
* StringUtils.indexOfAny(*, null) = -1
* StringUtils.indexOfAny(*, []) = -1
* StringUtils.indexOfAny("zzabyycdxx", ["ab","cd"]) = 2
* StringUtils.indexOfAny("zzabyycdxx", ["cd","ab"]) = 2
* StringUtils.indexOfAny("zzabyycdxx", ["mn","op"]) = -1
* StringUtils.indexOfAny("zzabyycdxx", ["zab","aby"]) = 1
* StringUtils.indexOfAny("zzabyycdxx", [""]) = 0
* StringUtils.indexOfAny("", [""]) = 0
* StringUtils.indexOfAny("", ["a"]) = -1
*
*
* @param str the String to check, may be null
* @param searchStrs the Strings to search for, may be null
* @return the first index of any of the searchStrs in str, -1 if no match
*/
public static int indexOfAny(final String str, final String[] searchStrs) {
if (str == null || searchStrs == null) {
return StringUtils.INDEX_NOT_FOUND;
}
int sz = searchStrs.length;
// String's can't have a MAX_VALUEth index.
int ret = Integer.MAX_VALUE;
int tmp = 0;
for (int i = 0; i < sz; i++) {
String search = searchStrs[i];
if (search == null) {
continue;
}
tmp = str.indexOf(search);
if (tmp == StringUtils.INDEX_NOT_FOUND) {
continue;
}
if (tmp < ret) {
ret = tmp;
}
}
return ret == Integer.MAX_VALUE ? StringUtils.INDEX_NOT_FOUND : ret;
}
/**
* Find the latest index of any of a set of potential substrings.
*
* A null String will return -1.
* A null search array will return -1.
* A null or zero length search array entry will be ignored,
* but a search array containing "" will return the length of str
* if str is not null. This method uses {@link String#indexOf(String)}
*
*
* StringUtils.lastIndexOfAny(null, *) = -1
* StringUtils.lastIndexOfAny(*, null) = -1
* StringUtils.lastIndexOfAny(*, []) = -1
* StringUtils.lastIndexOfAny(*, [null]) = -1
* StringUtils.lastIndexOfAny("zzabyycdxx", ["ab","cd"]) = 6
* StringUtils.lastIndexOfAny("zzabyycdxx", ["cd","ab"]) = 6
* StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1
* StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1
* StringUtils.lastIndexOfAny("zzabyycdxx", ["mn",""]) = 10
*
*
* @param str the String to check, may be null
* @param searchStrs the Strings to search for, may be null
* @return the last index of any of the Strings, -1 if no match
*/
public static int lastIndexOfAny(final String str, final String[] searchStrs) {
if (str == null || searchStrs == null) {
return StringUtils.INDEX_NOT_FOUND;
}
int sz = searchStrs.length;
int ret = StringUtils.INDEX_NOT_FOUND;
int tmp = 0;
for (int i = 0; i < sz; i++) {
String search = searchStrs[i];
if (search == null) {
continue;
}
tmp = str.lastIndexOf(search);
if (tmp > ret) {
ret = tmp;
}
}
return ret;
}
// Substring
//-----------------------------------------------------------------------
/**
* Gets a substring from the specified String avoiding exceptions.
*
* A negative start position can be used to start n
* characters from the end of the String.
*
* A null String will return null.
* An empty ("") String will return "".
*
*
* StringUtils.substring(null, *) = null
* StringUtils.substring("", *) = ""
* StringUtils.substring("abc", 0) = "abc"
* StringUtils.substring("abc", 2) = "c"
* StringUtils.substring("abc", 4) = ""
* StringUtils.substring("abc", -2) = "bc"
* StringUtils.substring("abc", -4) = "abc"
*
*
* @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, null if null String input
*/
public static String substring(final String str, int start) {
if (str == null) {
return null;
}
// handle negatives, which means last n characters
if (start < 0) {
start = str.length() + start; // remember start is negative
}
if (start < 0) {
start = 0;
}
if (start > str.length()) {
return StringUtils.EMPTY;
}
return str.substring(start);
}
/**
* Gets a substring from the specified String avoiding exceptions.
*
* A negative start position can be used to start/end n
* characters from the end of the String.
*
* The returned substring starts with the character in the start
* position and ends before the end position. All position counting is
* zero-based -- i.e., to start at the beginning of the string use
* start = 0. Negative start and end positions can be used to
* specify offsets relative to the end of the String.
*
* If start is not strictly to the left of end, ""
* is returned.
*
*
* StringUtils.substring(null, *, *) = null
* StringUtils.substring("", * , *) = "";
* StringUtils.substring("abc", 0, 2) = "ab"
* StringUtils.substring("abc", 2, 0) = ""
* StringUtils.substring("abc", 2, 4) = "c"
* StringUtils.substring("abc", 4, 6) = ""
* StringUtils.substring("abc", 2, 2) = ""
* StringUtils.substring("abc", -2, -1) = "b"
* StringUtils.substring("abc", -4, 2) = "ab"
*
*
* @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 to end at (exclusive), negative means
* count back from the end of the String by this many characters
* @return substring from start position to end positon,
* null if null String input
*/
public static String substring(final String str, int start, int end) {
if (str == null) {
return null;
}
// handle negatives
if (end < 0) {
end = str.length() + end; // remember end is negative
}
if (start < 0) {
start = str.length() + start; // remember start is negative
}
// check length next
if (end > str.length()) {
end = str.length();
}
// if start is greater than end, return ""
if (start > end) {
return StringUtils.EMPTY;
}
if (start < 0) {
start = 0;
}
if (end < 0) {
end = 0;
}
return str.substring(start, end);
}
// Left/Right/Mid
//-----------------------------------------------------------------------
/**
* Gets the leftmost len characters of a String.
*
* If len characters are not available, or the
* String is null, the String will be returned without
* an exception. An empty String is returned 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"
*
*
* @param str the String to get the leftmost characters from, may be null
* @param len the length of the required String
* @return the leftmost characters, null if null String input
*/
public static String left(final String str, final int len) {
if (str == null) {
return null;
}
if (len < 0) {
return StringUtils.EMPTY;
}
if (str.length() <= len) {
return str;
}
return str.substring(0, len);
}
/**
* Gets the rightmost len characters of a String.
*
* If len characters are not available, or the String
* is null, the String will be returned without an
* an exception. An empty String is returned 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"
*
*
* @param str the String to get the rightmost characters from, may be null
* @param len the length of the required String
* @return the rightmost characters, null if null String input
*/
public static String right(final String str, final int len) {
if (str == null) {
return null;
}
if (len < 0) {
return StringUtils.EMPTY;
}
if (str.length() <= len) {
return str;
}
return str.substring(str.length() - len);
}
/**
* Gets len characters from the middle of a String.
*
* If len characters are not available, the remainder
* of the String will be returned without an exception. If the
* String is null, null will be returned.
* An empty String is returned if len is negative or exceeds the
* length of str.
*
*
* 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"
*
*
* @param str the String to get the characters from, may be null
* @param pos the position to start from, negative treated as zero
* @param len the length of the required String
* @return the middle characters, null if null String input
*/
public static String mid(final String str, int pos, final int len) {
if (str == null) {
return null;
}
if (len < 0 || pos > str.length()) {
return StringUtils.EMPTY;
}
if (pos < 0) {
pos = 0;
}
if (str.length() <= pos + len) {
return str.substring(pos);
}
return str.substring(pos, pos + len);
}
// SubStringAfter/SubStringBefore
//-----------------------------------------------------------------------
/**
* Gets the substring before the first occurrence of a separator.
* The separator is not returned.
*
* A null string input will return null.
* An empty ("") string input will return the empty string.
* A null separator will return the input string.
*
* If nothing is found, the string input is returned.
*
*
* 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"
*
*
* @param str the String to get a substring from, may be null
* @param separator the String to search for, may be null
* @return the substring before the first occurrence of the separator,
* null if null String input
* @since 2.0
*/
public static String substringBefore(final String str, final String separator) {
if (StringUtils.isEmpty(str) || separator == null) {
return str;
}
if (separator.length() == 0) {
return StringUtils.EMPTY;
}
int pos = str.indexOf(separator);
if (pos == StringUtils.INDEX_NOT_FOUND) {
return str;
}
return str.substring(0, pos);
}
/**
* Gets the substring after the first occurrence of a separator.
* The separator is not returned.
*
* A null string input will return null.
* An empty ("") string input will return the empty string.
* A null separator will return the empty string if the
* input string is not null.
*
* If nothing is found, the empty string is returned.
*
*
* 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"
*
*
* @param str the String to get a substring from, may be null
* @param separator the String to search for, may be null
* @return the substring after the first occurrence of the separator,
* null if null String input
* @since 2.0
*/
public static String substringAfter(final String str, final String separator) {
if (StringUtils.isEmpty(str)) {
return str;
}
if (separator == null) {
return StringUtils.EMPTY;
}
int pos = str.indexOf(separator);
if (pos == StringUtils.INDEX_NOT_FOUND) {
return StringUtils.EMPTY;
}
return str.substring(pos + separator.length());
}
/**
* Gets the substring before the last occurrence of a separator.
* The separator is not returned.
*
* A null string input will return null.
* An empty ("") string input will return the empty string.
* An empty or null separator will return the input string.
*
* If nothing is found, the string input is returned.
*
*
* 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"
*
*
* @param str the String to get a substring from, may be null
* @param separator the String to search for, may be null
* @return the substring before the last occurrence of the separator,
* null if null String input
* @since 2.0
*/
public static String substringBeforeLast(final String str, final String separator) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(separator)) {
return str;
}
int pos = str.lastIndexOf(separator);
if (pos == StringUtils.INDEX_NOT_FOUND) {
return str;
}
return str.substring(0, pos);
}
/**
* Gets the substring after the last occurrence of a separator.
* The separator is not returned.
*
* A null string input will return null.
* An empty ("") string input will return the empty string.
* An empty or null separator will return the empty string if
* the input string is not null.
*
* If nothing is found, the empty string is returned.
*
*
* 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") = ""
*
*
* @param str the String to get a substring from, may be null
* @param separator the String to search for, may be null
* @return the substring after the last occurrence of the separator,
* null if null String input
* @since 2.0
*/
public static String substringAfterLast(final String str, final String separator) {
if (StringUtils.isEmpty(str)) {
return str;
}
if (StringUtils.isEmpty(separator)) {
return StringUtils.EMPTY;
}
int pos = str.lastIndexOf(separator);
if (pos == StringUtils.INDEX_NOT_FOUND || pos == str.length() - separator.length()) {
return StringUtils.EMPTY;
}
return str.substring(pos + separator.length());
}
// Substring between
//-----------------------------------------------------------------------
/**
* Gets the String that is nested in between two instances of the
* same String.
*
* A null input String returns null.
* A null tag returns null.
*
*
* StringUtils.substringBetween(null, *) = null
* StringUtils.substringBetween("", "") = ""
* StringUtils.substringBetween("", "tag") = null
* StringUtils.substringBetween("tagabctag", null) = null
* StringUtils.substringBetween("tagabctag", "") = ""
* StringUtils.substringBetween("tagabctag", "tag") = "abc"
*
*
* @param str the String containing the substring, may be null
* @param tag the String before and after the substring, may be null
* @return the substring, null if no match
* @since 2.0
*/
public static String substringBetween(final String str, final String tag) {
return StringUtils.substringBetween(str, tag, tag);
}
/**
* Gets the String that is nested in between two Strings.
* Only the first match is returned.
*
* A null input String returns null.
* A null open/close returns null (no match).
* An empty ("") open and close returns an empty string.
*
*
* StringUtils.substringBetween("wx[b]yz", "[", "]") = "b"
* StringUtils.substringBetween(null, *, *) = null
* StringUtils.substringBetween(*, null, *) = null
* StringUtils.substringBetween(*, *, null) = null
* StringUtils.substringBetween("", "", "") = ""
* StringUtils.substringBetween("", "", "]") = null
* StringUtils.substringBetween("", "[", "]") = null
* StringUtils.substringBetween("yabcz", "", "") = ""
* StringUtils.substringBetween("yabcz", "y", "z") = "abc"
* StringUtils.substringBetween("yabczyabcz", "y", "z") = "abc"
*
*
* @param str the String containing the substring, may be null
* @param open the String before the substring, may be null
* @param close the String after the substring, may be null
* @return the substring, null if no match
* @since 2.0
*/
public static String substringBetween(final String str, final String open, final String close) {
if (str == null || open == null || close == null) {
return null;
}
int start = str.indexOf(open);
if (start != StringUtils.INDEX_NOT_FOUND) {
int end = str.indexOf(close, start + open.length());
if (end != StringUtils.INDEX_NOT_FOUND) {
return str.substring(start + open.length(), end);
}
}
return null;
}
/**
* Searches a String for substrings delimited by a start and end tag,
* returning all matching substrings in an array.
*
* A null input String returns null.
* A null open/close returns null (no match).
* An empty ("") open/close returns null (no match).
*
*
* StringUtils.substringsBetween("[a][b][c]", "[", "]") = ["a","b","c"]
* StringUtils.substringsBetween(null, *, *) = null
* StringUtils.substringsBetween(*, null, *) = null
* StringUtils.substringsBetween(*, *, null) = null
* StringUtils.substringsBetween("", "[", "]") = []
*
*
* @param str the String containing the substrings, null returns null, empty returns empty
* @param open the String identifying the start of the substring, empty returns null
* @param close the String identifying the end of the substring, empty returns null
* @return a String Array of substrings, or null if no match
* @since 2.3
*/
public static String[] substringsBetween(final String str, final String open, final String close) {
if (str == null || StringUtils.isEmpty(open) || StringUtils.isEmpty(close)) {
return null;
}
int strLen = str.length();
if (strLen == 0) {
return ArrayUtils.EMPTY_STRING_ARRAY;
}
int closeLen = close.length();
int openLen = open.length();
List list = new ArrayList();
int pos = 0;
while (pos < strLen - closeLen) {
int start = str.indexOf(open, pos);
if (start < 0) {
break;
}
start += openLen;
int end = str.indexOf(close, start);
if (end < 0) {
break;
}
list.add(str.substring(start, end));
pos = end + closeLen;
}
if (list.isEmpty()) {
return null;
}
return list.toArray(new String[list.size()]);
}
// Splitting
//-----------------------------------------------------------------------
/**
* Splits the provided text into an array, using whitespace as the
* separator.
* Whitespace is defined by {@link Character#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.
*
* A null input String returns null.
*
*
* StringUtils.split(null) = null
* StringUtils.split("") = []
* StringUtils.split("abc def") = ["abc", "def"]
* StringUtils.split("abc def") = ["abc", "def"]
* StringUtils.split(" abc ") = ["abc"]
*
*
* @param str the String to parse, may be null
* @return an array of parsed Strings, null if null String input
*/
public static String[] split(final String str) {
return StringUtils.split(str, null, -1);
}
/**
* 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.
*
* A null input String returns null.
*
*
* StringUtils.split(null, *) = null
* StringUtils.split("", *) = []
* StringUtils.split("a.b.c", '.') = ["a", "b", "c"]
* StringUtils.split("a..b.c", '.') = ["a", "b", "c"]
* StringUtils.split("a:b:c", '.') = ["a:b:c"]
* StringUtils.split("a b c", ' ') = ["a", "b", "c"]
*
*
* @param str the String to parse, may be null
* @param separatorChar the character used as the delimiter
* @return an array of parsed Strings, null if null String input
* @since 2.0
*/
public static String[] split(final String str, final char separatorChar) {
return StringUtils.splitWorker(str, separatorChar, false);
}
/**
* 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.
*
* A null input String returns null.
* A null separatorChars splits on whitespace.
*
*
* StringUtils.split(null, *) = null
* StringUtils.split("", *) = []
* StringUtils.split("abc def", null) = ["abc", "def"]
* StringUtils.split("abc def", " ") = ["abc", "def"]
* StringUtils.split("abc def", " ") = ["abc", "def"]
* StringUtils.split("ab:cd:ef", ":") = ["ab", "cd", "ef"]
*
*
* @param str the String to parse, may be null
* @param separatorChars the characters used as the delimiters,
* null splits on whitespace
* @return an array of parsed Strings, null if null String input
*/
public static String[] split(final String str, final String separatorChars) {
return StringUtils.splitWorker(str, separatorChars, -1, false);
}
/**
* 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.
*
* A null input String returns null.
* A null separatorChars splits on whitespace.
*
* If more than max delimited substrings are found, the last
* returned string includes all characters after the first max - 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"]
*
*
* @param str the String to parse, may be null
* @param separatorChars the characters used as the delimiters,
* null splits on whitespace
* @param max the maximum number of elements to include in the
* array. A zero or negative value implies no limit
* @return an array of parsed Strings, null if null String input
*/
public static String[] split(final String str, final String separatorChars, final int max) {
return StringUtils.splitWorker(str, separatorChars, max, false);
}
/**
* 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.
*
* A null input String returns null.
* A null separator splits on whitespace.
*
*
* StringUtils.splitByWholeSeparator(null, *) = null
* StringUtils.splitByWholeSeparator("", *) = []
* StringUtils.splitByWholeSeparator("ab de fg", null) = ["ab", "de", "fg"]
* StringUtils.splitByWholeSeparator("ab de fg", null) = ["ab", "de", "fg"]
* StringUtils.splitByWholeSeparator("ab:cd:ef", ":") = ["ab", "cd", "ef"]
* StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]
*
*
* @param str the String to parse, may be null
* @param separator String containing the String to be used as a delimiter,
* null splits on whitespace
* @return an array of parsed Strings, null if null String was input
*/
public static String[] splitByWholeSeparator(final String str, final String separator) {
return StringUtils.splitByWholeSeparatorWorker(str, separator, -1, false);
}
/**
* Splits the provided text into an array, separator string specified.
* Returns a maximum of max substrings.
*
* The separator(s) will not be included in the returned String array.
* Adjacent separators are treated as one separator.
*
* A null input String returns null.
* A null 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:ef"]
* StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
* StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
*
*
* @param str the String to parse, may be null
* @param separator String containing the String to be used as a delimiter,
* null splits on whitespace
* @param max the maximum number of elements to include in the returned
* array. A zero or negative value implies no limit.
* @return an array of parsed Strings, null if null String was input
*/
public static String[] splitByWholeSeparator(final String str, final String separator, final int max) {
return StringUtils.splitByWholeSeparatorWorker(str, separator, max, false);
}
/**
* Splits the provided text into an array, separator string specified.
*
* 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.
*
* A null input String returns null.
* A null separator splits on whitespace.
*
*
* StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *) = null
* StringUtils.splitByWholeSeparatorPreserveAllTokens("", *) = []
* StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null) = ["ab", "de", "fg"]
* StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null) = ["ab", "", "", "de", "fg"]
* StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":") = ["ab", "cd", "ef"]
* StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]
*
*
* @param str the String to parse, may be null
* @param separator String containing the String to be used as a delimiter,
* null splits on whitespace
* @return an array of parsed Strings, null if null String was input
* @since 2.4
*/
public static String[] splitByWholeSeparatorPreserveAllTokens(final String str, final String separator) {
return StringUtils.splitByWholeSeparatorWorker(str, separator, -1, true);
}
/**
* Splits the provided text into an array, separator string specified.
* Returns a maximum of max substrings.
*
* 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.
*
* A null input String returns null.
* A null separator splits on whitespace.
*
*
* StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *, *) = null
* StringUtils.splitByWholeSeparatorPreserveAllTokens("", *, *) = []
* StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null, 0) = ["ab", "de", "fg"]
* StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null, 0) = ["ab", "", "", "de", "fg"]
* StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":", 2) = ["ab", "cd:ef"]
* StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
* StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
*
*
* @param str the String to parse, may be null
* @param separator String containing the String to be used as a delimiter,
* null splits on whitespace
* @param max the maximum number of elements to include in the returned
* array. A zero or negative value implies no limit.
* @return an array of parsed Strings, null if null String was input
* @since 2.4
*/
public static String[] splitByWholeSeparatorPreserveAllTokens(final String str, final String separator, final int max) {
return StringUtils.splitByWholeSeparatorWorker(str, separator, max, true);
}
/**
* Performs the logic for the splitByWholeSeparatorPreserveAllTokens methods.
*
* @param str the String to parse, may be null
* @param separator String containing the String to be used as a delimiter,
* null splits on whitespace
* @param max the maximum number of elements to include in the returned
* array. A zero or negative value implies no limit.
* @param preserveAllTokens if true, adjacent separators are
* treated as empty token separators; if false, adjacent
* separators are treated as one separator.
* @return an array of parsed Strings, null if null String input
* @since 2.4
*/
private static String[] splitByWholeSeparatorWorker(final String str, final String separator, final int max, final boolean preserveAllTokens) {
if (str == null) {
return null;
}
int len = str.length();
if (len == 0) {
return ArrayUtils.EMPTY_STRING_ARRAY;
}
if (separator == null || StringUtils.EMPTY.equals(separator)) {
// Split on whitespace.
return StringUtils.splitWorker(str, null, max, preserveAllTokens);
}
int separatorLength = separator.length();
ArrayList substrings = new ArrayList();
int numberOfSubstrings = 0;
int beg = 0;
int end = 0;
while (end < len) {
end = str.indexOf(separator, beg);
if (end > -1) {
if (end > beg) {
numberOfSubstrings += 1;
if (numberOfSubstrings == max) {
end = len;
substrings.add(str.substring(beg));
} else {
// The following is OK, because String.substring( beg, end ) excludes
// the character at the position 'end'.
substrings.add(str.substring(beg, end));
// Set the starting point for the next search.
// The following is equivalent to beg = end + (separatorLength - 1) + 1,
// which is the right calculation:
beg = end + separatorLength;
}
} else {
// We found a consecutive occurrence of the separator, so skip it.
if (preserveAllTokens) {
numberOfSubstrings += 1;
if (numberOfSubstrings == max) {
end = len;
substrings.add(str.substring(beg));
} else {
substrings.add(StringUtils.EMPTY);
}
}
beg = end + separatorLength;
}
} else {
// String.substring( beg ) goes from 'beg' to the end of the String.
substrings.add(str.substring(beg));
end = len;
}
}
return substrings.toArray(new String[substrings.size()]);
}
// -----------------------------------------------------------------------
/**
* 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 by {@link Character#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.
*
* A null input String returns null.
*
*
* StringUtils.splitPreserveAllTokens(null) = null
* StringUtils.splitPreserveAllTokens("") = []
* StringUtils.splitPreserveAllTokens("abc def") = ["abc", "def"]
* StringUtils.splitPreserveAllTokens("abc def") = ["abc", "", "def"]
* StringUtils.splitPreserveAllTokens(" abc ") = ["", "abc", ""]
*
*
* @param str the String to parse, may be null
* @return an array of parsed Strings, null if null String input
* @since 2.1
*/
public static String[] splitPreserveAllTokens(final String str) {
return StringUtils.splitWorker(str, null, -1, true);
}
/**
* 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.
*
* A null input String returns null.
*
*
* 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", ""]
*
*
* @param str the String to parse, may be null
* @param separatorChar the character used as the delimiter,
* null splits on whitespace
* @return an array of parsed Strings, null if null String input
* @since 2.1
*/
public static String[] splitPreserveAllTokens(final String str, final char separatorChar) {
return StringUtils.splitWorker(str, separatorChar, true);
}
/**
* Performs the logic for the split and
* splitPreserveAllTokens methods that do not return a
* maximum array length.
*
* @param str the String to parse, may be null
* @param separatorChar the separate character
* @param preserveAllTokens if true, adjacent separators are
* treated as empty token separators; if false, adjacent
* separators are treated as one separator.
* @return an array of parsed Strings, null if null String input
*/
private static String[] splitWorker(final String str, final char separatorChar, final boolean preserveAllTokens) {
// Performance tuned for 2.0 (JDK1.4)
if (str == null) {
return null;
}
int len = str.length();
if (len == 0) {
return ArrayUtils.EMPTY_STRING_ARRAY;
}
List list = new ArrayList();
int i = 0, start = 0;
boolean match = false;
boolean lastMatch = false;
while (i < len) {
if (str.charAt(i) == separatorChar) {
if (match || preserveAllTokens) {
list.add(str.substring(start, i));
match = false;
lastMatch = true;
}
start = ++i;
continue;
}
lastMatch = false;
match = true;
i++;
}
if (match || preserveAllTokens && lastMatch) {
list.add(str.substring(start, i));
}
return list.toArray(new String[list.size()]);
}
/**
* 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.
*
* A null input String returns null.
* A null 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", ""]
*
*
* @param str the String to parse, may be null
* @param separatorChars the characters used as the delimiters,
* null splits on whitespace
* @return an array of parsed Strings, null if null String input
* @since 2.1
*/
public static String[] splitPreserveAllTokens(final String str, final String separatorChars) {
return StringUtils.splitWorker(str, separatorChars, -1, true);
}
/**
* 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.
*
* A null input String returns null.
* A null separatorChars splits on whitespace.
*
* If more than max delimited substrings are found, the last
* returned string includes all characters after the first max - 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"]
*
*
* @param str the String to parse, may be null
* @param separatorChars the characters used as the delimiters,
* null splits on whitespace
* @param max the maximum number of elements to include in the
* array. A zero or negative value implies no limit
* @return an array of parsed Strings, null if null String input
* @since 2.1
*/
public static String[] splitPreserveAllTokens(final String str, final String separatorChars, final int max) {
return StringUtils.splitWorker(str, separatorChars, max, true);
}
/**
* Performs the logic for the split and
* splitPreserveAllTokens methods that return a maximum array
* length.
*
* @param str the String to parse, may be null
* @param separatorChars the separate character
* @param max the maximum number of elements to include in the
* array. A zero or negative value implies no limit.
* @param preserveAllTokens if true, adjacent separators are
* treated as empty token separators; if false, adjacent
* separators are treated as one separator.
* @return an array of parsed Strings, null if null String input
*/
private static String[] splitWorker(final String str, final String separatorChars, final int max, final boolean preserveAllTokens) {
// Performance tuned for 2.0 (JDK1.4)
// Direct code is quicker than StringTokenizer.
// Also, StringTokenizer uses isSpace() not isWhitespace()
if (str == null) {
return null;
}
int len = str.length();
if (len == 0) {
return ArrayUtils.EMPTY_STRING_ARRAY;
}
List list = new ArrayList();
int sizePlus1 = 1;
int i = 0, start = 0;
boolean match = false;
boolean lastMatch = false;
if (separatorChars == null) {
// Null separator means use whitespace
while (i < len) {
if (Character.isWhitespace(str.charAt(i))) {
if (match || preserveAllTokens) {
lastMatch = true;
if (sizePlus1++ == max) {
i = len;
lastMatch = false;
}
list.add(str.substring(start, i));
match = false;
}
start = ++i;
continue;
}
lastMatch = false;
match = true;
i++;
}
} else if (separatorChars.length() == 1) {
// Optimise 1 character case
char sep = separatorChars.charAt(0);
while (i < len) {
if (str.charAt(i) == sep) {
if (match || preserveAllTokens) {
lastMatch = true;
if (sizePlus1++ == max) {
i = len;
lastMatch = false;
}
list.add(str.substring(start, i));
match = false;
}
start = ++i;
continue;
}
lastMatch = false;
match = true;
i++;
}
} else {
// standard case
while (i < len) {
if (separatorChars.indexOf(str.charAt(i)) >= 0) {
if (match || preserveAllTokens) {
lastMatch = true;
if (sizePlus1++ == max) {
i = len;
lastMatch = false;
}
list.add(str.substring(start, i));
match = false;
}
start = ++i;
continue;
}
lastMatch = false;
match = true;
i++;
}
}
if (match || preserveAllTokens && lastMatch) {
list.add(str.substring(start, i));
}
return list.toArray(new String[list.size()]);
}
/**
* Splits a String by Character type as returned by
* java.lang.Character.getType(char). Groups of contiguous
* characters of the same type are returned as complete tokens.
*
* StringUtils.splitByCharacterType(null) = null
* StringUtils.splitByCharacterType("") = []
* StringUtils.splitByCharacterType("ab de fg") = ["ab", " ", "de", " ", "fg"]
* StringUtils.splitByCharacterType("ab de fg") = ["ab", " ", "de", " ", "fg"]
* StringUtils.splitByCharacterType("ab:cd:ef") = ["ab", ":", "cd", ":", "ef"]
* StringUtils.splitByCharacterType("number5") = ["number", "5"]
* StringUtils.splitByCharacterType("fooBar") = ["foo", "B", "ar"]
* StringUtils.splitByCharacterType("foo200Bar") = ["foo", "200", "B", "ar"]
* StringUtils.splitByCharacterType("ASFRules") = ["ASFR", "ules"]
*
* @param str the String to split, may be null
* @return an array of parsed Strings, null if null String input
* @since 2.4
*/
public static String[] splitByCharacterType(final String str) {
return StringUtils.splitByCharacterType(str, false);
}
/**
* Splits a String by Character type as returned by
* java.lang.Character.getType(char). Groups of contiguous
* characters of the same type are returned as complete tokens, with the
* following exception: the character of type
* Character.UPPERCASE_LETTER, if any, immediately
* preceding a token of type Character.LOWERCASE_LETTER
* will belong to the following token rather than to the preceding, if any,
* Character.UPPERCASE_LETTER token.
*
* StringUtils.splitByCharacterTypeCamelCase(null) = null
* StringUtils.splitByCharacterTypeCamelCase("") = []
* StringUtils.splitByCharacterTypeCamelCase("ab de fg") = ["ab", " ", "de", " ", "fg"]
* StringUtils.splitByCharacterTypeCamelCase("ab de fg") = ["ab", " ", "de", " ", "fg"]
* StringUtils.splitByCharacterTypeCamelCase("ab:cd:ef") = ["ab", ":", "cd", ":", "ef"]
* StringUtils.splitByCharacterTypeCamelCase("number5") = ["number", "5"]
* StringUtils.splitByCharacterTypeCamelCase("fooBar") = ["foo", "Bar"]
* StringUtils.splitByCharacterTypeCamelCase("foo200Bar") = ["foo", "200", "Bar"]
* StringUtils.splitByCharacterTypeCamelCase("ASFRules") = ["ASF", "Rules"]
*
* @param str the String to split, may be null
* @return an array of parsed Strings, null if null String input
* @since 2.4
*/
public static String[] splitByCharacterTypeCamelCase(final String str) {
return StringUtils.splitByCharacterType(str, true);
}
/**
* Splits a String by Character type as returned by
* java.lang.Character.getType(char). Groups of contiguous
* characters of the same type are returned as complete tokens, with the
* following exception: if camelCase is true,
* the character of type Character.UPPERCASE_LETTER, if any,
* immediately preceding a token of type Character.LOWERCASE_LETTER
* will belong to the following token rather than to the preceding, if any,
* Character.UPPERCASE_LETTER token.
* @param str the String to split, may be null
* @param camelCase whether to use so-called "camel-case" for letter types
* @return an array of parsed Strings, null if null String input
* @since 2.4
*/
private static String[] splitByCharacterType(final String str, final boolean camelCase) {
if (str == null) {
return null;
}
if (str.length() == 0) {
return ArrayUtils.EMPTY_STRING_ARRAY;
}
char[] c = str.toCharArray();
List list = new ArrayList();
int tokenStart = 0;
int currentType = Character.getType(c[tokenStart]);
for (int pos = tokenStart + 1; pos < c.length; pos++) {
int type = Character.getType(c[pos]);
if (type == currentType) {
continue;
}
if (camelCase && type == Character.LOWERCASE_LETTER && currentType == Character.UPPERCASE_LETTER) {
int newTokenStart = pos - 1;
if (newTokenStart != tokenStart) {
list.add(new String(c, tokenStart, newTokenStart - tokenStart));
tokenStart = newTokenStart;
}
} else {
list.add(new String(c, tokenStart, pos - tokenStart));
tokenStart = pos;
}
currentType = type;
}
list.add(new String(c, tokenStart, c.length - tokenStart));
return list.toArray(new String[list.size()]);
}
// Joining
//-----------------------------------------------------------------------
/**
* 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"
*
*
* @param array the array of values to join together, may be null
* @return the joined String, null if null array input
* @since 2.0
*/
public static String join(final Object[] array) {
return StringUtils.join(array, null);
}
/**
* 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"
*
*
* @param array the array of values to join together, may be null
* @param separator the separator character to use
* @return the joined String, null if null array input
* @since 2.0
*/
public static String join(final Object[] array, final char separator) {
if (array == null) {
return null;
}
return StringUtils.join(array, separator, 0, array.length);
}
/**
* 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"
*
*
* @param array the array of values to join together, may be null
* @param separator the separator character to use
* @param startIndex the first index to start joining from. It is
* an error to pass in an end index past the end of the array
* @param endIndex the index to stop joining from (exclusive). It is
* an error to pass in an end index past the end of the array
* @return the joined String, null if null array input
* @since 2.0
*/
public static String join(final Object[] array, final char separator, final int startIndex, final int endIndex) {
if (array == null) {
return null;
}
int bufSize = endIndex - startIndex;
if (bufSize <= 0) {
return StringUtils.EMPTY;
}
bufSize *= (array[startIndex] == null ? 16 : array[startIndex].toString().length()) + 1;
StringBuilder buf = new StringBuilder(bufSize);
for (int i = startIndex; i < endIndex; i++) {
if (i > startIndex) {
buf.append(separator);
}
if (array[i] != null) {
buf.append(array[i]);
}
}
return buf.toString();
}
/**
* Joins the elements of the provided array into a single String
* containing the provided list of elements.
*
* No delimiter is added before or after the list.
* A null separator is the same as an empty String ("").
* Null objects or empty strings within the array are represented by
* empty strings.
*
*
* StringUtils.join(null, *) = null
* StringUtils.join([], *) = ""
* StringUtils.join([null], *) = ""
* StringUtils.join(["a", "b", "c"], "--") = "a--b--c"
* StringUtils.join(["a", "b", "c"], null) = "abc"
* StringUtils.join(["a", "b", "c"], "") = "abc"
* StringUtils.join([null, "", "a"], ',') = ",,a"
*
*
* @param array the array of values to join together, may be null
* @param separator the separator character to use, null treated as ""
* @return the joined String, null if null array input
*/
public static String join(final Object[] array, final String separator) {
if (array == null) {
return null;
}
return StringUtils.join(array, separator, 0, array.length);
}
/**
* Joins the elements of the provided array into a single String
* containing the provided list of elements.
*
* No delimiter is added before or after the list.
* A null separator is the same as an empty String ("").
* Null objects or empty strings within the array are represented by
* empty strings.
*
*
* StringUtils.join(null, *) = null
* StringUtils.join([], *) = ""
* StringUtils.join([null], *) = ""
* StringUtils.join(["a", "b", "c"], "--") = "a--b--c"
* StringUtils.join(["a", "b", "c"], null) = "abc"
* StringUtils.join(["a", "b", "c"], "") = "abc"
* StringUtils.join([null, "", "a"], ',') = ",,a"
*
*
* @param array the array of values to join together, may be null
* @param separator the separator character to use, null treated as ""
* @param startIndex the first index to start joining from. It is
* an error to pass in an end index past the end of the array
* @param endIndex the index to stop joining from (exclusive). It is
* an error to pass in an end index past the end of the array
* @return the joined String, null if null array input
*/
public static String join(final Object[] array, String separator, final int startIndex, final int endIndex) {
if (array == null) {
return null;
}
if (separator == null) {
separator = StringUtils.EMPTY;
}
// endIndex - startIndex > 0: Len = NofStrings *(len(firstString) + len(separator))
// (Assuming that all Strings are roughly equally long)
int bufSize = endIndex - startIndex;
if (bufSize <= 0) {
return StringUtils.EMPTY;
}
bufSize *= (array[startIndex] == null ? 16 : array[startIndex].toString().length()) + separator.length();
StringBuilder buf = new StringBuilder(bufSize);
for (int i = startIndex; i < endIndex; i++) {
if (i > startIndex) {
buf.append(separator);
}
if (array[i] != null) {
buf.append(array[i]);
}
}
return buf.toString();
}
// Delete
//-----------------------------------------------------------------------
/**
* Deletes all whitespaces from a String as defined by
* {@link Character#isWhitespace(char)}.
*
*
* StringUtils.deleteWhitespace(null) = null
* StringUtils.deleteWhitespace("") = ""
* StringUtils.deleteWhitespace("abc") = "abc"
* StringUtils.deleteWhitespace(" ab c ") = "abc"
*
*
* @param str the String to delete whitespace from, may be null
* @return the String without whitespaces, null if null String input
*/
public static String deleteWhitespace(final String str) {
if (StringUtils.isEmpty(str)) {
return str;
}
int sz = str.length();
char[] chs = new char[sz];
int count = 0;
for (int i = 0; i < sz; i++) {
if (!Character.isWhitespace(str.charAt(i))) {
chs[count++] = str.charAt(i);
}
}
if (count == sz) {
return str;
}
return new String(chs, 0, count);
}
// Remove
//-----------------------------------------------------------------------
/**
* Removes a substring only if it is at the begining of a source string,
* otherwise returns the source string.
*
* A null source string will return null.
* An empty ("") source string will return the empty string.
* A null 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"
*
*
* @param str the source String to search, may be null
* @param remove the String to search for and remove, may be null
* @return the substring with the string removed if found,
* null if null String input
* @since 2.1
*/
public static String removeStart(final String str, final String remove) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(remove)) {
return str;
}
if (str.startsWith(remove)) {
return str.substring(remove.length());
}
return str;
}
/**
* Case insensitive removal of a substring if it is at the begining of a source string,
* otherwise returns the source string.
*
* A null source string will return null.
* An empty ("") source string will return the empty string.
* A null search string will return the source string.
*
*
* StringUtils.removeStartIgnoreCase(null, *) = null
* StringUtils.removeStartIgnoreCase("", *) = ""
* StringUtils.removeStartIgnoreCase(*, null) = *
* StringUtils.removeStartIgnoreCase("www.domain.com", "www.") = "domain.com"
* StringUtils.removeStartIgnoreCase("www.domain.com", "WWW.") = "domain.com"
* StringUtils.removeStartIgnoreCase("domain.com", "www.") = "domain.com"
* StringUtils.removeStartIgnoreCase("www.domain.com", "domain") = "www.domain.com"
* StringUtils.removeStartIgnoreCase("abc", "") = "abc"
*
*
* @param str the source String to search, may be null
* @param remove the String to search for (case insensitive) and remove, may be null
* @return the substring with the string removed if found,
* null if null String input
* @since 2.4
*/
public static String removeStartIgnoreCase(final String str, final String remove) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(remove)) {
return str;
}
if (StringUtils.startsWithIgnoreCase(str, remove)) {
return str.substring(remove.length());
}
return str;
}
/**
* Removes a substring only if it is at the end of a source string,
* otherwise returns the source string.
*
* A null source string will return null.
* An empty ("") source string will return the empty string.
* A null search string will return the source string.
*
*
* StringUtils.removeEnd(null, *) = null
* StringUtils.removeEnd("", *) = ""
* StringUtils.removeEnd(*, null) = *
* StringUtils.removeEnd("www.domain.com", ".com.") = "www.domain.com"
* StringUtils.removeEnd("www.domain.com", ".com") = "www.domain"
* StringUtils.removeEnd("www.domain.com", "domain") = "www.domain.com"
* StringUtils.removeEnd("abc", "") = "abc"
*
*
* @param str the source String to search, may be null
* @param remove the String to search for and remove, may be null
* @return the substring with the string removed if found,
* null if null String input
* @since 2.1
*/
public static String removeEnd(final String str, final String remove) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(remove)) {
return str;
}
if (str.endsWith(remove)) {
return str.substring(0, str.length() - remove.length());
}
return str;
}
/**
* Case insensitive removal of a substring if it is at the end of a source string,
* otherwise returns the source string.
*
* A null source string will return null.
* An empty ("") source string will return the empty string.
* A null search string will return the source string.
*
*
* StringUtils.removeEndIgnoreCase(null, *) = null
* StringUtils.removeEndIgnoreCase("", *) = ""
* StringUtils.removeEndIgnoreCase(*, null) = *
* StringUtils.removeEndIgnoreCase("www.domain.com", ".com.") = "www.domain.com"
* StringUtils.removeEndIgnoreCase("www.domain.com", ".com") = "www.domain"
* StringUtils.removeEndIgnoreCase("www.domain.com", "domain") = "www.domain.com"
* StringUtils.removeEndIgnoreCase("abc", "") = "abc"
* StringUtils.removeEndIgnoreCase("www.domain.com", ".COM") = "www.domain")
* StringUtils.removeEndIgnoreCase("www.domain.COM", ".com") = "www.domain")
*
*
* @param str the source String to search, may be null
* @param remove the String to search for (case insensitive) and remove, may be null
* @return the substring with the string removed if found,
* null if null String input
* @since 2.4
*/
public static String removeEndIgnoreCase(final String str, final String remove) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(remove)) {
return str;
}
if (StringUtils.endsWithIgnoreCase(str, remove)) {
return str.substring(0, str.length() - remove.length());
}
return str;
}
/**
* Removes all occurrences of a substring from within the source string.
*
* A null source string will return null.
* An empty ("") source string will return the empty string.
* A null 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"
*
*
* @param str the source String to search, may be null
* @param remove the String to search for and remove, may be null
* @return the substring with the string removed if found,
* null if null String input
* @since 2.1
*/
public static String remove(final String str, final String remove) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(remove)) {
return str;
}
return StringUtils.replace(str, remove, StringUtils.EMPTY, -1);
}
/**
* Removes all occurrences of a character from within the source string.
*
* A null source string will return null.
* 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"
*
*
* @param str the source String to search, may be null
* @param remove the char to search for and remove, may be null
* @return the substring with the char removed if found,
* null if null String input
* @since 2.1
*/
public static String remove(final String str, final char remove) {
if (StringUtils.isEmpty(str) || str.indexOf(remove) == StringUtils.INDEX_NOT_FOUND) {
return str;
}
char[] chars = str.toCharArray();
int pos = 0;
for (int i = 0; i < chars.length; i++) {
if (chars[i] != remove) {
chars[pos++] = chars[i];
}
}
return new String(chars, 0, pos);
}
// Replacing
//-----------------------------------------------------------------------
/**
* Replaces a String with another String inside a larger String, once.
*
* A null reference passed to this method is a no-op.
*
*
* StringUtils.replaceOnce(null, *, *) = null
* StringUtils.replaceOnce("", *, *) = ""
* StringUtils.replaceOnce("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"
*
*
* @see #replace(String text, String searchString, String replacement, int max)
* @param text text to search and replace in, may be null
* @param searchString the String to search for, may be null
* @param replacement the String to replace with, may be null
* @return the text with any replacements processed,
* null if null String input
*/
public static String replaceOnce(final String text, final String searchString, final String replacement) {
return StringUtils.replace(text, searchString, replacement, 1);
}
/**
* Replaces all occurrences of a String within another String.
*
* A null reference passed to this method is a no-op.
*
*
* StringUtils.replace(null, *, *) = null
* StringUtils.replace("", *, *) = ""
* StringUtils.replace("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"
*
*
* @see #replace(String text, String searchString, String replacement, int max)
* @param text text to search and replace in, may be null
* @param searchString the String to search for, may be null
* @param replacement the String to replace it with, may be null
* @return the text with any replacements processed,
* null if null String input
*/
public static String replace(final String text, final String searchString, final String replacement) {
return StringUtils.replace(text, searchString, replacement, -1);
}
/**
* Replaces a String with another String inside a larger String,
* for the first max values of the search String.
*
* A null reference passed to this method is a no-op.
*
*
* StringUtils.replace(null, *, *, *) = null
* StringUtils.replace("", *, *, *) = ""
* StringUtils.replace("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"
*
*
* @param text text to search and replace in, may be null
* @param searchString the String to search for, may be null
* @param replacement the String to replace it with, may be null
* @param max maximum number of values to replace, or -1 if no maximum
* @return the text with any replacements processed,
* null if null String input
*/
public static String replace(final String text, final String searchString, final String replacement, int max) {
if (StringUtils.isEmpty(text) || StringUtils.isEmpty(searchString) || replacement == null || max == 0) {
return text;
}
int start = 0;
int end = text.indexOf(searchString, start);
if (end == StringUtils.INDEX_NOT_FOUND) {
return text;
}
int replLength = searchString.length();
int increase = replacement.length() - replLength;
increase = increase < 0 ? 0 : increase;
increase *= max < 0 ? 16 : max > 64 ? 64 : max;
StringBuilder buf = new StringBuilder(text.length() + increase);
while (end != StringUtils.INDEX_NOT_FOUND) {
buf.append(text.substring(start, end)).append(replacement);
start = end + replLength;
if (--max == 0) {
break;
}
end = text.indexOf(searchString, start);
}
buf.append(text.substring(start));
return buf.toString();
}
/**
*
* Replaces all occurrences of Strings within another String.
*
*
*
* A null reference passed to this method is a no-op, or if
* any "search string" or "string to replace" is null, that replace will be
* ignored. This will not repeat. For repeating replaces, call the
* overloaded method.
*
*
*
* StringUtils.replaceEach(null, *, *) = null
* StringUtils.replaceEach("", *, *) = ""
* StringUtils.replaceEach("aba", null, null) = "aba"
* StringUtils.replaceEach("aba", new String[0], null) = "aba"
* StringUtils.replaceEach("aba", null, new String[0]) = "aba"
* StringUtils.replaceEach("aba", new String[]{"a"}, null) = "aba"
* StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""}) = "b"
* StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"}) = "aba"
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"}) = "wcte"
* (example of how it does not repeat)
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}) = "dcte"
*
*
* @param text
* text to search and replace in, no-op if null
* @param searchList
* the Strings to search for, no-op if null
* @param replacementList
* the Strings to replace them with, no-op if null
* @return the text with any replacements processed, null if
* null String input
* @throws IndexOutOfBoundsException
* if the lengths of the arrays are not the same (null is ok,
* and/or size 0)
* @since 2.4
*/
public static String replaceEach(final String text, final String[] searchList, final String[] replacementList) {
return StringUtils.replaceEach(text, searchList, replacementList, false, 0);
}
/**
*
* Replaces all occurrences of Strings within another String.
*
*
*
* A null reference passed to this method is a no-op, or if
* any "search string" or "string to replace" is null, that replace will be
* ignored. This will not repeat. For repeating replaces, call the
* overloaded method.
*
*
*
* StringUtils.replaceEach(null, *, *, *) = null
* StringUtils.replaceEach("", *, *, *) = ""
* StringUtils.replaceEach("aba", null, null, *) = "aba"
* StringUtils.replaceEach("aba", new String[0], null, *) = "aba"
* StringUtils.replaceEach("aba", null, new String[0], *) = "aba"
* StringUtils.replaceEach("aba", new String[]{"a"}, null, *) = "aba"
* StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""}, *) = "b"
* StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"}, *) = "aba"
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"}, *) = "wcte"
* (example of how it repeats)
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}, false) = "dcte"
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}, true) = "tcte"
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}, true) = IllegalArgumentException
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}, false) = "dcabe"
*
*
* @param text
* text to search and replace in, no-op if null
* @param searchList
* the Strings to search for, no-op if null
* @param replacementList
* the Strings to replace them with, no-op if null
* @return the text with any replacements processed, null if
* null String input
* @throws IllegalArgumentException
* if the search is repeating and there is an endless loop due
* to outputs of one being inputs to another
* @throws IndexOutOfBoundsException
* if the lengths of the arrays are not the same (null is ok,
* and/or size 0)
* @since 2.4
*/
public static String replaceEachRepeatedly(final String text, final String[] searchList, final String[] replacementList) {
// timeToLive should be 0 if not used or nothing to replace, else it's
// the length of the replace array
int timeToLive = searchList == null ? 0 : searchList.length;
return StringUtils.replaceEach(text, searchList, replacementList, true, timeToLive);
}
/**
*
* Replaces all occurrences of Strings within another String.
*
*
*
* A null reference passed to this method is a no-op, or if
* any "search string" or "string to replace" is null, that replace will be
* ignored.
*
*
*
* StringUtils.replaceEach(null, *, *, *) = null
* StringUtils.replaceEach("", *, *, *) = ""
* StringUtils.replaceEach("aba", null, null, *) = "aba"
* StringUtils.replaceEach("aba", new String[0], null, *) = "aba"
* StringUtils.replaceEach("aba", null, new String[0], *) = "aba"
* StringUtils.replaceEach("aba", new String[]{"a"}, null, *) = "aba"
* StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""}, *) = "b"
* StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"}, *) = "aba"
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"}, *) = "wcte"
* (example of how it repeats)
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}, false) = "dcte"
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}, true) = "tcte"
* StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}, *) = IllegalArgumentException
*
*
* @param text
* text to search and replace in, no-op if null
* @param searchList
* the Strings to search for, no-op if null
* @param replacementList
* the Strings to replace them with, no-op if null
* @param repeat if true, then replace repeatedly
* until there are no more possible replacements or timeToLive < 0
* @param timeToLive
* if less than 0 then there is a circular reference and endless
* loop
* @return the text with any replacements processed, null if
* null String input
* @throws IllegalArgumentException
* if the search is repeating and there is an endless loop due
* to outputs of one being inputs to another
* @throws IndexOutOfBoundsException
* if the lengths of the arrays are not the same (null is ok,
* and/or size 0)
* @since 2.4
*/
private static String replaceEach(final String text, final String[] searchList, final String[] replacementList, final boolean repeat, final int timeToLive) {
// mchyzer Performance note: This creates very few new objects (one major goal)
// let me know if there are performance requests, we can create a harness to measure
if (text == null || text.length() == 0 || searchList == null || searchList.length == 0 || replacementList == null || replacementList.length == 0) {
return text;
}
// if recursing, this shouldnt be less than 0
if (timeToLive < 0) {
throw new IllegalStateException("TimeToLive of " + timeToLive + " is less than 0: " + text);
}
int searchLength = searchList.length;
int replacementLength = replacementList.length;
// make sure lengths are ok, these need to be equal
if (searchLength != replacementLength) {
throw new IllegalArgumentException("Search and Replace array lengths don't match: " + searchLength + " vs " + replacementLength);
}
// keep track of which still have matches
boolean[] noMoreMatchesForReplIndex = new boolean[searchLength];
// index on index that the match was found
int textIndex = -1;
int replaceIndex = -1;
int tempIndex = -1;
// index of replace array that will replace the search string found
// NOTE: logic duplicated below START
for (int i = 0; i < searchLength; i++) {
if (noMoreMatchesForReplIndex[i] || searchList[i] == null || searchList[i].length() == 0 || replacementList[i] == null) {
continue;
}
tempIndex = text.indexOf(searchList[i]);
// see if we need to keep searching for this
if (tempIndex == -1) {
noMoreMatchesForReplIndex[i] = true;
} else {
if (textIndex == -1 || tempIndex < textIndex) {
textIndex = tempIndex;
replaceIndex = i;
}
}
}
// NOTE: logic mostly below END
// no search strings found, we are done
if (textIndex == -1) {
return text;
}
int start = 0;
// get a good guess on the size of the result buffer so it doesnt have to double if it goes over a bit
int increase = 0;
// count the replacement text elements that are larger than their corresponding text being replaced
for (int i = 0; i < searchList.length; i++) {
if (searchList[i] == null || replacementList[i] == null) {
continue;
}
int greater = replacementList[i].length() - searchList[i].length();
if (greater > 0) {
increase += 3 * greater; // assume 3 matches
}
}
// have upper-bound at 20% increase, then let Java take over
increase = Math.min(increase, text.length() / 5);
StringBuilder buf = new StringBuilder(text.length() + increase);
while (textIndex != -1) {
for (int i = start; i < textIndex; i++) {
buf.append(text.charAt(i));
}
buf.append(replacementList[replaceIndex]);
start = textIndex + searchList[replaceIndex].length();
textIndex = -1;
replaceIndex = -1;
tempIndex = -1;
// find the next earliest match
// NOTE: logic mostly duplicated above START
for (int i = 0; i < searchLength; i++) {
if (noMoreMatchesForReplIndex[i] || searchList[i] == null || searchList[i].length() == 0 || replacementList[i] == null) {
continue;
}
tempIndex = text.indexOf(searchList[i], start);
// see if we need to keep searching for this
if (tempIndex == -1) {
noMoreMatchesForReplIndex[i] = true;
} else {
if (textIndex == -1 || tempIndex < textIndex) {
textIndex = tempIndex;
replaceIndex = i;
}
}
}
// NOTE: logic duplicated above END
}
int textLength = text.length();
for (int i = start; i < textLength; i++) {
buf.append(text.charAt(i));
}
String result = buf.toString();
if (!repeat) {
return result;
}
return StringUtils.replaceEach(result, searchList, replacementList, repeat, timeToLive - 1);
}
// Replace, character based
//-----------------------------------------------------------------------
/**
* Replaces all occurrences of a character in a String with another.
* This is a null-safe version of {@link String#replace(char, char)}.
*
* A null string input returns null.
* An empty ("") string input returns an empty string.
*
*
* StringUtils.replaceChars(null, *, *) = null
* StringUtils.replaceChars("", *, *) = ""
* StringUtils.replaceChars("abcba", 'b', 'y') = "aycya"
* StringUtils.replaceChars("abcba", 'z', 'y') = "abcba"
*
*
* @param str String to replace characters in, may be null
* @param searchChar the character to search for, may be null
* @param replaceChar the character to replace, may be null
* @return modified String, null if null string input
* @since 2.0
*/
public static String replaceChars(final String str, final char searchChar, final char replaceChar) {
if (str == null) {
return null;
}
return str.replace(searchChar, replaceChar);
}
/**
* Replaces multiple characters in a String in one go.
* This method can also be used to delete characters.
*
* For example:
* replaceChars("hello", "ho", "jy") = jelly.
*
* A null string input returns null.
* An empty ("") string input returns an empty string.
* A null or empty set of search characters returns the input string.
*
* The length of the search characters should normally equal the length
* of the replace characters.
* If the search characters is longer, then the extra search characters
* are deleted.
* If the search characters is shorter, then the extra replace characters
* are ignored.
*
*
* StringUtils.replaceChars(null, *, *) = null
* StringUtils.replaceChars("", *, *) = ""
* StringUtils.replaceChars("abc", null, *) = "abc"
* StringUtils.replaceChars("abc", "", *) = "abc"
* StringUtils.replaceChars("abc", "b", null) = "ac"
* StringUtils.replaceChars("abc", "b", "") = "ac"
* StringUtils.replaceChars("abcba", "bc", "yz") = "ayzya"
* StringUtils.replaceChars("abcba", "bc", "y") = "ayya"
* StringUtils.replaceChars("abcba", "bc", "yzx") = "ayzya"
*
*
* @param str String to replace characters in, may be null
* @param searchChars a set of characters to search for, may be null
* @param replaceChars a set of characters to replace, may be null
* @return modified String, null if null string input
* @since 2.0
*/
public static String replaceChars(final String str, final String searchChars, String replaceChars) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(searchChars)) {
return str;
}
if (replaceChars == null) {
replaceChars = StringUtils.EMPTY;
}
boolean modified = false;
int replaceCharsLength = replaceChars.length();
int strLength = str.length();
StringBuilder buf = new StringBuilder(strLength);
for (int i = 0; i < strLength; i++) {
char ch = str.charAt(i);
int index = searchChars.indexOf(ch);
if (index >= 0) {
modified = true;
if (index < replaceCharsLength) {
buf.append(replaceChars.charAt(index));
}
} else {
buf.append(ch);
}
}
if (modified) {
return buf.toString();
}
return str;
}
// Overlay
//-----------------------------------------------------------------------
/**
* Overlays part of a String with another String.
*
* A null string input returns null.
* A negative index is treated as zero.
* An index greater than the string length is treated as the string length.
* The start index is always the smaller of the two indices.
*
*
* StringUtils.overlay(null, *, *, *) = null
* StringUtils.overlay("", "abc", 0, 0) = "abc"
* StringUtils.overlay("abcdef", null, 2, 4) = "abef"
* StringUtils.overlay("abcdef", "", 2, 4) = "abef"
* StringUtils.overlay("abcdef", "", 4, 2) = "abef"
* StringUtils.overlay("abcdef", "zzzz", 2, 4) = "abzzzzef"
* StringUtils.overlay("abcdef", "zzzz", 4, 2) = "abzzzzef"
* StringUtils.overlay("abcdef", "zzzz", -1, 4) = "zzzzef"
* StringUtils.overlay("abcdef", "zzzz", 2, 8) = "abzzzz"
* StringUtils.overlay("abcdef", "zzzz", -2, -3) = "zzzzabcdef"
* StringUtils.overlay("abcdef", "zzzz", 8, 10) = "abcdefzzzz"
*
*
* @param str the String to do overlaying in, may be null
* @param overlay the String to overlay, may be null
* @param start the position to start overlaying at
* @param end the position to stop overlaying before
* @return overlayed String, null if null String input
* @since 2.0
*/
public static String overlay(final String str, String overlay, int start, int end) {
if (str == null) {
return null;
}
if (overlay == null) {
overlay = StringUtils.EMPTY;
}
int len = str.length();
if (start < 0) {
start = 0;
}
if (start > len) {
start = len;
}
if (end < 0) {
end = 0;
}
if (end > len) {
end = len;
}
if (start > end) {
int temp = start;
start = end;
end = temp;
}
return new StringBuilder(len + start - end + overlay.length() + 1).append(str.substring(0, start)).append(overlay).append(str.substring(end)).toString();
}
// Chomping
//-----------------------------------------------------------------------
/**
* 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") = ""
*
*
* @param str the String to chomp a newline from, may be null
* @return String without newline, null if null String input
*/
public static String chomp(final String str) {
if (StringUtils.isEmpty(str)) {
return str;
}
if (str.length() == 1) {
char ch = str.charAt(0);
if (ch == CharUtils.CR || ch == CharUtils.LF) {
return StringUtils.EMPTY;
}
return str;
}
int lastIdx = str.length() - 1;
char last = str.charAt(lastIdx);
if (last == CharUtils.LF) {
if (str.charAt(lastIdx - 1) == CharUtils.CR) {
lastIdx--;
}
} else if (last != CharUtils.CR) {
lastIdx++;
}
return str.substring(0, lastIdx);
}
/**
* Removes separator from the end of
* str if it's there, otherwise leave it alone.
*
* NOTE: This method changed in version 2.0.
* It now more closely matches Perl chomp.
* For the previous behavior, use {@link #substringBeforeLast(String, String)}.
* This method uses {@link String#endsWith(String)}.
*
*
* StringUtils.chomp(null, *) = null
* StringUtils.chomp("", *) = ""
* StringUtils.chomp("foobar", "bar") = "foo"
* StringUtils.chomp("foobar", "baz") = "foobar"
* StringUtils.chomp("foo", "foo") = ""
* StringUtils.chomp("foo ", "foo") = "foo "
* StringUtils.chomp(" foo", "foo") = " "
* StringUtils.chomp("foo", "foooo") = "foo"
* StringUtils.chomp("foo", "") = "foo"
* StringUtils.chomp("foo", null) = "foo"
*
*
* @param str the String to chomp from, may be null
* @param separator separator String, may be null
* @return String without trailing separator, null if null String input
*/
public static String chomp(final String str, final String separator) {
if (StringUtils.isEmpty(str) || separator == null) {
return str;
}
if (str.endsWith(separator)) {
return str.substring(0, str.length() - separator.length());
}
return str;
}
// Chopping
//-----------------------------------------------------------------------
/**
* 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") = ""
*
*
* @param str the String to chop last character from, may be null
* @return String without last character, null if null String input
*/
public static String chop(final String str) {
if (str == null) {
return null;
}
int strLen = str.length();
if (strLen < 2) {
return StringUtils.EMPTY;
}
int lastIdx = strLen - 1;
String ret = str.substring(0, lastIdx);
char last = str.charAt(lastIdx);
if (last == CharUtils.LF) {
if (ret.charAt(lastIdx - 1) == CharUtils.CR) {
return ret.substring(0, lastIdx - 1);
}
}
return ret;
}
// Padding
//-----------------------------------------------------------------------
/**
* Repeat a String repeat times to form a
* new String.
*
*
* StringUtils.repeat(null, 2) = null
* StringUtils.repeat("", 0) = ""
* StringUtils.repeat("", 2) = ""
* StringUtils.repeat("a", 3) = "aaa"
* StringUtils.repeat("ab", 2) = "abab"
* StringUtils.repeat("a", -2) = ""
*
*
* @param str the String to repeat, may be null
* @param repeat number of times to repeat str, negative treated as zero
* @return a new String consisting of the original String repeated,
* null if null String input
*/
public static String repeat(final String str, final int repeat) {
// Performance tuned for 2.0 (JDK1.4)
if (str == null) {
return null;
}
if (repeat <= 0) {
return StringUtils.EMPTY;
}
int inputLength = str.length();
if (repeat == 1 || inputLength == 0) {
return str;
}
if (inputLength == 1 && repeat <= StringUtils.PAD_LIMIT) {
return StringUtils.padding(repeat, str.charAt(0));
}
int outputLength = inputLength * repeat;
switch (inputLength) {
case 1:
char ch = str.charAt(0);
char[] output1 = new char[outputLength];
for (int i = repeat - 1; i >= 0; i--) {
output1[i] = ch;
}
return new String(output1);
case 2:
char ch0 = str.charAt(0);
char ch1 = str.charAt(1);
char[] output2 = new char[outputLength];
for (int i = repeat * 2 - 2; i >= 0; i--, i--) {
output2[i] = ch0;
output2[i + 1] = ch1;
}
return new String(output2);
default:
StringBuilder buf = new StringBuilder(outputLength);
for (int i = 0; i < repeat; i++) {
buf.append(str);
}
return buf.toString();
}
}
/**
* Repeat a String repeat times to form a
* new String, with a String separator injected each time.
*
*
* StringUtils.repeat(null, null, 2) = null
* StringUtils.repeat(null, "x", 2) = null
* StringUtils.repeat("", null, 0) = ""
* StringUtils.repeat("", "", 2) = ""
* StringUtils.repeat("", "x", 3) = "xxx"
* StringUtils.repeat("?", ", ", 3) = "?, ?, ?"
*
*
* @param str the String to repeat, may be null
* @param separator the String to inject, may be null
* @param repeat number of times to repeat str, negative treated as zero
* @return a new String consisting of the original String repeated,
* null if null String input
* @since 2.5
*/
public static String repeat(final String str, final String separator, final int repeat) {
if (str == null || separator == null) {
return StringUtils.repeat(str, repeat);
} else {
// given that repeat(String, int) is quite optimized, better to rely on it than try and splice this into it
String result = StringUtils.repeat(str + separator, repeat);
return StringUtils.removeEnd(result, separator);
}
}
/**
* Returns padding using the specified delimiter repeated
* to a given length.
*
*
* StringUtils.padding(0, 'e') = ""
* StringUtils.padding(3, 'e') = "eee"
* StringUtils.padding(-2, 'e') = IndexOutOfBoundsException
*
*
* Note: this method doesn't not support padding with
* Unicode Supplementary Characters
* as they require a pair of chars to be represented.
* If you are needing to support full I18N of your applications
* consider using {@link #repeat(String, int)} instead.
*
*
* @param repeat number of times to repeat delim
* @param padChar character to repeat
* @return String with repeated character
* @throws IndexOutOfBoundsException if repeat < 0
* @see #repeat(String, int)
*/
private static String padding(final int repeat, final char padChar) throws IndexOutOfBoundsException {
if (repeat < 0) {
throw new IndexOutOfBoundsException("Cannot pad a negative amount: " + repeat);
}
final char[] buf = new char[repeat];
for (int i = 0; i < buf.length; i++) {
buf[i] = padChar;
}
return new String(buf);
}
/**
* Right pad a String with spaces (' ').
*
* The String is padded to the size of size.
*
*
* StringUtils.rightPad(null, *) = null
* StringUtils.rightPad("", 3) = " "
* StringUtils.rightPad("bat", 3) = "bat"
* StringUtils.rightPad("bat", 5) = "bat "
* StringUtils.rightPad("bat", 1) = "bat"
* StringUtils.rightPad("bat", -1) = "bat"
*
*
* @param str the String to pad out, may be null
* @param size the size to pad to
* @return right padded String or original String if no padding is necessary,
* null if null String input
*/
public static String rightPad(final String str, final int size) {
return StringUtils.rightPad(str, size, ' ');
}
/**
* Right pad a String with a specified character.
*
* The String is padded to the size of size.
*
*
* StringUtils.rightPad(null, *, *) = null
* StringUtils.rightPad("", 3, 'z') = "zzz"
* StringUtils.rightPad("bat", 3, 'z') = "bat"
* StringUtils.rightPad("bat", 5, 'z') = "batzz"
* StringUtils.rightPad("bat", 1, 'z') = "bat"
* StringUtils.rightPad("bat", -1, 'z') = "bat"
*
*
* @param str the String to pad out, may be null
* @param size the size to pad to
* @param padChar the character to pad with
* @return right padded String or original String if no padding is necessary,
* null if null String input
* @since 2.0
*/
public static String rightPad(final String str, final int size, final char padChar) {
if (str == null) {
return null;
}
int pads = size - str.length();
if (pads <= 0) {
return str; // returns original String when possible
}
if (pads > StringUtils.PAD_LIMIT) {
return StringUtils.rightPad(str, size, String.valueOf(padChar));
}
return str.concat(StringUtils.padding(pads, padChar));
}
/**
* Right pad a String with a specified String.
*
* The String is padded to the size of size.
*
*
* StringUtils.rightPad(null, *, *) = null
* StringUtils.rightPad("", 3, "z") = "zzz"
* StringUtils.rightPad("bat", 3, "yz") = "bat"
* StringUtils.rightPad("bat", 5, "yz") = "batyz"
* StringUtils.rightPad("bat", 8, "yz") = "batyzyzy"
* StringUtils.rightPad("bat", 1, "yz") = "bat"
* StringUtils.rightPad("bat", -1, "yz") = "bat"
* StringUtils.rightPad("bat", 5, null) = "bat "
* StringUtils.rightPad("bat", 5, "") = "bat "
*
*
* @param str the String to pad out, may be null
* @param size the size to pad to
* @param padStr the String to pad with, null or empty treated as single space
* @return right padded String or original String if no padding is necessary,
* null if null String input
*/
public static String rightPad(final String str, final int size, String padStr) {
if (str == null) {
return null;
}
if (StringUtils.isEmpty(padStr)) {
padStr = " ";
}
int padLen = padStr.length();
int strLen = str.length();
int pads = size - strLen;
if (pads <= 0) {
return str; // returns original String when possible
}
if (padLen == 1 && pads <= StringUtils.PAD_LIMIT) {
return StringUtils.rightPad(str, size, padStr.charAt(0));
}
if (pads == padLen) {
return str.concat(padStr);
} else if (pads < padLen) {
return str.concat(padStr.substring(0, pads));
} else {
char[] padding = new char[pads];
char[] padChars = padStr.toCharArray();
for (int i = 0; i < pads; i++) {
padding[i] = padChars[i % padLen];
}
return str.concat(new String(padding));
}
}
/**
* Left pad a String with spaces (' ').
*
* The String is padded to the size of size.
*
*
* StringUtils.leftPad(null, *) = null
* StringUtils.leftPad("", 3) = " "
* StringUtils.leftPad("bat", 3) = "bat"
* StringUtils.leftPad("bat", 5) = " bat"
* StringUtils.leftPad("bat", 1) = "bat"
* StringUtils.leftPad("bat", -1) = "bat"
*
*
* @param str the String to pad out, may be null
* @param size the size to pad to
* @return left padded String or original String if no padding is necessary,
* null if null String input
*/
public static String leftPad(final String str, final int size) {
return StringUtils.leftPad(str, size, ' ');
}
/**
* Left pad a String with a specified character.
*
* Pad to a size of size.
*
*
* StringUtils.leftPad(null, *, *) = null
* StringUtils.leftPad("", 3, 'z') = "zzz"
* StringUtils.leftPad("bat", 3, 'z') = "bat"
* StringUtils.leftPad("bat", 5, 'z') = "zzbat"
* StringUtils.leftPad("bat", 1, 'z') = "bat"
* StringUtils.leftPad("bat", -1, 'z') = "bat"
*
*
* @param str the String to pad out, may be null
* @param size the size to pad to
* @param padChar the character to pad with
* @return left padded String or original String if no padding is necessary,
* null if null String input
* @since 2.0
*/
public static String leftPad(final String str, final int size, final char padChar) {
if (str == null) {
return null;
}
int pads = size - str.length();
if (pads <= 0) {
return str; // returns original String when possible
}
if (pads > StringUtils.PAD_LIMIT) {
return StringUtils.leftPad(str, size, String.valueOf(padChar));
}
return StringUtils.padding(pads, padChar).concat(str);
}
/**
* Left pad a String with a specified String.
*
* Pad to a size of size.
*
*
* StringUtils.leftPad(null, *, *) = null
* StringUtils.leftPad("", 3, "z") = "zzz"
* StringUtils.leftPad("bat", 3, "yz") = "bat"
* StringUtils.leftPad("bat", 5, "yz") = "yzbat"
* StringUtils.leftPad("bat", 8, "yz") = "yzyzybat"
* StringUtils.leftPad("bat", 1, "yz") = "bat"
* StringUtils.leftPad("bat", -1, "yz") = "bat"
* StringUtils.leftPad("bat", 5, null) = " bat"
* StringUtils.leftPad("bat", 5, "") = " bat"
*
*
* @param str the String to pad out, may be null
* @param size the size to pad to
* @param padStr the String to pad with, null or empty treated as single space
* @return left padded String or original String if no padding is necessary,
* null if null String input
*/
public static String leftPad(final String str, final int size, String padStr) {
if (str == null) {
return null;
}
if (StringUtils.isEmpty(padStr)) {
padStr = " ";
}
int padLen = padStr.length();
int strLen = str.length();
int pads = size - strLen;
if (pads <= 0) {
return str; // returns original String when possible
}
if (padLen == 1 && pads <= StringUtils.PAD_LIMIT) {
return StringUtils.leftPad(str, size, padStr.charAt(0));
}
if (pads == padLen) {
return padStr.concat(str);
} else if (pads < padLen) {
return padStr.substring(0, pads).concat(str);
} else {
char[] padding = new char[pads];
char[] padChars = padStr.toCharArray();
for (int i = 0; i < pads; i++) {
padding[i] = padChars[i % padLen];
}
return new String(padding).concat(str);
}
}
/**
* Gets a String's length or 0 if the String is null.
*
* @param str
* a String or null
* @return String length or 0 if the String is null.
* @since 2.4
*/
public static int length(final String str) {
return str == null ? 0 : str.length();
}
// Centering
//-----------------------------------------------------------------------
/**
* Centers a String in a larger String of size size
* using the space character (' ').
*
*
If the size is less than the String length, the String is returned.
* A null String returns null.
* A negative size is treated as zero.
*
* Equivalent to center(str, size, " ").
*
*
* StringUtils.center(null, *) = null
* StringUtils.center("", 4) = " "
* StringUtils.center("ab", -1) = "ab"
* StringUtils.center("ab", 4) = " ab "
* StringUtils.center("abcd", 2) = "abcd"
* StringUtils.center("a", 4) = " a "
*
*
* @param str the String to center, may be null
* @param size the int size of new String, negative treated as zero
* @return centered String, null if null String input
*/
public static String center(final String str, final int size) {
return StringUtils.center(str, size, ' ');
}
/**
* Centers a String in a larger String of size size.
* Uses a supplied character as the value to pad the String with.
*
* If the size is less than the String length, the String is returned.
* A null String returns null.
* A negative size is treated as zero.
*
*
* StringUtils.center(null, *, *) = null
* StringUtils.center("", 4, ' ') = " "
* StringUtils.center("ab", -1, ' ') = "ab"
* StringUtils.center("ab", 4, ' ') = " ab"
* StringUtils.center("abcd", 2, ' ') = "abcd"
* StringUtils.center("a", 4, ' ') = " a "
* StringUtils.center("a", 4, 'y') = "yayy"
*
*
* @param str the String to center, may be null
* @param size the int size of new String, negative treated as zero
* @param padChar the character to pad the new String with
* @return centered String, null if null String input
* @since 2.0
*/
public static String center(String str, final int size, final char padChar) {
if (str == null || size <= 0) {
return str;
}
int strLen = str.length();
int pads = size - strLen;
if (pads <= 0) {
return str;
}
str = StringUtils.leftPad(str, strLen + pads / 2, padChar);
str = StringUtils.rightPad(str, size, padChar);
return str;
}
/**
* Centers a String in a larger String of size size.
* Uses a supplied String as the value to pad the String with.
*
* If the size is less than the String length, the String is returned.
* A null String returns null.
* A negative size is treated as zero.
*
*
* StringUtils.center(null, *, *) = null
* StringUtils.center("", 4, " ") = " "
* StringUtils.center("ab", -1, " ") = "ab"
* StringUtils.center("ab", 4, " ") = " ab"
* StringUtils.center("abcd", 2, " ") = "abcd"
* StringUtils.center("a", 4, " ") = " a "
* StringUtils.center("a", 4, "yz") = "yayz"
* StringUtils.center("abc", 7, null) = " abc "
* StringUtils.center("abc", 7, "") = " abc "
*
*
* @param str the String to center, may be null
* @param size the int size of new String, negative treated as zero
* @param padStr the String to pad the new String with, must not be null or empty
* @return centered String, null if null String input
* @throws IllegalArgumentException if padStr is null or empty
*/
public static String center(String str, final int size, String padStr) {
if (str == null || size <= 0) {
return str;
}
if (StringUtils.isEmpty(padStr)) {
padStr = " ";
}
int strLen = str.length();
int pads = size - strLen;
if (pads <= 0) {
return str;
}
str = StringUtils.leftPad(str, strLen + pads / 2, padStr);
str = StringUtils.rightPad(str, size, padStr);
return str;
}
// Case conversion
//-----------------------------------------------------------------------
/**
* Converts a String to upper case as per {@link String#toUpperCase()}.
*
* A null input String returns null.
*
*
* StringUtils.upperCase(null) = null
* StringUtils.upperCase("") = ""
* StringUtils.upperCase("aBc") = "ABC"
*
*
* Note: As described in the documentation for {@link String#toUpperCase()},
* the result of this method is affected by the current locale.
* For platform-independent case transformations, the method {@link #lowerCase(String, Locale)}
* should be used with a specific locale (e.g. {@link Locale#ENGLISH}).
*
* @param str the String to upper case, may be null
* @return the upper cased String, null if null String input
*/
public static String upperCase(final String str) {
if (str == null) {
return null;
}
return str.toUpperCase();
}
/**
* Converts a String to upper case as per {@link String#toUpperCase(Locale)}.
*
* A null input String returns null.
*
*
* StringUtils.upperCase(null, Locale.ENGLISH) = null
* StringUtils.upperCase("", Locale.ENGLISH) = ""
* StringUtils.upperCase("aBc", Locale.ENGLISH) = "ABC"
*
*
* @param str the String to upper case, may be null
* @param locale the locale that defines the case transformation rules, must not be null
* @return the upper cased String, null if null String input
* @since 2.5
*/
public static String upperCase(final String str, final Locale locale) {
if (str == null) {
return null;
}
return str.toUpperCase(locale);
}
/**
* Converts a String to lower case as per {@link String#toLowerCase()}.
*
* A null input String returns null.
*
*
* StringUtils.lowerCase(null) = null
* StringUtils.lowerCase("") = ""
* StringUtils.lowerCase("aBc") = "abc"
*
*
* Note: As described in the documentation for {@link String#toLowerCase()},
* the result of this method is affected by the current locale.
* For platform-independent case transformations, the method {@link #lowerCase(String, Locale)}
* should be used with a specific locale (e.g. {@link Locale#ENGLISH}).
*
* @param str the String to lower case, may be null
* @return the lower cased String, null if null String input
*/
public static String lowerCase(final String str) {
if (str == null) {
return null;
}
return str.toLowerCase();
}
/**
* Converts a String to lower case as per {@link String#toLowerCase(Locale)}.
*
* A null input String returns null.
*
*
* StringUtils.lowerCase(null, Locale.ENGLISH) = null
* StringUtils.lowerCase("", Locale.ENGLISH) = ""
* StringUtils.lowerCase("aBc", Locale.ENGLISH) = "abc"
*
*
* @param str the String to lower case, may be null
* @param locale the locale that defines the case transformation rules, must not be null
* @return the lower cased String, null if null String input
* @since 2.5
*/
public static String lowerCase(final String str, final Locale locale) {
if (str == null) {
return null;
}
return str.toLowerCase(locale);
}
/**
* Capitalizes a String changing the first letter to title case as
* per {@link Character#toTitleCase(char)}. No other letters are changed.
*
* A null input String returns null.
*
*
* StringUtils.capitalize(null) = null
* StringUtils.capitalize("") = ""
* StringUtils.capitalize("cat") = "Cat"
* StringUtils.capitalize("cAt") = "CAt"
*
*
* @param str the String to capitalize, may be null
* @return the capitalized String, null if null String input
* @see #uncapitalize(String)
* @since 2.0
*/
public static String capitalize(final String str) {
int strLen;
if (str == null || (strLen = str.length()) == 0) {
return str;
}
return new StringBuilder(strLen).append(Character.toTitleCase(str.charAt(0))).append(str.substring(1)).toString();
}
/**
* Uncapitalizes a String changing the first letter to title case as
* per {@link Character#toLowerCase(char)}. No other letters are changed.
*
* A null input String returns null.
*
*
* StringUtils.uncapitalize(null) = null
* StringUtils.uncapitalize("") = ""
* StringUtils.uncapitalize("Cat") = "cat"
* StringUtils.uncapitalize("CAT") = "cAT"
*
*
* @param str the String to uncapitalize, may be null
* @return the uncapitalized String, null if null String input
* @see #capitalize(String)
* @since 2.0
*/
public static String uncapitalize(final String str) {
int strLen;
if (str == null || (strLen = str.length()) == 0) {
return str;
}
return new StringBuilder(strLen).append(Character.toLowerCase(str.charAt(0))).append(str.substring(1)).toString();
}
/**
* Swaps the case of a String changing upper and title case to
* lower case, and lower case to upper case.
*
*
* - Upper case character converts to Lower case
* - Title case character converts to Lower case
* - Lower case character converts to Upper case
*
*
* A null input String returns null.
*
*
* StringUtils.swapCase(null) = null
* StringUtils.swapCase("") = ""
* StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"
*
*
* NOTE: This method changed in Lang version 2.0.
* It no longer performs a word based algorithm.
* If you only use ASCII, you will notice no change.
* That functionality is available in WordUtils.
*
* @param str the String to swap case, may be null
* @return the changed String, null if null String input
*/
public static String swapCase(final String str) {
int strLen;
if (str == null || (strLen = str.length()) == 0) {
return str;
}
StringBuilder buffer = new StringBuilder(strLen);
char ch = 0;
for (int i = 0; i < strLen; i++) {
ch = str.charAt(i);
if (Character.isUpperCase(ch)) {
ch = Character.toLowerCase(ch);
} else if (Character.isTitleCase(ch)) {
ch = Character.toLowerCase(ch);
} else if (Character.isLowerCase(ch)) {
ch = Character.toUpperCase(ch);
}
buffer.append(ch);
}
return buffer.toString();
}
// Count matches
//-----------------------------------------------------------------------
/**
* Counts how many times the substring appears in the larger String.
*
* A null or empty ("") String input returns 0.
*
*
* StringUtils.countMatches(null, *) = 0
* StringUtils.countMatches("", *) = 0
* StringUtils.countMatches("abba", null) = 0
* StringUtils.countMatches("abba", "") = 0
* StringUtils.countMatches("abba", "a") = 2
* StringUtils.countMatches("abba", "ab") = 1
* StringUtils.countMatches("abba", "xxx") = 0
*
*
* @param str the String to check, may be null
* @param sub the substring to count, may be null
* @return the number of occurrences, 0 if either String is null
*/
public static int countMatches(final String str, final String sub) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(sub)) {
return 0;
}
int count = 0;
int idx = 0;
while ((idx = str.indexOf(sub, idx)) != StringUtils.INDEX_NOT_FOUND) {
count++;
idx += sub.length();
}
return count;
}
// Character Tests
//-----------------------------------------------------------------------
/**
* Checks if the String contains only unicode letters.
*
* null will return false.
* An empty String (length()=0) will return true.
*
*
* StringUtils.isAlpha(null) = false
* StringUtils.isAlpha("") = true
* StringUtils.isAlpha(" ") = false
* StringUtils.isAlpha("abc") = true
* StringUtils.isAlpha("ab2c") = false
* StringUtils.isAlpha("ab-c") = false
*
*
* @param str the String to check, may be null
* @return true if only contains letters, and is non-null
*/
public static boolean isAlpha(final String str) {
if (str == null) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (Character.isLetter(str.charAt(i)) == false) {
return false;
}
}
return true;
}
/**
* Checks if the String contains only unicode letters and
* space (' ').
*
* null will return false
* An empty String (length()=0) will return true.
*
*
* StringUtils.isAlphaSpace(null) = false
* StringUtils.isAlphaSpace("") = true
* StringUtils.isAlphaSpace(" ") = true
* StringUtils.isAlphaSpace("abc") = true
* StringUtils.isAlphaSpace("ab c") = true
* StringUtils.isAlphaSpace("ab2c") = false
* StringUtils.isAlphaSpace("ab-c") = false
*
*
* @param str the String to check, may be null
* @return true if only contains letters and space,
* and is non-null
*/
public static boolean isAlphaSpace(final String str) {
if (str == null) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (Character.isLetter(str.charAt(i)) == false && str.charAt(i) != ' ') {
return false;
}
}
return true;
}
/**
* Checks if the String contains only unicode letters or digits.
*
* null will return false.
* An empty String (length()=0) will return true.
*
*
* StringUtils.isAlphanumeric(null) = false
* StringUtils.isAlphanumeric("") = true
* StringUtils.isAlphanumeric(" ") = false
* StringUtils.isAlphanumeric("abc") = true
* StringUtils.isAlphanumeric("ab c") = false
* StringUtils.isAlphanumeric("ab2c") = true
* StringUtils.isAlphanumeric("ab-c") = false
*
*
* @param str the String to check, may be null
* @return true if only contains letters or digits,
* and is non-null
*/
public static boolean isAlphanumeric(final String str) {
if (str == null) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (Character.isLetterOrDigit(str.charAt(i)) == false) {
return false;
}
}
return true;
}
/**
* Checks if the String contains only unicode letters, digits
* or space (' ').
*
* null will return false.
* An empty String (length()=0) will return true.
*
*
* StringUtils.isAlphanumeric(null) = false
* StringUtils.isAlphanumeric("") = true
* StringUtils.isAlphanumeric(" ") = true
* StringUtils.isAlphanumeric("abc") = true
* StringUtils.isAlphanumeric("ab c") = true
* StringUtils.isAlphanumeric("ab2c") = true
* StringUtils.isAlphanumeric("ab-c") = false
*
*
* @param str the String to check, may be null
* @return true if only contains letters, digits or space,
* and is non-null
*/
public static boolean isAlphanumericSpace(final String str) {
if (str == null) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (Character.isLetterOrDigit(str.charAt(i)) == false && str.charAt(i) != ' ') {
return false;
}
}
return true;
}
/**
* Checks if the string contains only ASCII printable characters.
*
* null will return false.
* An empty String (length()=0) will return true.
*
*
* 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
*
*
* @param str the string to check, may be null
* @return true if every character is in the range
* 32 thru 126
* @since 2.1
*/
public static boolean isAsciiPrintable(final String str) {
if (str == null) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (CharUtils.isAsciiPrintable(str.charAt(i)) == false) {
return false;
}
}
return true;
}
/**
* Checks if the String contains only unicode digits.
* A decimal point is not a unicode digit and returns false.
*
* null will return false.
* An empty String (length()=0) will return true.
*
*
* StringUtils.isNumeric(null) = false
* StringUtils.isNumeric("") = true
* StringUtils.isNumeric(" ") = false
* StringUtils.isNumeric("123") = true
* StringUtils.isNumeric("12 3") = false
* StringUtils.isNumeric("ab2c") = false
* StringUtils.isNumeric("12-3") = false
* StringUtils.isNumeric("12.3") = false
*
*
* @param str the String to check, may be null
* @return true if only contains digits, and is non-null
*/
public static boolean isNumeric(final String str) {
if (str == null) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (Character.isDigit(str.charAt(i)) == false) {
return false;
}
}
return true;
}
/**
* Checks if the String contains only unicode digits or space
* (' ').
* A decimal point is not a unicode digit and returns false.
*
* null will return false.
* An empty String (length()=0) will return true.
*
*
* StringUtils.isNumeric(null) = false
* StringUtils.isNumeric("") = true
* StringUtils.isNumeric(" ") = true
* StringUtils.isNumeric("123") = true
* StringUtils.isNumeric("12 3") = true
* StringUtils.isNumeric("ab2c") = false
* StringUtils.isNumeric("12-3") = false
* StringUtils.isNumeric("12.3") = false
*
*
* @param str the String to check, may be null
* @return true if only contains digits or space,
* and is non-null
*/
public static boolean isNumericSpace(final String str) {
if (str == null) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (Character.isDigit(str.charAt(i)) == false && str.charAt(i) != ' ') {
return false;
}
}
return true;
}
/**
* Checks if the String contains only whitespace.
*
* null will return false.
* An empty String (length()=0) will return true.
*
*
* StringUtils.isWhitespace(null) = false
* StringUtils.isWhitespace("") = true
* StringUtils.isWhitespace(" ") = true
* StringUtils.isWhitespace("abc") = false
* StringUtils.isWhitespace("ab2c") = false
* StringUtils.isWhitespace("ab-c") = false
*
*
* @param str the String to check, may be null
* @return true if only contains whitespace, and is non-null
* @since 2.0
*/
public static boolean isWhitespace(final String str) {
if (str == null) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (Character.isWhitespace(str.charAt(i)) == false) {
return false;
}
}
return true;
}
/**
* Checks if the String contains only lowercase characters.
*
* null will return false.
* An empty String (length()=0) will return false.
*
*
* StringUtils.isAllLowerCase(null) = false
* StringUtils.isAllLowerCase("") = false
* StringUtils.isAllLowerCase(" ") = false
* StringUtils.isAllLowerCase("abc") = true
* StringUtils.isAllLowerCase("abC") = false
*
*
* @param str the String to check, may be null
* @return true if only contains lowercase characters, and is non-null
* @since 2.5
*/
public static boolean isAllLowerCase(final String str) {
if (str == null || StringUtils.isEmpty(str)) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (Character.isLowerCase(str.charAt(i)) == false) {
return false;
}
}
return true;
}
/**
* Checks if the String contains only uppercase characters.
*
* null will return false.
* An empty String (length()=0) will return false.
*
*
* StringUtils.isAllUpperCase(null) = false
* StringUtils.isAllUpperCase("") = false
* StringUtils.isAllUpperCase(" ") = false
* StringUtils.isAllUpperCase("ABC") = true
* StringUtils.isAllUpperCase("aBC") = false
*
*
* @param str the String to check, may be null
* @return true if only contains uppercase characters, and is non-null
* @since 2.5
*/
public static boolean isAllUpperCase(final String str) {
if (str == null || StringUtils.isEmpty(str)) {
return false;
}
int sz = str.length();
for (int i = 0; i < sz; i++) {
if (Character.isUpperCase(str.charAt(i)) == false) {
return false;
}
}
return true;
}
// Defaults
//-----------------------------------------------------------------------
/**
* Returns either the passed in String,
* or if the String is null, an empty String ("").
*
*
* StringUtils.defaultString(null) = ""
* StringUtils.defaultString("") = ""
* StringUtils.defaultString("bat") = "bat"
*
*
* @see ObjectUtils#toString(Object)
* @see String#valueOf(Object)
* @param str the String to check, may be null
* @return the passed in String, or the empty String if it
* was null
*/
public static String defaultString(final String str) {
return str == null ? StringUtils.EMPTY : str;
}
/**
* Returns either the passed in String, or if the String is
* null, the value of defaultStr.
*
*
* StringUtils.defaultString(null, "NULL") = "NULL"
* StringUtils.defaultString("", "NULL") = ""
* StringUtils.defaultString("bat", "NULL") = "bat"
*
*
* @see ObjectUtils#toString(Object, String)
* @see String#valueOf(Object)
* @param str the String to check, may be null
* @param defaultStr the default String to return
* if the input is null, may be null
* @return the passed in String, or the default if it was null
*/
public static String defaultString(final String str, final String defaultStr) {
return str == null ? defaultStr : str;
}
/**
* Returns either the passed in String, or if the String is
* whitespace, empty ("") or null, the value of defaultStr.
*
*
* StringUtils.defaultIfBlank(null, "NULL") = "NULL"
* StringUtils.defaultIfBlank("", "NULL") = "NULL"
* StringUtils.defaultIfBlank(" ", "NULL") = "NULL"
* StringUtils.defaultIfBlank("bat", "NULL") = "bat"
* StringUtils.defaultIfBlank("", null) = null
*
* @param str the String to check, may be null
* @param defaultStr the default String to return
* if the input is whitespace, empty ("") or null, may be null
* @return the passed in String, or the default
* @see StringUtils#defaultString(String, String)
* @since 2.6
*/
public static String defaultIfBlank(final String str, final String defaultStr) {
return StringUtils.isBlank(str) ? defaultStr : str;
}
/**
* Returns either the passed in String, or if the String is
* empty or null, the value of defaultStr.
*
*
* StringUtils.defaultIfEmpty(null, "NULL") = "NULL"
* StringUtils.defaultIfEmpty("", "NULL") = "NULL"
* StringUtils.defaultIfEmpty("bat", "NULL") = "bat"
* StringUtils.defaultIfEmpty("", null) = null
*
*
* @param str the String to check, may be null
* @param defaultStr the default String to return
* if the input is empty ("") or null, may be null
* @return the passed in String, or the default
* @see StringUtils#defaultString(String, String)
*/
public static String defaultIfEmpty(final String str, final String defaultStr) {
return StringUtils.isEmpty(str) ? defaultStr : str;
}
// Reversing
//-----------------------------------------------------------------------
/**
* Reverses a String as per {@link StringBuilder#reverse()}.
*
* A null String returns null.
*
*
* StringUtils.reverse(null) = null
* StringUtils.reverse("") = ""
* StringUtils.reverse("bat") = "tab"
*
*
* @param str the String to reverse, may be null
* @return the reversed String, null if null String input
*/
public static String reverse(final String str) {
if (str == null) {
return null;
}
return new StringBuilder(str).reverse().toString();
}
/**
* 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"
*
*
* @param str the String to reverse, may be null
* @param separatorChar the separator character to use
* @return the reversed String, null if null String input
* @since 2.0
*/
public static String reverseDelimited(final String str, final char separatorChar) {
if (str == null) {
return null;
}
// could implement manually, but simple way is to reuse other,
// probably slower, methods.
String[] strs = StringUtils.split(str, separatorChar);
ArrayUtils.reverse(strs);
return StringUtils.join(strs, separatorChar);
}
// Abbreviating
//-----------------------------------------------------------------------
/**
* Abbreviates a String using ellipses. This will turn
* "Now is the time for all good men" into "Now is the time for..."
*
* Specifically:
*
* - If
str is less than maxWidth characters
* long, return it.
* - Else abbreviate it to
(substring(str, 0, max-3) + "...").
* - If
maxWidth is less than 4, throw an
* IllegalArgumentException.
* - In no case will it return a String of length greater than
*
maxWidth.
*
*
*
*
* StringUtils.abbreviate(null, *) = null
* StringUtils.abbreviate("", 4) = ""
* StringUtils.abbreviate("abcdefg", 6) = "abc..."
* StringUtils.abbreviate("abcdefg", 7) = "abcdefg"
* StringUtils.abbreviate("abcdefg", 8) = "abcdefg"
* StringUtils.abbreviate("abcdefg", 4) = "a..."
* StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException
*
*
* @param str the String to check, may be null
* @param maxWidth maximum length of result String, must be at least 4
* @return abbreviated String, null if null String input
* @throws IllegalArgumentException if the width is too small
* @since 2.0
*/
public static String abbreviate(final String str, final int maxWidth) {
return StringUtils.abbreviate(str, 0, maxWidth);
}
/**
* Abbreviates a String using ellipses. This will turn
* "Now is the time for all good men" into "...is the time for..."
*
* Works like abbreviate(String, int), but allows you to specify
* a "left edge" offset. Note that this left edge is not necessarily going to
* be the leftmost character in the result, or the first character following the
* ellipses, but it will appear somewhere in the result.
*
*
In no case will it return a String of length greater than
* maxWidth.
*
*
* StringUtils.abbreviate(null, *, *) = null
* StringUtils.abbreviate("", 0, 4) = ""
* StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..."
* StringUtils.abbreviate("abcdefghijklmno", 0, 10) = "abcdefg..."
* StringUtils.abbreviate("abcdefghijklmno", 1, 10) = "abcdefg..."
* StringUtils.abbreviate("abcdefghijklmno", 4, 10) = "abcdefg..."
* StringUtils.abbreviate("abcdefghijklmno", 5, 10) = "...fghi..."
* StringUtils.abbreviate("abcdefghijklmno", 6, 10) = "...ghij..."
* StringUtils.abbreviate("abcdefghijklmno", 8, 10) = "...ijklmno"
* StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno"
* StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno"
* StringUtils.abbreviate("abcdefghij", 0, 3) = IllegalArgumentException
* StringUtils.abbreviate("abcdefghij", 5, 6) = IllegalArgumentException
*
*
* @param str the String to check, may be null
* @param offset left edge of source String
* @param maxWidth maximum length of result String, must be at least 4
* @return abbreviated String, null if null String input
* @throws IllegalArgumentException if the width is too small
* @since 2.0
*/
public static String abbreviate(final String str, int offset, final int maxWidth) {
if (str == null) {
return null;
}
if (maxWidth < 4) {
throw new IllegalArgumentException("Minimum abbreviation width is 4");
}
if (str.length() <= maxWidth) {
return str;
}
if (offset > str.length()) {
offset = str.length();
}
if (str.length() - offset < maxWidth - 3) {
offset = str.length() - (maxWidth - 3);
}
if (offset <= 4) {
return str.substring(0, maxWidth - 3) + "...";
}
if (maxWidth < 7) {
throw new IllegalArgumentException("Minimum abbreviation width with offset is 7");
}
if (offset + maxWidth - 3 < str.length()) {
return "..." + StringUtils.abbreviate(str.substring(offset), maxWidth - 3);
}
return "..." + str.substring(str.length() - (maxWidth - 3));
}
/**
* Abbreviates a String to the length passed, replacing the middle characters with the supplied
* replacement String.
*
* This abbreviation only occurs if the following criteria is met:
*
* - Neither the String for abbreviation nor the replacement String are null or empty
* - The length to truncate to is less than the length of the supplied String
* - The length to truncate to is greater than 0
* - The abbreviated String will have enough room for the length supplied replacement String
* and the first and last characters of the supplied String for abbreviation
*
* Otherwise, the returned String will be the same as the supplied String for abbreviation.
*
*
*
* StringUtils.abbreviateMiddle(null, null, 0) = null
* StringUtils.abbreviateMiddle("abc", null, 0) = "abc"
* StringUtils.abbreviateMiddle("abc", ".", 0) = "abc"
* StringUtils.abbreviateMiddle("abc", ".", 3) = "abc"
* StringUtils.abbreviateMiddle("abcdef", ".", 4) = "ab.f"
*
*
* @param str the String to abbreviate, may be null
* @param middle the String to replace the middle characters with, may be null
* @param length the length to abbreviate str to.
* @return the abbreviated String if the above criteria is met, or the original String supplied for abbreviation.
* @since 2.5
*/
public static String abbreviateMiddle(final String str, final String middle, final int length) {
if (StringUtils.isEmpty(str) || StringUtils.isEmpty(middle)) {
return str;
}
if (length >= str.length() || length < middle.length() + 2) {
return str;
}
int targetSting = length - middle.length();
int startOffset = targetSting / 2 + targetSting % 2;
int endOffset = str.length() - targetSting / 2;
StringBuilder builder = new StringBuilder(length);
builder.append(str.substring(0, startOffset));
builder.append(middle);
builder.append(str.substring(endOffset));
return builder.toString();
}
// Difference
//-----------------------------------------------------------------------
/**
* 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"
*
*
* @param str1 the first String, may be null
* @param str2 the second String, may be null
* @return the portion of str2 where it differs from str1; returns the
* empty String if they are equal
* @since 2.0
*/
public static String difference(final String str1, final String str2) {
if (str1 == null) {
return str2;
}
if (str2 == null) {
return str1;
}
int at = StringUtils.indexOfDifference(str1, str2);
if (at == StringUtils.INDEX_NOT_FOUND) {
return StringUtils.EMPTY;
}
return str2.substring(at);
}
/**
* 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
*
*
* @param str1 the first String, may be null
* @param str2 the second String, may be null
* @return the index where str2 and str1 begin to differ; -1 if they are equal
* @since 2.0
*/
public static int indexOfDifference(final String str1, final String str2) {
if (str1 != null && str1.equals(str2)) {
return StringUtils.INDEX_NOT_FOUND;
}
if (str1 == null || str2 == null) {
return 0;
}
int i;
for (i = 0; i < str1.length() && i < str2.length(); ++i) {
if (str1.charAt(i) != str2.charAt(i)) {
break;
}
}
if (i < str2.length() || i < str1.length()) {
return i;
}
return StringUtils.INDEX_NOT_FOUND;
}
/**
* Compares all Strings in an array and returns the index at which the
* Strings begin to differ.
*
* For example,
* indexOfDifference(new String[] {"i am a machine", "i am a robot"}) -> 7
*
*
* StringUtils.indexOfDifference(null) = -1
* StringUtils.indexOfDifference(new String[] {}) = -1
* StringUtils.indexOfDifference(new String[] {"abc"}) = -1
* StringUtils.indexOfDifference(new String[] {null, null}) = -1
* StringUtils.indexOfDifference(new String[] {"", ""}) = -1
* StringUtils.indexOfDifference(new String[] {"", null}) = 0
* StringUtils.indexOfDifference(new String[] {"abc", null, null}) = 0
* StringUtils.indexOfDifference(new String[] {null, null, "abc"}) = 0
* StringUtils.indexOfDifference(new String[] {"", "abc"}) = 0
* StringUtils.indexOfDifference(new String[] {"abc", ""}) = 0
* StringUtils.indexOfDifference(new String[] {"abc", "abc"}) = -1
* StringUtils.indexOfDifference(new String[] {"abc", "a"}) = 1
* StringUtils.indexOfDifference(new String[] {"ab", "abxyz"}) = 2
* StringUtils.indexOfDifference(new String[] {"abcde", "abxyz"}) = 2
* StringUtils.indexOfDifference(new String[] {"abcde", "xyz"}) = 0
* StringUtils.indexOfDifference(new String[] {"xyz", "abcde"}) = 0
* StringUtils.indexOfDifference(new String[] {"i am a machine", "i am a robot"}) = 7
*
*
* @param strs array of strings, entries may be null
* @return the index where the strings begin to differ; -1 if they are all equal
* @since 2.4
*/
public static int indexOfDifference(final String[] strs) {
if (strs == null || strs.length <= 1) {
return StringUtils.INDEX_NOT_FOUND;
}
boolean anyStringNull = false;
boolean allStringsNull = true;
int arrayLen = strs.length;
int shortestStrLen = Integer.MAX_VALUE;
int longestStrLen = 0;
// find the min and max string lengths; this avoids checking to make
// sure we are not exceeding the length of the string each time through
// the bottom loop.
for (int i = 0; i < arrayLen; i++) {
if (strs[i] == null) {
anyStringNull = true;
shortestStrLen = 0;
} else {
allStringsNull = false;
shortestStrLen = Math.min(strs[i].length(), shortestStrLen);
longestStrLen = Math.max(strs[i].length(), longestStrLen);
}
}
// handle lists containing all nulls or all empty strings
if (allStringsNull || longestStrLen == 0 && !anyStringNull) {
return StringUtils.INDEX_NOT_FOUND;
}
// handle lists containing some nulls or some empty strings
if (shortestStrLen == 0) {
return 0;
}
// find the position with the first difference across all strings
int firstDiff = -1;
for (int stringPos = 0; stringPos < shortestStrLen; stringPos++) {
char comparisonChar = strs[0].charAt(stringPos);
for (int arrayPos = 1; arrayPos < arrayLen; arrayPos++) {
if (strs[arrayPos].charAt(stringPos) != comparisonChar) {
firstDiff = stringPos;
break;
}
}
if (firstDiff != -1) {
break;
}
}
if (firstDiff == -1 && shortestStrLen != longestStrLen) {
// we compared all of the characters up to the length of the
// shortest string and didn't find a match, but the string lengths
// vary, so return the length of the shortest string.
return shortestStrLen;
}
return firstDiff;
}
/**
* Compares all Strings in an array and returns the initial sequence of
* characters that is common to all of them.
*
* For example,
* getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) -> "i am a "
*
*
* StringUtils.getCommonPrefix(null) = ""
* StringUtils.getCommonPrefix(new String[] {}) = ""
* StringUtils.getCommonPrefix(new String[] {"abc"}) = "abc"
* StringUtils.getCommonPrefix(new String[] {null, null}) = ""
* StringUtils.getCommonPrefix(new String[] {"", ""}) = ""
* StringUtils.getCommonPrefix(new String[] {"", null}) = ""
* StringUtils.getCommonPrefix(new String[] {"abc", null, null}) = ""
* StringUtils.getCommonPrefix(new String[] {null, null, "abc"}) = ""
* StringUtils.getCommonPrefix(new String[] {"", "abc"}) = ""
* StringUtils.getCommonPrefix(new String[] {"abc", ""}) = ""
* StringUtils.getCommonPrefix(new String[] {"abc", "abc"}) = "abc"
* StringUtils.getCommonPrefix(new String[] {"abc", "a"}) = "a"
* StringUtils.getCommonPrefix(new String[] {"ab", "abxyz"}) = "ab"
* StringUtils.getCommonPrefix(new String[] {"abcde", "abxyz"}) = "ab"
* StringUtils.getCommonPrefix(new String[] {"abcde", "xyz"}) = ""
* StringUtils.getCommonPrefix(new String[] {"xyz", "abcde"}) = ""
* StringUtils.getCommonPrefix(new String[] {"i am a machine", "i am a robot"}) = "i am a "
*
*
* @param strs array of String objects, entries may be null
* @return the initial sequence of characters that are common to all Strings
* in the array; empty String if the array is null, the elements are all null
* or if there is no common prefix.
* @since 2.4
*/
public static String getCommonPrefix(final String[] strs) {
if (strs == null || strs.length == 0) {
return StringUtils.EMPTY;
}
int smallestIndexOfDiff = StringUtils.indexOfDifference(strs);
if (smallestIndexOfDiff == StringUtils.INDEX_NOT_FOUND) {
// all strings were identical
if (strs[0] == null) {
return StringUtils.EMPTY;
}
return strs[0];
} else if (smallestIndexOfDiff == 0) {
// there were no common initial characters
return StringUtils.EMPTY;
} else {
// we found a common initial character sequence
return strs[0].substring(0, smallestIndexOfDiff);
}
}
// Misc
//-----------------------------------------------------------------------
/**
* 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).
*
* The previous implementation of the Levenshtein distance algorithm
* was from http://www.merriampark.com/ld.htm
*
* Chas Emerick has written an implementation in Java, which avoids an OutOfMemoryError
* which can occur when my Java implementation is used with very large strings.
* This implementation of the Levenshtein distance algorithm
* is from http://www.merriampark.com/ldjava.htm
*
*
* StringUtils.getLevenshteinDistance(null, *) = IllegalArgumentException
* StringUtils.getLevenshteinDistance(*, null) = IllegalArgumentException
* StringUtils.getLevenshteinDistance("","") = 0
* StringUtils.getLevenshteinDistance("","a") = 1
* StringUtils.getLevenshteinDistance("aaapppp", "") = 7
* StringUtils.getLevenshteinDistance("frog", "fog") = 1
* StringUtils.getLevenshteinDistance("fly", "ant") = 3
* StringUtils.getLevenshteinDistance("elephant", "hippo") = 7
* StringUtils.getLevenshteinDistance("hippo", "elephant") = 7
* StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8
* StringUtils.getLevenshteinDistance("hello", "hallo") = 1
*
*
* @param s the first String, must not be null
* @param t the second String, must not be null
* @return result distance
* @throws IllegalArgumentException if either String input null
*/
public static int getLevenshteinDistance(String s, String t) {
if (s == null || t == null) {
throw new IllegalArgumentException("Strings must not be null");
}
/*
The difference between this impl. and the previous is that, rather
than creating and retaining a matrix of size s.length()+1 by t.length()+1,
we maintain two single-dimensional arrays of length s.length()+1. The first, d,
is the 'current working' distance array that maintains the newest distance cost
counts as we iterate through the characters of String s. Each time we increment
the index of String t we are comparing, d is copied to p, the second int[]. Doing so
allows us to retain the previous cost counts as required by the algorithm (taking
the minimum of the cost count to the left, up one, and diagonally up and to the left
of the current cost count being calculated). (Note that the arrays aren't really
copied anymore, just switched...this is clearly much better than cloning an array
or doing a System.arraycopy() each time through the outer loop.)
Effectively, the difference between the two implementations is this one does not
cause an out of memory condition when calculating the LD over two very large strings.
*/
int n = s.length(); // length of s
int m = t.length(); // length of t
if (n == 0) {
return m;
} else if (m == 0) {
return n;
}
if (n > m) {
// swap the input strings to consume less memory
String tmp = s;
s = t;
t = tmp;
n = m;
m = t.length();
}
int p[] = new int[n + 1]; //'previous' cost array, horizontally
int d[] = new int[n + 1]; // cost array, horizontally
int _d[]; //placeholder to assist in swapping p and d
// indexes into strings s and t
int i; // iterates through s
int j; // iterates through t
char t_j; // jth character of t
int cost; // cost
for (i = 0; i <= n; i++) {
p[i] = i;
}
for (j = 1; j <= m; j++) {
t_j = t.charAt(j - 1);
d[0] = j;
for (i = 1; i <= n; i++) {
cost = s.charAt(i - 1) == t_j ? 0 : 1;
// minimum of cell to the left+1, to the top+1, diagonally left and up +cost
d[i] = Math.min(Math.min(d[i - 1] + 1, p[i] + 1), p[i - 1] + cost);
}
// copy current distance counts to 'previous row' distance counts
_d = p;
p = d;
d = _d;
}
// our last action in the above loop was to switch d and p, so p now
// actually has the most recent cost counts
return p[n];
}
// startsWith
//-----------------------------------------------------------------------
/**
* Check if a String starts with a specified prefix.
*
* nulls are handled without exceptions. Two null
* references are considered to be equal. The comparison is case sensitive.
*
*
* StringUtils.startsWith(null, null) = true
* StringUtils.startsWith(null, "abc") = false
* StringUtils.startsWith("abcdef", null) = false
* StringUtils.startsWith("abcdef", "abc") = true
* StringUtils.startsWith("ABCDEF", "abc") = false
*
*
* @see String#startsWith(String)
* @param str the String to check, may be null
* @param prefix the prefix to find, may be null
* @return true if the String starts with the prefix, case sensitive, or
* both null
* @since 2.4
*/
public static boolean startsWith(final String str, final String prefix) {
return StringUtils.startsWith(str, prefix, false);
}
/**
* Case insensitive check if a String starts with a specified prefix.
*
* nulls are handled without exceptions. Two null
* references are considered to be equal. The comparison is case insensitive.
*
*
* StringUtils.startsWithIgnoreCase(null, null) = true
* StringUtils.startsWithIgnoreCase(null, "abc") = false
* StringUtils.startsWithIgnoreCase("abcdef", null) = false
* StringUtils.startsWithIgnoreCase("abcdef", "abc") = true
* StringUtils.startsWithIgnoreCase("ABCDEF", "abc") = true
*
*
* @see String#startsWith(String)
* @param str the String to check, may be null
* @param prefix the prefix to find, may be null
* @return true if the String starts with the prefix, case insensitive, or
* both null
* @since 2.4
*/
public static boolean startsWithIgnoreCase(final String str, final String prefix) {
return StringUtils.startsWith(str, prefix, true);
}
/**
* Check if a String starts with a specified prefix (optionally case insensitive).
*
* @see String#startsWith(String)
* @param str the String to check, may be null
* @param prefix the prefix to find, may be null
* @param ignoreCase inidicates whether the compare should ignore case
* (case insensitive) or not.
* @return true if the String starts with the prefix or
* both null
*/
private static boolean startsWith(final String str, final String prefix, final boolean ignoreCase) {
if (str == null || prefix == null) {
return str == null && prefix == null;
}
if (prefix.length() > str.length()) {
return false;
}
return str.regionMatches(ignoreCase, 0, prefix, 0, prefix.length());
}
/**
* Check if a String starts with any of an array of specified strings.
*
*
* StringUtils.startsWithAny(null, null) = false
* StringUtils.startsWithAny(null, new String[] {"abc"}) = false
* StringUtils.startsWithAny("abcxyz", null) = false
* StringUtils.startsWithAny("abcxyz", new String[] {""}) = false
* StringUtils.startsWithAny("abcxyz", new String[] {"abc"}) = true
* StringUtils.startsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
*
*
* @see #startsWith(String, String)
* @param string the String to check, may be null
* @param searchStrings the Strings to find, may be null or empty
* @return true if the String starts with any of the the prefixes, case insensitive, or
* both null
* @since 2.5
*/
public static boolean startsWithAny(final String string, final String[] searchStrings) {
if (StringUtils.isEmpty(string) || ArrayUtils.isEmpty(searchStrings)) {
return false;
}
for (String searchString : searchStrings) {
if (StringUtils.startsWith(string, searchString)) {
return true;
}
}
return false;
}
// endsWith
//-----------------------------------------------------------------------
/**
* Check if a String ends with a specified suffix.
*
* nulls are handled without exceptions. Two null
* references are considered to be equal. The comparison is case sensitive.
*
*
* StringUtils.endsWith(null, null) = true
* StringUtils.endsWith(null, "def") = false
* StringUtils.endsWith("abcdef", null) = false
* StringUtils.endsWith("abcdef", "def") = true
* StringUtils.endsWith("ABCDEF", "def") = false
* StringUtils.endsWith("ABCDEF", "cde") = false
*
*
* @see String#endsWith(String)
* @param str the String to check, may be null
* @param suffix the suffix to find, may be null
* @return true if the String ends with the suffix, case sensitive, or
* both null
* @since 2.4
*/
public static boolean endsWith(final String str, final String suffix) {
return StringUtils.endsWith(str, suffix, false);
}
/**
* Case insensitive check if a String ends with a specified suffix.
*
* nulls are handled without exceptions. Two null
* references are considered to be equal. The comparison is case insensitive.
*
*
* StringUtils.endsWithIgnoreCase(null, null) = true
* StringUtils.endsWithIgnoreCase(null, "def") = false
* StringUtils.endsWithIgnoreCase("abcdef", null) = false
* StringUtils.endsWithIgnoreCase("abcdef", "def") = true
* StringUtils.endsWithIgnoreCase("ABCDEF", "def") = true
* StringUtils.endsWithIgnoreCase("ABCDEF", "cde") = false
*
*
* @see String#endsWith(String)
* @param str the String to check, may be null
* @param suffix the suffix to find, may be null
* @return true if the String ends with the suffix, case insensitive, or
* both null
* @since 2.4
*/
public static boolean endsWithIgnoreCase(final String str, final String suffix) {
return StringUtils.endsWith(str, suffix, true);
}
/**
* Check if a String ends with a specified suffix (optionally case insensitive).
*
* @see String#endsWith(String)
* @param str the String to check, may be null
* @param suffix the suffix to find, may be null
* @param ignoreCase inidicates whether the compare should ignore case
* (case insensitive) or not.
* @return true if the String starts with the prefix or
* both null
*/
private static boolean endsWith(final String str, final String suffix, final boolean ignoreCase) {
if (str == null || suffix == null) {
return str == null && suffix == null;
}
if (suffix.length() > str.length()) {
return false;
}
int strOffset = str.length() - suffix.length();
return str.regionMatches(ignoreCase, strOffset, suffix, 0, suffix.length());
}
/**
*
* Similar to http://www.w3.org/TR/xpath/#function-normalize
* -space
*
*
* The function returns the argument string with whitespace normalized by using
* {@link #trim(String)} to remove leading and trailing whitespace
* and then replacing sequences of whitespace characters by a single space.
*
* In XML Whitespace characters are the same as those allowed by the S production, which is S ::= (#x20 | #x9 | #xD | #xA)+
*
* See Java's {@link Character#isWhitespace(char)} for which characters are considered whitespace.
*
* The difference is that Java's whitespace includes vertical tab and form feed, which this functional will also
* normalize. Additonally {@link #trim(String)} removes control characters (char <= 32) from both
* ends of this String.
*
*
* @see Character#isWhitespace(char)
* @see #trim(String)
* @see
* http://www.w3.org/TR/xpath/#function-normalize-space
* @param str the source String to normalize whitespaces from, may be null
* @return the modified string with whitespace normalized, null if null String input
*
* @since 2.6
*/
public static String normalizeSpace(String str) {
str = StringUtils.strip(str);
if (str == null || str.length() <= 2) {
return str;
}
StringBuilder b = new StringBuilder(str.length());
for (int i = 0; i < str.length(); i++) {
char c = str.charAt(i);
if (Character.isWhitespace(c)) {
if (i > 0 && !Character.isWhitespace(str.charAt(i - 1))) {
b.append(' ');
}
} else {
b.append(c);
}
}
return b.toString();
}
/**
* Check if a String ends with any of an array of specified strings.
*
*
* StringUtils.endsWithAny(null, null) = false
* StringUtils.endsWithAny(null, new String[] {"abc"}) = false
* StringUtils.endsWithAny("abcxyz", null) = false
* StringUtils.endsWithAny("abcxyz", new String[] {""}) = true
* StringUtils.endsWithAny("abcxyz", new String[] {"xyz"}) = true
* StringUtils.endsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
*
*
* @param string the String to check, may be null
* @param searchStrings the Strings to find, may be null or empty
* @return true if the String ends with any of the the prefixes, case insensitive, or
* both null
* @since 2.6
*/
public static boolean endsWithAny(final String string, final String[] searchStrings) {
if (StringUtils.isEmpty(string) || ArrayUtils.isEmpty(searchStrings)) {
return false;
}
for (String searchString : searchStrings) {
if (StringUtils.endsWith(string, searchString)) {
return true;
}
}
return false;
}
/**
* 转换首字母大写。
*
* StringUtils.firstCharToUpperCase(null) = null
* StringUtils.firstCharToUpperCase("") = ""
* StringUtils.firstCharToUpperCase("abc") = "Abc"
* StringUtils.firstCharToUpperCase("Abc") = "Abc"
* StringUtils.firstCharToUpperCase("ABC") = "ABC"
*
*/
public static String firstCharToUpperCase(final String value) {
if (StringUtils.isBlank(value)) {
return value;
}
StringBuilder sb = new StringBuilder(value);
char firstChar = sb.charAt(0);
sb.delete(0, 1);
sb.insert(0, (char) (firstChar >= 97 ? firstChar - 32 : firstChar));
return sb.toString();
}
/**
* 转换首字母小写。
*
* StringUtils.firstCharToLowerCase(null) = null
* StringUtils.firstCharToLowerCase("") = ""
* StringUtils.firstCharToLowerCase("abc") = "abc"
* StringUtils.firstCharToLowerCase("Abc") = "abc"
* StringUtils.firstCharToLowerCase("ABC") = "aBC"
*
*/
public static String firstCharToLowerCase(final String value) {
if (StringUtils.isBlank(value)) {
return value;
}
StringBuffer sb = new StringBuffer(value);
char firstChar = sb.charAt(0);
sb.delete(0, 1);
sb.insert(0, (char) (firstChar <= 90 ? firstChar + 32 : firstChar));
return sb.toString();
}
/**
* 执行字符串匹配。
*
* StringUtils.equalsBlankIgnoreCase(null,"") = true
* StringUtils.equalsBlankIgnoreCase("","") = true
* StringUtils.equalsBlankIgnoreCase(" ","") = true
* StringUtils.equalsBlankIgnoreCase(" ",null) = true
* StringUtils.equalsBlankIgnoreCase("bob","") = false
* StringUtils.equalsBlankIgnoreCase(" bob ","bob") = true
*
*/
public static boolean equalsBlankIgnoreCase(final String str1, final String str2) {
return StringUtils.equalsIgnoreCase(StringUtils.trimToEmpty(str1), StringUtils.trimToEmpty(str2));
}
/**
* 按照某个字符组装固定长度的的字符串。
*
* StringUtils.fixedString(' ',4) = " "
* StringUtils.fixedString(' ',2) = " "
* StringUtils.fixedString('A',2) = "AA"
* StringUtils.fixedString('A',0) = ""
* StringUtils.fixedString('A',-1) = null
*
*/
public static String fixedString(final char c, final int length) {
if (length < 0) {
return "";
}
if (length == 0) {
return "";
}
//
char[] chars = new char[length];
Arrays.fill(chars, c);
return new String(chars);
}
/* ------------------------------------------------------------ */
private static final char[] escapes = new char[32];
static {
Arrays.fill(escapes, (char) 0xFFFF);
escapes['\b'] = 'b';
escapes['\t'] = 't';
escapes['\n'] = 'n';
escapes['\f'] = 'f';
escapes['\r'] = 'r';
}
/** Quote a string into an Appendable.
* The characters ", \, \n, \r, \t, \f and \b are escaped
* @param input The String to quote.
*/
public static String quote(String input) {
StringBuilder buffer = new StringBuilder();
quote(buffer, input);
return buffer.toString();
}
public static void quote(Appendable buffer, String input) {
try {
buffer.append('"');
for (int i = 0; i < input.length(); ++i) {
char c = input.charAt(i);
if (c >= 32) {
if (c == '"' || c == '\\')
buffer.append('\\');
buffer.append(c);
} else {
char escape = escapes[c];
if (escape == 0xFFFF) {
// Unicode escape
buffer.append('\\').append('u').append('0').append('0');
if (c < 0x10)
buffer.append('0');
buffer.append(Integer.toString(c, 16));
} else {
buffer.append('\\').append(escape);
}
}
}
buffer.append('"');
} catch (IOException x) {
throw new RuntimeException(x);
}
}
}