Class StringUtils
- java.lang.Object
-
- org.apache.commons.lang3.StringUtils
-
public class StringUtils extends java.lang.Object
Operations on
String
that arenull
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
- AppendIfMissing - appends a suffix to the end of the String if not present
- PrependIfMissing - prepends a prefix to the start of the String if not present
- 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
- LevenshteinDistance - 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
Character.isWhitespace(char)
- trim - the characters <= 32 as in
String.trim()
StringUtils
handlesnull
input Strings quietly. That is to say that anull
input will returnnull
. Where aboolean
orint
is being returned details vary by method.A side effect of the
null
handling is that aNullPointerException
should be considered a bug inStringUtils
.Methods in this class give sample code to explain their operation. The symbol
*
is used to indicate any input includingnull
.#ThreadSafe#
- Since:
- 1.0
- Version:
- $Id: StringUtils.java 1648067 2014-12-27 16:45:42Z britter $
- See Also:
String
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
CR
A String for carriage return CR ("\r").static java.lang.String
EMPTY
The empty String""
.static int
INDEX_NOT_FOUND
Represents a failed index search.static java.lang.String
LF
A String for linefeed LF ("\n").static java.lang.String
SPACE
A String for a space character.
-
Constructor Summary
Constructors Constructor Description StringUtils()
StringUtils
instances should NOT be constructed in standard programming.
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static java.lang.String
abbreviate(java.lang.String str, int maxWidth)
Abbreviates a String using ellipses.static java.lang.String
abbreviate(java.lang.String str, int offset, int maxWidth)
Abbreviates a String using ellipses.static java.lang.String
abbreviateMiddle(java.lang.String str, java.lang.String middle, int length)
Abbreviates a String to the length passed, replacing the middle characters with the supplied replacement String.static java.lang.String
appendIfMissing(java.lang.String str, java.lang.CharSequence suffix, java.lang.CharSequence... suffixes)
Appends the suffix to the end of the string if the string does not already end with any the suffixes.static java.lang.String
appendIfMissingIgnoreCase(java.lang.String str, java.lang.CharSequence suffix, java.lang.CharSequence... suffixes)
Appends the suffix to the end of the string if the string does not already end, case insensitive, with any of the suffixes.static java.lang.String
capitalize(java.lang.String str)
Capitalizes a String changing the first letter to title case as perCharacter.toTitleCase(char)
.static java.lang.String
center(java.lang.String str, int size)
Centers a String in a larger String of sizesize
using the space character (' ').static java.lang.String
center(java.lang.String str, int size, char padChar)
Centers a String in a larger String of sizesize
.static java.lang.String
center(java.lang.String str, int size, java.lang.String padStr)
Centers a String in a larger String of sizesize
.static java.lang.String
chomp(java.lang.String str)
Removes one newline from end of a String if it's there, otherwise leave it alone.static java.lang.String
chomp(java.lang.String str, java.lang.String separator)
Deprecated.This feature will be removed in Lang 4.0, useremoveEnd(String, String)
insteadstatic java.lang.String
chop(java.lang.String str)
Remove the last character from a String.static boolean
contains(java.lang.CharSequence seq, int searchChar)
Checks if CharSequence contains a search character, handlingnull
.static boolean
contains(java.lang.CharSequence seq, java.lang.CharSequence searchSeq)
Checks if CharSequence contains a search CharSequence, handlingnull
.static boolean
containsAny(java.lang.CharSequence cs, char... searchChars)
Checks if the CharSequence contains any character in the given set of characters.static boolean
containsAny(java.lang.CharSequence cs, java.lang.CharSequence searchChars)
Checks if the CharSequence contains any character in the given set of characters.static boolean
containsAny(java.lang.CharSequence cs, java.lang.CharSequence... searchCharSequences)
Checks if the CharSequence contains any of the CharSequences in the given array.static boolean
containsIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr)
Checks if CharSequence contains a search CharSequence irrespective of case, handlingnull
.static boolean
containsNone(java.lang.CharSequence cs, char... searchChars)
Checks that the CharSequence does not contain certain characters.static boolean
containsNone(java.lang.CharSequence cs, java.lang.String invalidChars)
Checks that the CharSequence does not contain certain characters.static boolean
containsOnly(java.lang.CharSequence cs, char... valid)
Checks if the CharSequence contains only certain characters.static boolean
containsOnly(java.lang.CharSequence cs, java.lang.String validChars)
Checks if the CharSequence contains only certain characters.static boolean
containsWhitespace(java.lang.CharSequence seq)
Check whether the given CharSequence contains any whitespace characters.static int
countMatches(java.lang.CharSequence str, char ch)
Counts how many times the char appears in the given string.static int
countMatches(java.lang.CharSequence str, java.lang.CharSequence sub)
Counts how many times the substring appears in the larger string.static <T extends java.lang.CharSequence>
TdefaultIfBlank(T str, T defaultStr)
Returns either the passed in CharSequence, or if the CharSequence is whitespace, empty ("") ornull
, the value ofdefaultStr
.static <T extends java.lang.CharSequence>
TdefaultIfEmpty(T str, T defaultStr)
Returns either the passed in CharSequence, or if the CharSequence is empty ornull
, the value ofdefaultStr
.static java.lang.String
defaultString(java.lang.String str)
Returns either the passed in String, or if the String isnull
, an empty String ("").static java.lang.String
defaultString(java.lang.String str, java.lang.String defaultStr)
Returns either the passed in String, or if the String isnull
, the value ofdefaultStr
.static java.lang.String
deleteWhitespace(java.lang.String str)
Deletes all whitespaces from a String as defined byCharacter.isWhitespace(char)
.static java.lang.String
difference(java.lang.String str1, java.lang.String str2)
Compares two Strings, and returns the portion where they differ.static boolean
endsWith(java.lang.CharSequence str, java.lang.CharSequence suffix)
Check if a CharSequence ends with a specified suffix.static boolean
endsWithAny(java.lang.CharSequence string, java.lang.CharSequence... searchStrings)
Check if a CharSequence ends with any of an array of specified strings.static boolean
endsWithIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence suffix)
Case insensitive check if a CharSequence ends with a specified suffix.static boolean
equals(java.lang.CharSequence cs1, java.lang.CharSequence cs2)
Compares two CharSequences, returningtrue
if they represent equal sequences of characters.static boolean
equalsIgnoreCase(java.lang.CharSequence str1, java.lang.CharSequence str2)
Compares two CharSequences, returningtrue
if they represent equal sequences of characters, ignoring case.static java.lang.String
getCommonPrefix(java.lang.String... strs)
Compares all Strings in an array and returns the initial sequence of characters that is common to all of them.static int
getFuzzyDistance(java.lang.CharSequence term, java.lang.CharSequence query, java.util.Locale locale)
Find the Fuzzy Distance which indicates the similarity score between two Strings.static double
getJaroWinklerDistance(java.lang.CharSequence first, java.lang.CharSequence second)
Find the Jaro Winkler Distance which indicates the similarity score between two Strings.static int
getLevenshteinDistance(java.lang.CharSequence s, java.lang.CharSequence t)
Find the Levenshtein distance between two Strings.static int
getLevenshteinDistance(java.lang.CharSequence s, java.lang.CharSequence t, int threshold)
Find the Levenshtein distance between two Strings if it's less than or equal to a given threshold.static int
indexOf(java.lang.CharSequence seq, int searchChar)
Finds the first index within a CharSequence, handlingnull
.static int
indexOf(java.lang.CharSequence seq, int searchChar, int startPos)
Finds the first index within a CharSequence from a start position, handlingnull
.static int
indexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq)
Finds the first index within a CharSequence, handlingnull
.static int
indexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq, int startPos)
Finds the first index within a CharSequence, handlingnull
.static int
indexOfAny(java.lang.CharSequence cs, char... searchChars)
Search a CharSequence to find the first index of any character in the given set of characters.static int
indexOfAny(java.lang.CharSequence str, java.lang.CharSequence... searchStrs)
Find the first index of any of a set of potential substrings.static int
indexOfAny(java.lang.CharSequence cs, java.lang.String searchChars)
Search a CharSequence to find the first index of any character in the given set of characters.static int
indexOfAnyBut(java.lang.CharSequence cs, char... searchChars)
Searches a CharSequence to find the first index of any character not in the given set of characters.static int
indexOfAnyBut(java.lang.CharSequence seq, java.lang.CharSequence searchChars)
Search a CharSequence to find the first index of any character not in the given set of characters.static int
indexOfDifference(java.lang.CharSequence... css)
Compares all CharSequences in an array and returns the index at which the CharSequences begin to differ.static int
indexOfDifference(java.lang.CharSequence cs1, java.lang.CharSequence cs2)
Compares two CharSequences, and returns the index at which the CharSequences begin to differ.static int
indexOfIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr)
Case in-sensitive find of the first index within a CharSequence.static int
indexOfIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr, int startPos)
Case in-sensitive find of the first index within a CharSequence from the specified position.static boolean
isAllLowerCase(java.lang.CharSequence cs)
Checks if the CharSequence contains only lowercase characters.static boolean
isAllUpperCase(java.lang.CharSequence cs)
Checks if the CharSequence contains only uppercase characters.static boolean
isAlpha(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode letters.static boolean
isAlphanumeric(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode letters or digits.static boolean
isAlphanumericSpace(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode letters, digits or space (' '
).static boolean
isAlphaSpace(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode letters and space (' ').static boolean
isAnyBlank(java.lang.CharSequence... css)
Checks if any one of the CharSequences are blank ("") or null and not whitespace only..static boolean
isAnyEmpty(java.lang.CharSequence... css)
Checks if any one of the CharSequences are empty ("") or null.static boolean
isAsciiPrintable(java.lang.CharSequence cs)
Checks if the CharSequence contains only ASCII printable characters.static boolean
isBlank(java.lang.CharSequence cs)
Checks if a CharSequence is whitespace, empty ("") or null.static boolean
isEmpty(java.lang.CharSequence cs)
Checks if a CharSequence is empty ("") or null.static boolean
isNoneBlank(java.lang.CharSequence... css)
Checks if none of the CharSequences are blank ("") or null and whitespace only..static boolean
isNoneEmpty(java.lang.CharSequence... css)
Checks if none of the CharSequences are empty ("") or null.static boolean
isNotBlank(java.lang.CharSequence cs)
Checks if a CharSequence is not empty (""), not null and not whitespace only.static boolean
isNotEmpty(java.lang.CharSequence cs)
Checks if a CharSequence is not empty ("") and not null.static boolean
isNumeric(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode digits.static boolean
isNumericSpace(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode digits or space (' '
).static boolean
isWhitespace(java.lang.CharSequence cs)
Checks if the CharSequence contains only whitespace.static java.lang.String
join(byte[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(byte[] array, char separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(char[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(char[] array, char separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(double[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(double[] array, char separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(float[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(float[] array, char separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(int[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(int[] array, char separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(long[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(long[] array, char separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(short[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(short[] array, char separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(java.lang.Iterable<?> iterable, char separator)
Joins the elements of the providedIterable
into a single String containing the provided elements.static java.lang.String
join(java.lang.Iterable<?> iterable, java.lang.String separator)
Joins the elements of the providedIterable
into a single String containing the provided elements.static java.lang.String
join(java.lang.Object[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(java.lang.Object[] array, char separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(java.lang.Object[] array, java.lang.String separator)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(java.lang.Object[] array, java.lang.String separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.static java.lang.String
join(java.util.Iterator<?> iterator, char separator)
Joins the elements of the providedIterator
into a single String containing the provided elements.static java.lang.String
join(java.util.Iterator<?> iterator, java.lang.String separator)
Joins the elements of the providedIterator
into a single String containing the provided elements.static <T> java.lang.String
join(T... elements)
Joins the elements of the provided array into a single String containing the provided list of elements.static int
lastIndexOf(java.lang.CharSequence seq, int searchChar)
Finds the last index within a CharSequence, handlingnull
.static int
lastIndexOf(java.lang.CharSequence seq, int searchChar, int startPos)
Finds the last index within a CharSequence from a start position, handlingnull
.static int
lastIndexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq)
Finds the last index within a CharSequence, handlingnull
.static int
lastIndexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq, int startPos)
Finds the last index within a CharSequence, handlingnull
.static int
lastIndexOfAny(java.lang.CharSequence str, java.lang.CharSequence... searchStrs)
Find the latest index of any of a set of potential substrings.static int
lastIndexOfIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr)
Case in-sensitive find of the last index within a CharSequence.static int
lastIndexOfIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr, int startPos)
Case in-sensitive find of the last index within a CharSequence from the specified position.static int
lastOrdinalIndexOf(java.lang.CharSequence str, java.lang.CharSequence searchStr, int ordinal)
Finds the n-th last index within a String, handlingnull
.static java.lang.String
left(java.lang.String str, int len)
Gets the leftmostlen
characters of a String.static java.lang.String
leftPad(java.lang.String str, int size)
Left pad a String with spaces (' ').static java.lang.String
leftPad(java.lang.String str, int size, char padChar)
Left pad a String with a specified character.static java.lang.String
leftPad(java.lang.String str, int size, java.lang.String padStr)
Left pad a String with a specified String.static int
length(java.lang.CharSequence cs)
Gets a CharSequence length or0
if the CharSequence isnull
.static java.lang.String
lowerCase(java.lang.String str)
Converts a String to lower case as perString.toLowerCase()
.static java.lang.String
lowerCase(java.lang.String str, java.util.Locale locale)
Converts a String to lower case as perString.toLowerCase(Locale)
.static java.lang.String
mid(java.lang.String str, int pos, int len)
Getslen
characters from the middle of a String.static java.lang.String
normalizeSpace(java.lang.String str)
static int
ordinalIndexOf(java.lang.CharSequence str, java.lang.CharSequence searchStr, int ordinal)
Finds the n-th index within a CharSequence, handlingnull
.static java.lang.String
overlay(java.lang.String str, java.lang.String overlay, int start, int end)
Overlays part of a String with another String.static java.lang.String
prependIfMissing(java.lang.String str, java.lang.CharSequence prefix, java.lang.CharSequence... prefixes)
Prepends the prefix to the start of the string if the string does not already start with any of the prefixes.static java.lang.String
prependIfMissingIgnoreCase(java.lang.String str, java.lang.CharSequence prefix, java.lang.CharSequence... prefixes)
Prepends the prefix to the start of the string if the string does not already start, case insensitive, with any of the prefixes.static java.lang.String
remove(java.lang.String str, char remove)
Removes all occurrences of a character from within the source string.static java.lang.String
remove(java.lang.String str, java.lang.String remove)
Removes all occurrences of a substring from within the source string.static java.lang.String
removeEnd(java.lang.String str, java.lang.String remove)
Removes a substring only if it is at the end of a source string, otherwise returns the source string.static java.lang.String
removeEndIgnoreCase(java.lang.String str, java.lang.String remove)
Case insensitive removal of a substring if it is at the end of a source string, otherwise returns the source string.static java.lang.String
removePattern(java.lang.String source, java.lang.String regex)
Removes each substring of the source String that matches the given regular expression using the DOTALL option.static java.lang.String
removeStart(java.lang.String str, java.lang.String remove)
Removes a substring only if it is at the beginning of a source string, otherwise returns the source string.static java.lang.String
removeStartIgnoreCase(java.lang.String str, java.lang.String remove)
Case insensitive removal of a substring if it is at the beginning of a source string, otherwise returns the source string.static java.lang.String
repeat(char ch, int repeat)
Returns padding using the specified delimiter repeated to a given length.static java.lang.String
repeat(java.lang.String str, int repeat)
Repeat a Stringrepeat
times to form a new String.static java.lang.String
repeat(java.lang.String str, java.lang.String separator, int repeat)
Repeat a Stringrepeat
times to form a new String, with a String separator injected each time.static java.lang.String
replace(java.lang.String text, java.lang.String searchString, java.lang.String replacement)
Replaces all occurrences of a String within another String.static java.lang.String
replace(java.lang.String text, java.lang.String searchString, java.lang.String replacement, int max)
Replaces a String with another String inside a larger String, for the firstmax
values of the search String.static java.lang.String
replaceChars(java.lang.String str, char searchChar, char replaceChar)
Replaces all occurrences of a character in a String with another.static java.lang.String
replaceChars(java.lang.String str, java.lang.String searchChars, java.lang.String replaceChars)
Replaces multiple characters in a String in one go.static java.lang.String
replaceEach(java.lang.String text, java.lang.String[] searchList, java.lang.String[] replacementList)
Replaces all occurrences of Strings within another String.static java.lang.String
replaceEachRepeatedly(java.lang.String text, java.lang.String[] searchList, java.lang.String[] replacementList)
Replaces all occurrences of Strings within another String.static java.lang.String
replaceOnce(java.lang.String text, java.lang.String searchString, java.lang.String replacement)
Replaces a String with another String inside a larger String, once.static java.lang.String
replacePattern(java.lang.String source, java.lang.String regex, java.lang.String replacement)
Replaces each substring of the source String that matches the given regular expression with the given replacement using thePattern.DOTALL
option.static java.lang.String
reverse(java.lang.String str)
Reverses a String as perStringBuilder.reverse()
.static java.lang.String
reverseDelimited(java.lang.String str, char separatorChar)
Reverses a String that is delimited by a specific character.static java.lang.String
right(java.lang.String str, int len)
Gets the rightmostlen
characters of a String.static java.lang.String
rightPad(java.lang.String str, int size)
Right pad a String with spaces (' ').static java.lang.String
rightPad(java.lang.String str, int size, char padChar)
Right pad a String with a specified character.static java.lang.String
rightPad(java.lang.String str, int size, java.lang.String padStr)
Right pad a String with a specified String.static java.lang.String[]
split(java.lang.String str)
Splits the provided text into an array, using whitespace as the separator.static java.lang.String[]
split(java.lang.String str, char separatorChar)
Splits the provided text into an array, separator specified.static java.lang.String[]
split(java.lang.String str, java.lang.String separatorChars)
Splits the provided text into an array, separators specified.static java.lang.String[]
split(java.lang.String str, java.lang.String separatorChars, int max)
Splits the provided text into an array with a maximum length, separators specified.static java.lang.String[]
splitByCharacterType(java.lang.String str)
Splits a String by Character type as returned byjava.lang.Character.getType(char)
.static java.lang.String[]
splitByCharacterTypeCamelCase(java.lang.String str)
Splits a String by Character type as returned byjava.lang.Character.getType(char)
.static java.lang.String[]
splitByWholeSeparator(java.lang.String str, java.lang.String separator)
Splits the provided text into an array, separator string specified.static java.lang.String[]
splitByWholeSeparator(java.lang.String str, java.lang.String separator, int max)
Splits the provided text into an array, separator string specified.static java.lang.String[]
splitByWholeSeparatorPreserveAllTokens(java.lang.String str, java.lang.String separator)
Splits the provided text into an array, separator string specified.static java.lang.String[]
splitByWholeSeparatorPreserveAllTokens(java.lang.String str, java.lang.String separator, int max)
Splits the provided text into an array, separator string specified.static java.lang.String[]
splitPreserveAllTokens(java.lang.String str)
Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators.static java.lang.String[]
splitPreserveAllTokens(java.lang.String str, char separatorChar)
Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators.static java.lang.String[]
splitPreserveAllTokens(java.lang.String str, java.lang.String separatorChars)
Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators.static java.lang.String[]
splitPreserveAllTokens(java.lang.String str, java.lang.String separatorChars, int max)
Splits the provided text into an array with a maximum length, separators specified, preserving all tokens, including empty tokens created by adjacent separators.static boolean
startsWith(java.lang.CharSequence str, java.lang.CharSequence prefix)
Check if a CharSequence starts with a specified prefix.static boolean
startsWithAny(java.lang.CharSequence string, java.lang.CharSequence... searchStrings)
Check if a CharSequence starts with any of an array of specified strings.static boolean
startsWithIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence prefix)
Case insensitive check if a CharSequence starts with a specified prefix.static java.lang.String
strip(java.lang.String str)
Strips whitespace from the start and end of a String.static java.lang.String
strip(java.lang.String str, java.lang.String stripChars)
Strips any of a set of characters from the start and end of a String.static java.lang.String
stripAccents(java.lang.String input)
Removes diacritics (~= accents) from a string.static java.lang.String[]
stripAll(java.lang.String... strs)
Strips whitespace from the start and end of every String in an array.static java.lang.String[]
stripAll(java.lang.String[] strs, java.lang.String stripChars)
Strips any of a set of characters from the start and end of every String in an array.static java.lang.String
stripEnd(java.lang.String str, java.lang.String stripChars)
Strips any of a set of characters from the end of a String.static java.lang.String
stripStart(java.lang.String str, java.lang.String stripChars)
Strips any of a set of characters from the start of a String.static java.lang.String
stripToEmpty(java.lang.String str)
Strips whitespace from the start and end of a String returning an empty String ifnull
input.static java.lang.String
stripToNull(java.lang.String str)
Strips whitespace from the start and end of a String returningnull
if the String is empty ("") after the strip.static java.lang.String
substring(java.lang.String str, int start)
Gets a substring from the specified String avoiding exceptions.static java.lang.String
substring(java.lang.String str, int start, int end)
Gets a substring from the specified String avoiding exceptions.static java.lang.String
substringAfter(java.lang.String str, java.lang.String separator)
Gets the substring after the first occurrence of a separator.static java.lang.String
substringAfterLast(java.lang.String str, java.lang.String separator)
Gets the substring after the last occurrence of a separator.static java.lang.String
substringBefore(java.lang.String str, java.lang.String separator)
Gets the substring before the first occurrence of a separator.static java.lang.String
substringBeforeLast(java.lang.String str, java.lang.String separator)
Gets the substring before the last occurrence of a separator.static java.lang.String
substringBetween(java.lang.String str, java.lang.String tag)
Gets the String that is nested in between two instances of the same String.static java.lang.String
substringBetween(java.lang.String str, java.lang.String open, java.lang.String close)
Gets the String that is nested in between two Strings.static java.lang.String[]
substringsBetween(java.lang.String str, java.lang.String open, java.lang.String close)
Searches a String for substrings delimited by a start and end tag, returning all matching substrings in an array.static java.lang.String
swapCase(java.lang.String str)
Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.static java.lang.String
toEncodedString(byte[] bytes, java.nio.charset.Charset charset)
Converts abyte[]
to a String using the specified character encoding.static java.lang.String
toString(byte[] bytes, java.lang.String charsetName)
Deprecated.usetoEncodedString(byte[], Charset)
instead of String constants in your codestatic java.lang.String
trim(java.lang.String str)
Removes control characters (char <= 32) from both ends of this String, handlingnull
by returningnull
.static java.lang.String
trimToEmpty(java.lang.String str)
Removes control characters (char <= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if it isnull
.static java.lang.String
trimToNull(java.lang.String str)
Removes control characters (char <= 32) from both ends of this String returningnull
if the String is empty ("") after the trim or if it isnull
.static java.lang.String
uncapitalize(java.lang.String str)
Uncapitalizes a String changing the first letter to title case as perCharacter.toLowerCase(char)
.static java.lang.String
upperCase(java.lang.String str)
Converts a String to upper case as perString.toUpperCase()
.static java.lang.String
upperCase(java.lang.String str, java.util.Locale locale)
Converts a String to upper case as perString.toUpperCase(Locale)
.static java.lang.String
wrap(java.lang.String str, char wrapWith)
Wraps a string with a char.static java.lang.String
wrap(java.lang.String str, java.lang.String wrapWith)
Wraps a String with another String.
-
-
-
Field Detail
-
SPACE
public static final java.lang.String SPACE
A String for a space character.- Since:
- 3.2
- See Also:
- Constant Field Values
-
EMPTY
public static final java.lang.String EMPTY
The empty String""
.- Since:
- 2.0
- See Also:
- Constant Field Values
-
LF
public static final java.lang.String LF
A String for linefeed LF ("\n").- Since:
- 3.2
- See Also:
- JLF: Escape Sequences for Character and String Literals, Constant Field Values
-
CR
public static final java.lang.String CR
A String for carriage return CR ("\r").- Since:
- 3.2
- See Also:
- JLF: Escape Sequences for Character and String Literals, Constant Field Values
-
INDEX_NOT_FOUND
public static final int INDEX_NOT_FOUND
Represents a failed index search.- Since:
- 2.1
- See Also:
- Constant Field Values
-
-
Method Detail
-
isEmpty
public static boolean isEmpty(java.lang.CharSequence cs)
Checks if a CharSequence 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 CharSequence. That functionality is available in isBlank().
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if the CharSequence is empty or null- Since:
- 3.0 Changed signature from isEmpty(String) to isEmpty(CharSequence)
-
isNotEmpty
public static boolean isNotEmpty(java.lang.CharSequence cs)
Checks if a CharSequence is not empty ("") and not null.
StringUtils.isNotEmpty(null) = false StringUtils.isNotEmpty("") = false StringUtils.isNotEmpty(" ") = true StringUtils.isNotEmpty("bob") = true StringUtils.isNotEmpty(" bob ") = true
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if the CharSequence is not empty and not null- Since:
- 3.0 Changed signature from isNotEmpty(String) to isNotEmpty(CharSequence)
-
isAnyEmpty
public static boolean isAnyEmpty(java.lang.CharSequence... css)
Checks if any one of the CharSequences are empty ("") or null.
StringUtils.isAnyEmpty(null) = true StringUtils.isAnyEmpty(null, "foo") = true StringUtils.isAnyEmpty("", "bar") = true StringUtils.isAnyEmpty("bob", "") = true StringUtils.isAnyEmpty(" bob ", null) = true StringUtils.isAnyEmpty(" ", "bar") = false StringUtils.isAnyEmpty("foo", "bar") = false
- Parameters:
css
- the CharSequences to check, may be null or empty- Returns:
true
if any of the CharSequences are empty or null- Since:
- 3.2
-
isNoneEmpty
public static boolean isNoneEmpty(java.lang.CharSequence... css)
Checks if none of the CharSequences are empty ("") or null.
StringUtils.isNoneEmpty(null) = false StringUtils.isNoneEmpty(null, "foo") = false StringUtils.isNoneEmpty("", "bar") = false StringUtils.isNoneEmpty("bob", "") = false StringUtils.isNoneEmpty(" bob ", null) = false StringUtils.isNoneEmpty(" ", "bar") = true StringUtils.isNoneEmpty("foo", "bar") = true
- Parameters:
css
- the CharSequences to check, may be null or empty- Returns:
true
if none of the CharSequences are empty or null- Since:
- 3.2
-
isBlank
public static boolean isBlank(java.lang.CharSequence cs)
Checks if a CharSequence is whitespace, empty ("") or null.
StringUtils.isBlank(null) = true StringUtils.isBlank("") = true StringUtils.isBlank(" ") = true StringUtils.isBlank("bob") = false StringUtils.isBlank(" bob ") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if the CharSequence is null, empty or whitespace- Since:
- 2.0, 3.0 Changed signature from isBlank(String) to isBlank(CharSequence)
-
isNotBlank
public static boolean isNotBlank(java.lang.CharSequence cs)
Checks if a CharSequence is not empty (""), not null and not whitespace only.
StringUtils.isNotBlank(null) = false StringUtils.isNotBlank("") = false StringUtils.isNotBlank(" ") = false StringUtils.isNotBlank("bob") = true StringUtils.isNotBlank(" bob ") = true
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if the CharSequence is not empty and not null and not whitespace- Since:
- 2.0, 3.0 Changed signature from isNotBlank(String) to isNotBlank(CharSequence)
-
isAnyBlank
public static boolean isAnyBlank(java.lang.CharSequence... css)
Checks if any one of the CharSequences are blank ("") or null and not whitespace only..
StringUtils.isAnyBlank(null) = true StringUtils.isAnyBlank(null, "foo") = true StringUtils.isAnyBlank(null, null) = true StringUtils.isAnyBlank("", "bar") = true StringUtils.isAnyBlank("bob", "") = true StringUtils.isAnyBlank(" bob ", null) = true StringUtils.isAnyBlank(" ", "bar") = true StringUtils.isAnyBlank("foo", "bar") = false
- Parameters:
css
- the CharSequences to check, may be null or empty- Returns:
true
if any of the CharSequences are blank or null or whitespace only- Since:
- 3.2
-
isNoneBlank
public static boolean isNoneBlank(java.lang.CharSequence... css)
Checks if none of the CharSequences are blank ("") or null and whitespace only..
StringUtils.isNoneBlank(null) = false StringUtils.isNoneBlank(null, "foo") = false StringUtils.isNoneBlank(null, null) = false StringUtils.isNoneBlank("", "bar") = false StringUtils.isNoneBlank("bob", "") = false StringUtils.isNoneBlank(" bob ", null) = false StringUtils.isNoneBlank(" ", "bar") = false StringUtils.isNoneBlank("foo", "bar") = true
- Parameters:
css
- the CharSequences to check, may be null or empty- Returns:
true
if none of the CharSequences are blank or null or whitespace only- Since:
- 3.2
-
trim
public static java.lang.String trim(java.lang.String str)
Removes control characters (char <= 32) from both ends of this String, handling
null
by returningnull
.The String is trimmed using
String.trim()
. Trim removes start and end characters <= 32. To strip whitespace usestrip(String)
.To trim your choice of characters, use the
strip(String, String)
methods.StringUtils.trim(null) = null StringUtils.trim("") = "" StringUtils.trim(" ") = "" StringUtils.trim("abc") = "abc" StringUtils.trim(" abc ") = "abc"
- Parameters:
str
- the String to be trimmed, may be null- Returns:
- the trimmed string,
null
if null String input
-
trimToNull
public static java.lang.String trimToNull(java.lang.String str)
Removes control characters (char <= 32) from both ends of this String returning
null
if the String is empty ("") after the trim or if it isnull
.The String is trimmed using
String.trim()
. Trim removes start and end characters <= 32. To strip whitespace usestripToNull(String)
.StringUtils.trimToNull(null) = null StringUtils.trimToNull("") = null StringUtils.trimToNull(" ") = null StringUtils.trimToNull("abc") = "abc" StringUtils.trimToNull(" abc ") = "abc"
- Parameters:
str
- the String to be trimmed, may be null- Returns:
- the trimmed String,
null
if only chars <= 32, empty or null String input - Since:
- 2.0
-
trimToEmpty
public static java.lang.String trimToEmpty(java.lang.String str)
Removes control characters (char <= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if it is
null
.The String is trimmed using
String.trim()
. Trim removes start and end characters <= 32. To strip whitespace usestripToEmpty(String)
.StringUtils.trimToEmpty(null) = "" StringUtils.trimToEmpty("") = "" StringUtils.trimToEmpty(" ") = "" StringUtils.trimToEmpty("abc") = "abc" StringUtils.trimToEmpty(" abc ") = "abc"
- Parameters:
str
- the String to be trimmed, may be null- Returns:
- the trimmed String, or an empty String if
null
input - Since:
- 2.0
-
strip
public static java.lang.String strip(java.lang.String str)
Strips whitespace from the start and end of a String.
This is similar to
trim(String)
but removes whitespace. Whitespace is defined byCharacter.isWhitespace(char)
.A
null
input String returnsnull
.StringUtils.strip(null) = null StringUtils.strip("") = "" StringUtils.strip(" ") = "" StringUtils.strip("abc") = "abc" StringUtils.strip(" abc") = "abc" StringUtils.strip("abc ") = "abc" StringUtils.strip(" abc ") = "abc" StringUtils.strip(" ab c ") = "ab c"
- Parameters:
str
- the String to remove whitespace from, may be null- Returns:
- the stripped String,
null
if null String input
-
stripToNull
public static java.lang.String stripToNull(java.lang.String str)
Strips whitespace from the start and end of a String returning
null
if the String is empty ("") after the strip.This is similar to
trimToNull(String)
but removes whitespace. Whitespace is defined byCharacter.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"
- Parameters:
str
- the String to be stripped, may be null- Returns:
- the stripped String,
null
if whitespace, empty or null String input - Since:
- 2.0
-
stripToEmpty
public static java.lang.String stripToEmpty(java.lang.String str)
Strips whitespace from the start and end of a String returning an empty String if
null
input.This is similar to
trimToEmpty(String)
but removes whitespace. Whitespace is defined byCharacter.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"
- Parameters:
str
- the String to be stripped, may be null- Returns:
- the trimmed String, or an empty String if
null
input - Since:
- 2.0
-
strip
public static java.lang.String strip(java.lang.String str, java.lang.String stripChars)
Strips any of a set of characters from the start and end of a String. This is similar to
String.trim()
but allows the characters to be stripped to be controlled.A
null
input String returnsnull
. An empty string ("") input returns the empty string.If the stripChars String is
null
, whitespace is stripped as defined byCharacter.isWhitespace(char)
. Alternatively usestrip(String)
.StringUtils.strip(null, *) = null StringUtils.strip("", *) = "" StringUtils.strip("abc", null) = "abc" StringUtils.strip(" abc", null) = "abc" StringUtils.strip("abc ", null) = "abc" StringUtils.strip(" abc ", null) = "abc" StringUtils.strip(" abcyx", "xyz") = " abc"
- Parameters:
str
- the String to remove characters from, may be nullstripChars
- the characters to remove, null treated as whitespace- Returns:
- the stripped String,
null
if null String input
-
stripStart
public static java.lang.String stripStart(java.lang.String str, java.lang.String stripChars)
Strips any of a set of characters from the start of a String.
A
null
input String returnsnull
. An empty string ("") input returns the empty string.If the stripChars String is
null
, whitespace is stripped as defined byCharacter.isWhitespace(char)
.StringUtils.stripStart(null, *) = null StringUtils.stripStart("", *) = "" StringUtils.stripStart("abc", "") = "abc" StringUtils.stripStart("abc", null) = "abc" StringUtils.stripStart(" abc", null) = "abc" StringUtils.stripStart("abc ", null) = "abc " StringUtils.stripStart(" abc ", null) = "abc " StringUtils.stripStart("yxabc ", "xyz") = "abc "
- Parameters:
str
- the String to remove characters from, may be nullstripChars
- the characters to remove, null treated as whitespace- Returns:
- the stripped String,
null
if null String input
-
stripEnd
public static java.lang.String stripEnd(java.lang.String str, java.lang.String stripChars)
Strips any of a set of characters from the end of a String.
A
null
input String returnsnull
. An empty string ("") input returns the empty string.If the stripChars String is
null
, whitespace is stripped as defined byCharacter.isWhitespace(char)
.StringUtils.stripEnd(null, *) = null StringUtils.stripEnd("", *) = "" StringUtils.stripEnd("abc", "") = "abc" StringUtils.stripEnd("abc", null) = "abc" StringUtils.stripEnd(" abc", null) = " abc" StringUtils.stripEnd("abc ", null) = "abc" StringUtils.stripEnd(" abc ", null) = " abc" StringUtils.stripEnd(" abcyx", "xyz") = " abc" StringUtils.stripEnd("120.00", ".0") = "12"
- Parameters:
str
- the String to remove characters from, may be nullstripChars
- the set of characters to remove, null treated as whitespace- Returns:
- the stripped String,
null
if null String input
-
stripAll
public static java.lang.String[] stripAll(java.lang.String... strs)
Strips whitespace from the start and end of every String in an array. Whitespace is defined by
Character.isWhitespace(char)
.A new array is returned each time, except for length zero. A
null
array will returnnull
. An empty array will return itself. Anull
array entry will be ignored.StringUtils.stripAll(null) = null StringUtils.stripAll([]) = [] StringUtils.stripAll(["abc", " abc"]) = ["abc", "abc"] StringUtils.stripAll(["abc ", null]) = ["abc", null]
- Parameters:
strs
- the array to remove whitespace from, may be null- Returns:
- the stripped Strings,
null
if null array input
-
stripAll
public static java.lang.String[] stripAll(java.lang.String[] strs, java.lang.String stripChars)
Strips any of a set of characters from the start and end of every String in an array.
Whitespace is defined by
Character.isWhitespace(char)
.A new array is returned each time, except for length zero. A
null
array will returnnull
. An empty array will return itself. Anull
array entry will be ignored. Anull
stripChars will strip whitespace as defined byCharacter.isWhitespace(char)
.StringUtils.stripAll(null, *) = null StringUtils.stripAll([], *) = [] StringUtils.stripAll(["abc", " abc"], null) = ["abc", "abc"] StringUtils.stripAll(["abc ", null], null) = ["abc", null] StringUtils.stripAll(["abc ", null], "yz") = ["abc ", null] StringUtils.stripAll(["yabcz", null], "yz") = ["abc", null]
- Parameters:
strs
- the array to remove characters from, may be nullstripChars
- the characters to remove, null treated as whitespace- Returns:
- the stripped Strings,
null
if null array input
-
stripAccents
public static java.lang.String stripAccents(java.lang.String input)
Removes diacritics (~= accents) from a string. The case will not be altered.
For instance, 'à' will be replaced by 'a'.
Note that ligatures will be left as is.
StringUtils.stripAccents(null) = null StringUtils.stripAccents("") = "" StringUtils.stripAccents("control") = "control" StringUtils.stripAccents("éclair") = "eclair"
- Parameters:
input
- String to be stripped- Returns:
- input text with diacritics removed
- Since:
- 3.0
-
equals
public static boolean equals(java.lang.CharSequence cs1, java.lang.CharSequence cs2)
Compares two CharSequences, returning
true
if they represent equal sequences of characters.null
s are handled without exceptions. Twonull
references are considered to be equal. The comparison is case sensitive.StringUtils.equals(null, null) = true StringUtils.equals(null, "abc") = false StringUtils.equals("abc", null) = false StringUtils.equals("abc", "abc") = true StringUtils.equals("abc", "ABC") = false
- Parameters:
cs1
- the first CharSequence, may benull
cs2
- the second CharSequence, may benull
- Returns:
true
if the CharSequences are equal (case-sensitive), or bothnull
- Since:
- 3.0 Changed signature from equals(String, String) to equals(CharSequence, CharSequence)
- See Also:
Object.equals(Object)
-
equalsIgnoreCase
public static boolean equalsIgnoreCase(java.lang.CharSequence str1, java.lang.CharSequence str2)
Compares two CharSequences, returning
true
if they represent equal sequences of characters, ignoring case.null
s are handled without exceptions. Twonull
references are considered equal. Comparison is case insensitive.StringUtils.equalsIgnoreCase(null, null) = true StringUtils.equalsIgnoreCase(null, "abc") = false StringUtils.equalsIgnoreCase("abc", null) = false StringUtils.equalsIgnoreCase("abc", "abc") = true StringUtils.equalsIgnoreCase("abc", "ABC") = true
- Parameters:
str1
- the first CharSequence, may be nullstr2
- the second CharSequence, may be null- Returns:
true
if the CharSequence are equal, case insensitive, or bothnull
- Since:
- 3.0 Changed signature from equalsIgnoreCase(String, String) to equalsIgnoreCase(CharSequence, CharSequence)
-
indexOf
public static int indexOf(java.lang.CharSequence seq, int searchChar)
Finds the first index within a CharSequence, handling
null
. This method usesString.indexOf(int, int)
if possible.A
null
or empty ("") CharSequence will returnINDEX_NOT_FOUND (-1)
.StringUtils.indexOf(null, *) = -1 StringUtils.indexOf("", *) = -1 StringUtils.indexOf("aabaabaa", 'a') = 0 StringUtils.indexOf("aabaabaa", 'b') = 2
- Parameters:
seq
- the CharSequence to check, may be nullsearchChar
- the character to find- Returns:
- the first index of the search character,
-1 if no match or
null
string input - Since:
- 2.0, 3.0 Changed signature from indexOf(String, int) to indexOf(CharSequence, int)
-
indexOf
public static int indexOf(java.lang.CharSequence seq, int searchChar, int startPos)
Finds the first index within a CharSequence from a start position, handling
null
. This method usesString.indexOf(int, int)
if possible.A
null
or empty ("") CharSequence 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
- Parameters:
seq
- the CharSequence to check, may be nullsearchChar
- the character to findstartPos
- the start position, negative treated as zero- Returns:
- the first index of the search character (always ≥ startPos),
-1 if no match or
null
string input - Since:
- 2.0, 3.0 Changed signature from indexOf(String, int, int) to indexOf(CharSequence, int, int)
-
indexOf
public static int indexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq)
Finds the first index within a CharSequence, handling
null
. This method usesString.indexOf(String, int)
if possible.A
null
CharSequence 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
- Parameters:
seq
- the CharSequence to check, may be nullsearchSeq
- the CharSequence to find, may be null- Returns:
- the first index of the search CharSequence,
-1 if no match or
null
string input - Since:
- 2.0, 3.0 Changed signature from indexOf(String, String) to indexOf(CharSequence, CharSequence)
-
indexOf
public static int indexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq, int startPos)
Finds the first index within a CharSequence, handling
null
. This method usesString.indexOf(String, int)
if possible.A
null
CharSequence will return-1
. A negative start position is treated as zero. An empty ("") search CharSequence always matches. A start position greater than the string length only matches an empty search CharSequence.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
- Parameters:
seq
- the CharSequence to check, may be nullsearchSeq
- the CharSequence to find, may be nullstartPos
- the start position, negative treated as zero- Returns:
- the first index of the search CharSequence (always ≥ startPos),
-1 if no match or
null
string input - Since:
- 2.0, 3.0 Changed signature from indexOf(String, String, int) to indexOf(CharSequence, CharSequence, int)
-
ordinalIndexOf
public static int ordinalIndexOf(java.lang.CharSequence str, java.lang.CharSequence searchStr, int ordinal)
Finds the n-th index within a CharSequence, handling
null
. This method usesString.indexOf(String)
if possible.A
null
CharSequence 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(CharSequence str, int n)' may be implemented as:
str.substring(0, lastOrdinalIndexOf(str, "\n", n))
- Parameters:
str
- the CharSequence to check, may be nullsearchStr
- the CharSequence to find, may be nullordinal
- the n-thsearchStr
to find- Returns:
- the n-th index of the search CharSequence,
-1
(INDEX_NOT_FOUND
) if no match ornull
string input - Since:
- 2.1, 3.0 Changed signature from ordinalIndexOf(String, String, int) to ordinalIndexOf(CharSequence, CharSequence, int)
-
indexOfIgnoreCase
public static int indexOfIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr)
Case in-sensitive find of the first index within a CharSequence.
A
null
CharSequence will return-1
. A negative start position is treated as zero. An empty ("") search CharSequence always matches. A start position greater than the string length only matches an empty search CharSequence.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
- Parameters:
str
- the CharSequence to check, may be nullsearchStr
- the CharSequence to find, may be null- Returns:
- the first index of the search CharSequence,
-1 if no match or
null
string input - Since:
- 2.5, 3.0 Changed signature from indexOfIgnoreCase(String, String) to indexOfIgnoreCase(CharSequence, CharSequence)
-
indexOfIgnoreCase
public static int indexOfIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr, int startPos)
Case in-sensitive find of the first index within a CharSequence from the specified position.
A
null
CharSequence will return-1
. A negative start position is treated as zero. An empty ("") search CharSequence always matches. A start position greater than the string length only matches an empty search CharSequence.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
- Parameters:
str
- the CharSequence to check, may be nullsearchStr
- the CharSequence to find, may be nullstartPos
- the start position, negative treated as zero- Returns:
- the first index of the search CharSequence (always ≥ startPos),
-1 if no match or
null
string input - Since:
- 2.5, 3.0 Changed signature from indexOfIgnoreCase(String, String, int) to indexOfIgnoreCase(CharSequence, CharSequence, int)
-
lastIndexOf
public static int lastIndexOf(java.lang.CharSequence seq, int searchChar)
Finds the last index within a CharSequence, handling
null
. This method usesString.lastIndexOf(int)
if possible.A
null
or empty ("") CharSequence will return-1
.StringUtils.lastIndexOf(null, *) = -1 StringUtils.lastIndexOf("", *) = -1 StringUtils.lastIndexOf("aabaabaa", 'a') = 7 StringUtils.lastIndexOf("aabaabaa", 'b') = 5
- Parameters:
seq
- the CharSequence to check, may be nullsearchChar
- the character to find- Returns:
- the last index of the search character,
-1 if no match or
null
string input - Since:
- 2.0, 3.0 Changed signature from lastIndexOf(String, int) to lastIndexOf(CharSequence, int)
-
lastIndexOf
public static int lastIndexOf(java.lang.CharSequence seq, int searchChar, int startPos)
Finds the last index within a CharSequence from a start position, handling
null
. This method usesString.lastIndexOf(int, int)
if possible.A
null
or empty ("") CharSequence will return-1
. A negative start position returns-1
. A start position greater than the string length searches the whole string. The search starts at the startPos and works backwards; matches starting after the start position are ignored.StringUtils.lastIndexOf(null, *, *) = -1 StringUtils.lastIndexOf("", *, *) = -1 StringUtils.lastIndexOf("aabaabaa", 'b', 8) = 5 StringUtils.lastIndexOf("aabaabaa", 'b', 4) = 2 StringUtils.lastIndexOf("aabaabaa", 'b', 0) = -1 StringUtils.lastIndexOf("aabaabaa", 'b', 9) = 5 StringUtils.lastIndexOf("aabaabaa", 'b', -1) = -1 StringUtils.lastIndexOf("aabaabaa", 'a', 0) = 0
- Parameters:
seq
- the CharSequence to check, may be nullsearchChar
- the character to findstartPos
- the start position- Returns:
- the last index of the search character (always ≤ startPos),
-1 if no match or
null
string input - Since:
- 2.0, 3.0 Changed signature from lastIndexOf(String, int, int) to lastIndexOf(CharSequence, int, int)
-
lastIndexOf
public static int lastIndexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq)
Finds the last index within a CharSequence, handling
null
. This method usesString.lastIndexOf(String)
if possible.A
null
CharSequence 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
- Parameters:
seq
- the CharSequence to check, may be nullsearchSeq
- the CharSequence to find, may be null- Returns:
- the last index of the search String,
-1 if no match or
null
string input - Since:
- 2.0, 3.0 Changed signature from lastIndexOf(String, String) to lastIndexOf(CharSequence, CharSequence)
-
lastOrdinalIndexOf
public static int lastOrdinalIndexOf(java.lang.CharSequence str, java.lang.CharSequence searchStr, int ordinal)
Finds the n-th last index within a String, handling
null
. This method usesString.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(CharSequence str, int n)' may be implemented as:
str.substring(lastOrdinalIndexOf(str, "\n", n) + 1)
- Parameters:
str
- the CharSequence to check, may be nullsearchStr
- the CharSequence to find, may be nullordinal
- the n-th lastsearchStr
to find- Returns:
- the n-th last index of the search CharSequence,
-1
(INDEX_NOT_FOUND
) if no match ornull
string input - Since:
- 2.5, 3.0 Changed signature from lastOrdinalIndexOf(String, String, int) to lastOrdinalIndexOf(CharSequence, CharSequence, int)
-
lastIndexOf
public static int lastIndexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq, int startPos)
Finds the last index within a CharSequence, handling
null
. This method usesString.lastIndexOf(String, int)
if possible.A
null
CharSequence will return-1
. A negative start position returns-1
. An empty ("") search CharSequence always matches unless the start position is negative. A start position greater than the string length searches the whole string. The search starts at the startPos and works backwards; matches starting after the start position are ignored.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 StringUtils.lastIndexOf("aabaabaa", "b", 1) = -1 StringUtils.lastIndexOf("aabaabaa", "b", 2) = 2 StringUtils.lastIndexOf("aabaabaa", "ba", 2) = -1 StringUtils.lastIndexOf("aabaabaa", "ba", 2) = 2
- Parameters:
seq
- the CharSequence to check, may be nullsearchSeq
- the CharSequence to find, may be nullstartPos
- the start position, negative treated as zero- Returns:
- the last index of the search CharSequence (always ≤ startPos),
-1 if no match or
null
string input - Since:
- 2.0, 3.0 Changed signature from lastIndexOf(String, String, int) to lastIndexOf(CharSequence, CharSequence, int)
-
lastIndexOfIgnoreCase
public static int lastIndexOfIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr)
Case in-sensitive find of the last index within a CharSequence.
A
null
CharSequence will return-1
. A negative start position returns-1
. An empty ("") search CharSequence always matches unless the start position is negative. A start position greater than the string length searches the whole string.StringUtils.lastIndexOfIgnoreCase(null, *) = -1 StringUtils.lastIndexOfIgnoreCase(*, null) = -1 StringUtils.lastIndexOfIgnoreCase("aabaabaa", "A") = 7 StringUtils.lastIndexOfIgnoreCase("aabaabaa", "B") = 5 StringUtils.lastIndexOfIgnoreCase("aabaabaa", "AB") = 4
- Parameters:
str
- the CharSequence to check, may be nullsearchStr
- the CharSequence to find, may be null- Returns:
- the first index of the search CharSequence,
-1 if no match or
null
string input - Since:
- 2.5, 3.0 Changed signature from lastIndexOfIgnoreCase(String, String) to lastIndexOfIgnoreCase(CharSequence, CharSequence)
-
lastIndexOfIgnoreCase
public static int lastIndexOfIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr, int startPos)
Case in-sensitive find of the last index within a CharSequence from the specified position.
A
null
CharSequence will return-1
. A negative start position returns-1
. An empty ("") search CharSequence always matches unless the start position is negative. A start position greater than the string length searches the whole string. The search starts at the startPos and works backwards; matches starting after the start position are ignored.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
- Parameters:
str
- the CharSequence to check, may be nullsearchStr
- the CharSequence to find, may be nullstartPos
- the start position- Returns:
- the last index of the search CharSequence (always ≤ startPos),
-1 if no match or
null
input - Since:
- 2.5, 3.0 Changed signature from lastIndexOfIgnoreCase(String, String, int) to lastIndexOfIgnoreCase(CharSequence, CharSequence, int)
-
contains
public static boolean contains(java.lang.CharSequence seq, int searchChar)
Checks if CharSequence contains a search character, handling
null
. This method usesString.indexOf(int)
if possible.A
null
or empty ("") CharSequence will returnfalse
.StringUtils.contains(null, *) = false StringUtils.contains("", *) = false StringUtils.contains("abc", 'a') = true StringUtils.contains("abc", 'z') = false
- Parameters:
seq
- the CharSequence to check, may be nullsearchChar
- the character to find- Returns:
- true if the CharSequence contains the search character,
false if not or
null
string input - Since:
- 2.0, 3.0 Changed signature from contains(String, int) to contains(CharSequence, int)
-
contains
public static boolean contains(java.lang.CharSequence seq, java.lang.CharSequence searchSeq)
Checks if CharSequence contains a search CharSequence, handling
null
. This method usesString.indexOf(String)
if possible.A
null
CharSequence will returnfalse
.StringUtils.contains(null, *) = false StringUtils.contains(*, null) = false StringUtils.contains("", "") = true StringUtils.contains("abc", "") = true StringUtils.contains("abc", "a") = true StringUtils.contains("abc", "z") = false
- Parameters:
seq
- the CharSequence to check, may be nullsearchSeq
- the CharSequence to find, may be null- Returns:
- true if the CharSequence contains the search CharSequence,
false if not or
null
string input - Since:
- 2.0, 3.0 Changed signature from contains(String, String) to contains(CharSequence, CharSequence)
-
containsIgnoreCase
public static boolean containsIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr)
Checks if CharSequence contains a search CharSequence irrespective of case, handling
null
. Case-insensitivity is defined as byString.equalsIgnoreCase(String)
.A
null
CharSequence will returnfalse
.StringUtils.contains(null, *) = false StringUtils.contains(*, null) = false StringUtils.contains("", "") = true StringUtils.contains("abc", "") = true StringUtils.contains("abc", "a") = true StringUtils.contains("abc", "z") = false StringUtils.contains("abc", "A") = true StringUtils.contains("abc", "Z") = false
- Parameters:
str
- the CharSequence to check, may be nullsearchStr
- the CharSequence to find, may be null- Returns:
- true if the CharSequence contains the search CharSequence irrespective of
case or false if not or
null
string input - Since:
- 3.0 Changed signature from containsIgnoreCase(String, String) to containsIgnoreCase(CharSequence, CharSequence)
-
containsWhitespace
public static boolean containsWhitespace(java.lang.CharSequence seq)
Check whether the given CharSequence contains any whitespace characters.- Parameters:
seq
- the CharSequence to check (may benull
)- Returns:
true
if the CharSequence is not empty and contains at least 1 whitespace character- Since:
- 3.0
- See Also:
Character.isWhitespace(char)
-
indexOfAny
public static int indexOfAny(java.lang.CharSequence cs, char... searchChars)
Search a CharSequence to find the first index of any character in the given set of characters.
A
null
String will return-1
. Anull
or zero length search array will return-1
.StringUtils.indexOfAny(null, *) = -1 StringUtils.indexOfAny("", *) = -1 StringUtils.indexOfAny(*, null) = -1 StringUtils.indexOfAny(*, []) = -1 StringUtils.indexOfAny("zzabyycdxx",['z','a']) = 0 StringUtils.indexOfAny("zzabyycdxx",['b','y']) = 3 StringUtils.indexOfAny("aba", ['z']) = -1
- Parameters:
cs
- the CharSequence to check, may be nullsearchChars
- the chars to search for, may be null- Returns:
- the index of any of the chars, -1 if no match or null input
- Since:
- 2.0, 3.0 Changed signature from indexOfAny(String, char[]) to indexOfAny(CharSequence, char...)
-
indexOfAny
public static int indexOfAny(java.lang.CharSequence cs, java.lang.String searchChars)
Search a CharSequence to find the first index of any character in the given set of characters.
A
null
String will return-1
. Anull
search string will return-1
.StringUtils.indexOfAny(null, *) = -1 StringUtils.indexOfAny("", *) = -1 StringUtils.indexOfAny(*, null) = -1 StringUtils.indexOfAny(*, "") = -1 StringUtils.indexOfAny("zzabyycdxx", "za") = 0 StringUtils.indexOfAny("zzabyycdxx", "by") = 3 StringUtils.indexOfAny("aba","z") = -1
- Parameters:
cs
- the CharSequence to check, may be nullsearchChars
- the chars to search for, may be null- Returns:
- the index of any of the chars, -1 if no match or null input
- Since:
- 2.0, 3.0 Changed signature from indexOfAny(String, String) to indexOfAny(CharSequence, String)
-
containsAny
public static boolean containsAny(java.lang.CharSequence cs, char... searchChars)
Checks if the CharSequence contains any character in the given set of characters.
A
null
CharSequence will returnfalse
. Anull
or zero length search array will returnfalse
.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
- Parameters:
cs
- the CharSequence to check, may be nullsearchChars
- the chars to search for, may be null- Returns:
- the
true
if any of the chars are found,false
if no match or null input - Since:
- 2.4, 3.0 Changed signature from containsAny(String, char[]) to containsAny(CharSequence, char...)
-
containsAny
public static boolean containsAny(java.lang.CharSequence cs, java.lang.CharSequence searchChars)
Checks if the CharSequence contains any character in the given set of characters.
A
null
CharSequence will returnfalse
. Anull
search CharSequence will returnfalse
.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
- Parameters:
cs
- the CharSequence to check, may be nullsearchChars
- the chars to search for, may be null- Returns:
- the
true
if any of the chars are found,false
if no match or null input - Since:
- 2.4, 3.0 Changed signature from containsAny(String, String) to containsAny(CharSequence, CharSequence)
-
containsAny
public static boolean containsAny(java.lang.CharSequence cs, java.lang.CharSequence... searchCharSequences)
Checks if the CharSequence contains any of the CharSequences in the given array.
A
null
CharSequence will returnfalse
. Anull
or zero length search array will returnfalse
.StringUtils.containsAny(null, *) = false StringUtils.containsAny("", *) = false StringUtils.containsAny(*, null) = false StringUtils.containsAny(*, []) = false StringUtils.containsAny("abcd", "ab", "cd") = false StringUtils.containsAny("abc", "d", "abc") = true
- Parameters:
cs
- The CharSequence to check, may be nullsearchCharSequences
- The array of CharSequences to search for, may be null- Returns:
true
if any of the search CharSequences are found,false
otherwise- Since:
- 3.4
-
indexOfAnyBut
public static int indexOfAnyBut(java.lang.CharSequence cs, char... searchChars)
Searches a CharSequence to find the first index of any character not in the given set of characters.
A
null
CharSequence will return-1
. Anull
or zero length search array will return-1
.StringUtils.indexOfAnyBut(null, *) = -1 StringUtils.indexOfAnyBut("", *) = -1 StringUtils.indexOfAnyBut(*, null) = -1 StringUtils.indexOfAnyBut(*, []) = -1 StringUtils.indexOfAnyBut("zzabyycdxx", new char[] {'z', 'a'} ) = 3 StringUtils.indexOfAnyBut("aba", new char[] {'z'} ) = 0 StringUtils.indexOfAnyBut("aba", new char[] {'a', 'b'} ) = -1
- Parameters:
cs
- the CharSequence to check, may be nullsearchChars
- the chars to search for, may be null- Returns:
- the index of any of the chars, -1 if no match or null input
- Since:
- 2.0, 3.0 Changed signature from indexOfAnyBut(String, char[]) to indexOfAnyBut(CharSequence, char...)
-
indexOfAnyBut
public static int indexOfAnyBut(java.lang.CharSequence seq, java.lang.CharSequence searchChars)
Search a CharSequence to find the first index of any character not in the given set of characters.
A
null
CharSequence will return-1
. Anull
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
- Parameters:
seq
- the CharSequence to check, may be nullsearchChars
- the chars to search for, may be null- Returns:
- the index of any of the chars, -1 if no match or null input
- Since:
- 2.0, 3.0 Changed signature from indexOfAnyBut(String, String) to indexOfAnyBut(CharSequence, CharSequence)
-
containsOnly
public static boolean containsOnly(java.lang.CharSequence cs, char... valid)
Checks if the CharSequence contains only certain characters.
A
null
CharSequence will returnfalse
. Anull
valid character array will returnfalse
. An empty CharSequence (length()=0) always returnstrue
.StringUtils.containsOnly(null, *) = false StringUtils.containsOnly(*, null) = false StringUtils.containsOnly("", *) = true StringUtils.containsOnly("ab", '') = false StringUtils.containsOnly("abab", 'abc') = true StringUtils.containsOnly("ab1", 'abc') = false StringUtils.containsOnly("abz", 'abc') = false
- Parameters:
cs
- the String to check, may be nullvalid
- an array of valid chars, may be null- Returns:
- true if it only contains valid chars and is non-null
- Since:
- 3.0 Changed signature from containsOnly(String, char[]) to containsOnly(CharSequence, char...)
-
containsOnly
public static boolean containsOnly(java.lang.CharSequence cs, java.lang.String validChars)
Checks if the CharSequence contains only certain characters.
A
null
CharSequence will returnfalse
. Anull
valid character String will returnfalse
. An empty String (length()=0) always returnstrue
.StringUtils.containsOnly(null, *) = false StringUtils.containsOnly(*, null) = false StringUtils.containsOnly("", *) = true StringUtils.containsOnly("ab", "") = false StringUtils.containsOnly("abab", "abc") = true StringUtils.containsOnly("ab1", "abc") = false StringUtils.containsOnly("abz", "abc") = false
- Parameters:
cs
- the CharSequence to check, may be nullvalidChars
- a String of valid chars, may be null- Returns:
- true if it only contains valid chars and is non-null
- Since:
- 2.0, 3.0 Changed signature from containsOnly(String, String) to containsOnly(CharSequence, String)
-
containsNone
public static boolean containsNone(java.lang.CharSequence cs, char... searchChars)
Checks that the CharSequence does not contain certain characters.
A
null
CharSequence will returntrue
. Anull
invalid character array will returntrue
. An empty CharSequence (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
- Parameters:
cs
- the CharSequence to check, may be nullsearchChars
- an array of invalid chars, may be null- Returns:
- true if it contains none of the invalid chars, or is null
- Since:
- 2.0, 3.0 Changed signature from containsNone(String, char[]) to containsNone(CharSequence, char...)
-
containsNone
public static boolean containsNone(java.lang.CharSequence cs, java.lang.String invalidChars)
Checks that the CharSequence does not contain certain characters.
A
null
CharSequence will returntrue
. Anull
invalid character array will returntrue
. An empty String ("") always returns true.StringUtils.containsNone(null, *) = true StringUtils.containsNone(*, null) = true StringUtils.containsNone("", *) = true StringUtils.containsNone("ab", "") = true StringUtils.containsNone("abab", "xyz") = true StringUtils.containsNone("ab1", "xyz") = true StringUtils.containsNone("abz", "xyz") = false
- Parameters:
cs
- the CharSequence to check, may be nullinvalidChars
- a String of invalid chars, may be null- Returns:
- true if it contains none of the invalid chars, or is null
- Since:
- 2.0, 3.0 Changed signature from containsNone(String, String) to containsNone(CharSequence, String)
-
indexOfAny
public static int indexOfAny(java.lang.CharSequence str, java.lang.CharSequence... searchStrs)
Find the first index of any of a set of potential substrings.
A
null
CharSequence will return-1
. Anull
or zero length search array will return-1
. Anull
search array entry will be ignored, but a search array containing "" will return0
ifstr
is not null. This method usesString.indexOf(String)
if possible.StringUtils.indexOfAny(null, *) = -1 StringUtils.indexOfAny(*, null) = -1 StringUtils.indexOfAny(*, []) = -1 StringUtils.indexOfAny("zzabyycdxx", ["ab","cd"]) = 2 StringUtils.indexOfAny("zzabyycdxx", ["cd","ab"]) = 2 StringUtils.indexOfAny("zzabyycdxx", ["mn","op"]) = -1 StringUtils.indexOfAny("zzabyycdxx", ["zab","aby"]) = 1 StringUtils.indexOfAny("zzabyycdxx", [""]) = 0 StringUtils.indexOfAny("", [""]) = 0 StringUtils.indexOfAny("", ["a"]) = -1
- Parameters:
str
- the CharSequence to check, may be nullsearchStrs
- the CharSequences to search for, may be null- Returns:
- the first index of any of the searchStrs in str, -1 if no match
- Since:
- 3.0 Changed signature from indexOfAny(String, String[]) to indexOfAny(CharSequence, CharSequence...)
-
lastIndexOfAny
public static int lastIndexOfAny(java.lang.CharSequence str, java.lang.CharSequence... searchStrs)
Find the latest index of any of a set of potential substrings.
A
null
CharSequence will return-1
. Anull
search array will return-1
. Anull
or zero length search array entry will be ignored, but a search array containing "" will return the length ofstr
ifstr
is not null. This method usesString.indexOf(String)
if possibleStringUtils.lastIndexOfAny(null, *) = -1 StringUtils.lastIndexOfAny(*, null) = -1 StringUtils.lastIndexOfAny(*, []) = -1 StringUtils.lastIndexOfAny(*, [null]) = -1 StringUtils.lastIndexOfAny("zzabyycdxx", ["ab","cd"]) = 6 StringUtils.lastIndexOfAny("zzabyycdxx", ["cd","ab"]) = 6 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn","op"]) = -1 StringUtils.lastIndexOfAny("zzabyycdxx", ["mn",""]) = 10
- Parameters:
str
- the CharSequence to check, may be nullsearchStrs
- the CharSequences to search for, may be null- Returns:
- the last index of any of the CharSequences, -1 if no match
- Since:
- 3.0 Changed signature from lastIndexOfAny(String, String[]) to lastIndexOfAny(CharSequence, CharSequence)
-
substring
public static java.lang.String substring(java.lang.String str, int start)
Gets a substring from the specified String avoiding exceptions.
A negative start position can be used to start
n
characters from the end of the String.A
null
String will returnnull
. An empty ("") String will return "".StringUtils.substring(null, *) = null StringUtils.substring("", *) = "" StringUtils.substring("abc", 0) = "abc" StringUtils.substring("abc", 2) = "c" StringUtils.substring("abc", 4) = "" StringUtils.substring("abc", -2) = "bc" StringUtils.substring("abc", -4) = "abc"
- Parameters:
str
- the String to get the substring from, may be nullstart
- the position to start from, negative means count back from the end of the String by this many characters- Returns:
- substring from start position,
null
if null String input
-
substring
public static java.lang.String substring(java.lang.String str, int start, int end)
Gets a substring from the specified String avoiding exceptions.
A negative start position can be used to start/end
n
characters from the end of the String.The returned substring starts with the character in the
start
position and ends before theend
position. All position counting is zero-based -- i.e., to start at the beginning of the string usestart = 0
. Negative start and end positions can be used to specify offsets relative to the end of the String.If
start
is not strictly to the left ofend
, "" is returned.StringUtils.substring(null, *, *) = null StringUtils.substring("", * , *) = ""; StringUtils.substring("abc", 0, 2) = "ab" StringUtils.substring("abc", 2, 0) = "" StringUtils.substring("abc", 2, 4) = "c" StringUtils.substring("abc", 4, 6) = "" StringUtils.substring("abc", 2, 2) = "" StringUtils.substring("abc", -2, -1) = "b" StringUtils.substring("abc", -4, 2) = "ab"
- Parameters:
str
- the String to get the substring from, may be nullstart
- the position to start from, negative means count back from the end of the String by this many charactersend
- the position to end at (exclusive), negative means count back from the end of the String by this many characters- Returns:
- substring from start position to end position,
null
if null String input
-
left
public static java.lang.String left(java.lang.String str, int len)
Gets the leftmost
len
characters of a String.If
len
characters are not available, or the String isnull
, 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"
- Parameters:
str
- the String to get the leftmost characters from, may be nulllen
- the length of the required String- Returns:
- the leftmost characters,
null
if null String input
-
right
public static java.lang.String right(java.lang.String str, int len)
Gets the rightmost
len
characters of a String.If
len
characters are not available, or the String isnull
, 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"
- Parameters:
str
- the String to get the rightmost characters from, may be nulllen
- the length of the required String- Returns:
- the rightmost characters,
null
if null String input
-
mid
public static java.lang.String mid(java.lang.String str, int pos, int len)
Gets
len
characters from the middle of a String.If
len
characters are not available, the remainder of the String will be returned without an exception. If the String isnull
,null
will be returned. An empty String is returned if len is negative or exceeds the length ofstr
.StringUtils.mid(null, *, *) = null StringUtils.mid(*, *, -ve) = "" StringUtils.mid("", 0, *) = "" StringUtils.mid("abc", 0, 2) = "ab" StringUtils.mid("abc", 0, 4) = "abc" StringUtils.mid("abc", 2, 4) = "c" StringUtils.mid("abc", 4, 2) = "" StringUtils.mid("abc", -2, 2) = "ab"
- Parameters:
str
- the String to get the characters from, may be nullpos
- the position to start from, negative treated as zerolen
- the length of the required String- Returns:
- the middle characters,
null
if null String input
-
substringBefore
public static java.lang.String substringBefore(java.lang.String str, java.lang.String separator)
Gets the substring before the first occurrence of a separator. The separator is not returned.
A
null
string input will returnnull
. An empty ("") string input will return the empty string. Anull
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"
- Parameters:
str
- the String to get a substring from, may be nullseparator
- the String to search for, may be null- Returns:
- the substring before the first occurrence of the separator,
null
if null String input - Since:
- 2.0
-
substringAfter
public static java.lang.String substringAfter(java.lang.String str, java.lang.String separator)
Gets the substring after the first occurrence of a separator. The separator is not returned.
A
null
string input will returnnull
. An empty ("") string input will return the empty string. Anull
separator will return the empty string if the input string is notnull
.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"
- Parameters:
str
- the String to get a substring from, may be nullseparator
- the String to search for, may be null- Returns:
- the substring after the first occurrence of the separator,
null
if null String input - Since:
- 2.0
-
substringBeforeLast
public static java.lang.String substringBeforeLast(java.lang.String str, java.lang.String separator)
Gets the substring before the last occurrence of a separator. The separator is not returned.
A
null
string input will returnnull
. An empty ("") string input will return the empty string. An empty ornull
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"
- Parameters:
str
- the String to get a substring from, may be nullseparator
- the String to search for, may be null- Returns:
- the substring before the last occurrence of the separator,
null
if null String input - Since:
- 2.0
-
substringAfterLast
public static java.lang.String substringAfterLast(java.lang.String str, java.lang.String separator)
Gets the substring after the last occurrence of a separator. The separator is not returned.
A
null
string input will returnnull
. An empty ("") string input will return the empty string. An empty ornull
separator will return the empty string if the input string is notnull
.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") = ""
- Parameters:
str
- the String to get a substring from, may be nullseparator
- the String to search for, may be null- Returns:
- the substring after the last occurrence of the separator,
null
if null String input - Since:
- 2.0
-
substringBetween
public static java.lang.String substringBetween(java.lang.String str, java.lang.String tag)
Gets the String that is nested in between two instances of the same String.
A
null
input String returnsnull
. Anull
tag returnsnull
.StringUtils.substringBetween(null, *) = null StringUtils.substringBetween("", "") = "" StringUtils.substringBetween("", "tag") = null StringUtils.substringBetween("tagabctag", null) = null StringUtils.substringBetween("tagabctag", "") = "" StringUtils.substringBetween("tagabctag", "tag") = "abc"
- Parameters:
str
- the String containing the substring, may be nulltag
- the String before and after the substring, may be null- Returns:
- the substring,
null
if no match - Since:
- 2.0
-
substringBetween
public static java.lang.String substringBetween(java.lang.String str, java.lang.String open, java.lang.String close)
Gets the String that is nested in between two Strings. Only the first match is returned.
A
null
input String returnsnull
. Anull
open/close returnsnull
(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"
- Parameters:
str
- the String containing the substring, may be nullopen
- the String before the substring, may be nullclose
- the String after the substring, may be null- Returns:
- the substring,
null
if no match - Since:
- 2.0
-
substringsBetween
public static java.lang.String[] substringsBetween(java.lang.String str, java.lang.String open, java.lang.String close)
Searches a String for substrings delimited by a start and end tag, returning all matching substrings in an array.
A
null
input String returnsnull
. Anull
open/close returnsnull
(no match). An empty ("") open/close returnsnull
(no match).StringUtils.substringsBetween("[a][b][c]", "[", "]") = ["a","b","c"] StringUtils.substringsBetween(null, *, *) = null StringUtils.substringsBetween(*, null, *) = null StringUtils.substringsBetween(*, *, null) = null StringUtils.substringsBetween("", "[", "]") = []
- Parameters:
str
- the String containing the substrings, null returns null, empty returns emptyopen
- the String identifying the start of the substring, empty returns nullclose
- the String identifying the end of the substring, empty returns null- Returns:
- a String Array of substrings, or
null
if no match - Since:
- 2.3
-
split
public static java.lang.String[] split(java.lang.String str)
Splits the provided text into an array, using whitespace as the separator. Whitespace is defined by
Character.isWhitespace(char)
.The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.
A
null
input String returnsnull
.StringUtils.split(null) = null StringUtils.split("") = [] StringUtils.split("abc def") = ["abc", "def"] StringUtils.split("abc def") = ["abc", "def"] StringUtils.split(" abc ") = ["abc"]
- Parameters:
str
- the String to parse, may be null- Returns:
- an array of parsed Strings,
null
if null String input
-
split
public static java.lang.String[] split(java.lang.String str, char separatorChar)
Splits the provided text into an array, separator specified. This is an alternative to using StringTokenizer.
The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.
A
null
input String returnsnull
.StringUtils.split(null, *) = null StringUtils.split("", *) = [] StringUtils.split("a.b.c", '.') = ["a", "b", "c"] StringUtils.split("a..b.c", '.') = ["a", "b", "c"] StringUtils.split("a:b:c", '.') = ["a:b:c"] StringUtils.split("a b c", ' ') = ["a", "b", "c"]
- Parameters:
str
- the String to parse, may be nullseparatorChar
- the character used as the delimiter- Returns:
- an array of parsed Strings,
null
if null String input - Since:
- 2.0
-
split
public static java.lang.String[] split(java.lang.String str, java.lang.String separatorChars)
Splits the provided text into an array, separators specified. This is an alternative to using StringTokenizer.
The separator is not included in the returned String array. Adjacent separators are treated as one separator. For more control over the split use the StrTokenizer class.
A
null
input String returnsnull
. Anull
separatorChars splits on whitespace.StringUtils.split(null, *) = null StringUtils.split("", *) = [] StringUtils.split("abc def", null) = ["abc", "def"] StringUtils.split("abc def", " ") = ["abc", "def"] StringUtils.split("abc def", " ") = ["abc", "def"] StringUtils.split("ab:cd:ef", ":") = ["ab", "cd", "ef"]
- Parameters:
str
- the String to parse, may be nullseparatorChars
- the characters used as the delimiters,null
splits on whitespace- Returns:
- an array of parsed Strings,
null
if null String input
-
split
public static java.lang.String[] split(java.lang.String str, java.lang.String separatorChars, int max)
Splits the provided text into an array with a maximum length, separators specified.
The separator is not included in the returned String array. Adjacent separators are treated as one separator.
A
null
input String returnsnull
. Anull
separatorChars splits on whitespace.If more than
max
delimited substrings are found, the last returned string includes all characters after the firstmax - 1
returned strings (including separator characters).StringUtils.split(null, *, *) = null StringUtils.split("", *, *) = [] StringUtils.split("ab cd ef", null, 0) = ["ab", "cd", "ef"] StringUtils.split("ab cd ef", null, 0) = ["ab", "cd", "ef"] StringUtils.split("ab:cd:ef", ":", 0) = ["ab", "cd", "ef"] StringUtils.split("ab:cd:ef", ":", 2) = ["ab", "cd:ef"]
- Parameters:
str
- the String to parse, may be nullseparatorChars
- the characters used as the delimiters,null
splits on whitespacemax
- the maximum number of elements to include in the array. A zero or negative value implies no limit- Returns:
- an array of parsed Strings,
null
if null String input
-
splitByWholeSeparator
public static java.lang.String[] splitByWholeSeparator(java.lang.String str, java.lang.String separator)
Splits the provided text into an array, separator string specified.
The separator(s) will not be included in the returned String array. Adjacent separators are treated as one separator.
A
null
input String returnsnull
. Anull
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"]
- Parameters:
str
- the String to parse, may be nullseparator
- String containing the String to be used as a delimiter,null
splits on whitespace- Returns:
- an array of parsed Strings,
null
if null String was input
-
splitByWholeSeparator
public static java.lang.String[] splitByWholeSeparator(java.lang.String str, java.lang.String separator, int max)
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 returnsnull
. Anull
separator splits on whitespace.StringUtils.splitByWholeSeparator(null, *, *) = null StringUtils.splitByWholeSeparator("", *, *) = [] StringUtils.splitByWholeSeparator("ab de fg", null, 0) = ["ab", "de", "fg"] StringUtils.splitByWholeSeparator("ab de fg", null, 0) = ["ab", "de", "fg"] StringUtils.splitByWholeSeparator("ab:cd:ef", ":", 2) = ["ab", "cd:ef"] StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"] StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
- Parameters:
str
- the String to parse, may be nullseparator
- String containing the String to be used as a delimiter,null
splits on whitespacemax
- the maximum number of elements to include in the returned array. A zero or negative value implies no limit.- Returns:
- an array of parsed Strings,
null
if null String was input
-
splitByWholeSeparatorPreserveAllTokens
public static java.lang.String[] splitByWholeSeparatorPreserveAllTokens(java.lang.String str, java.lang.String separator)
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 returnsnull
. Anull
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"]
- Parameters:
str
- the String to parse, may be nullseparator
- String containing the String to be used as a delimiter,null
splits on whitespace- Returns:
- an array of parsed Strings,
null
if null String was input - Since:
- 2.4
-
splitByWholeSeparatorPreserveAllTokens
public static java.lang.String[] splitByWholeSeparatorPreserveAllTokens(java.lang.String str, java.lang.String separator, int max)
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 returnsnull
. Anull
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"]
- Parameters:
str
- the String to parse, may be nullseparator
- String containing the String to be used as a delimiter,null
splits on whitespacemax
- the maximum number of elements to include in the returned array. A zero or negative value implies no limit.- Returns:
- an array of parsed Strings,
null
if null String was input - Since:
- 2.4
-
splitPreserveAllTokens
public static java.lang.String[] splitPreserveAllTokens(java.lang.String str)
Splits the provided text into an array, using whitespace as the separator, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer. Whitespace is defined by
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 returnsnull
.StringUtils.splitPreserveAllTokens(null) = null StringUtils.splitPreserveAllTokens("") = [] StringUtils.splitPreserveAllTokens("abc def") = ["abc", "def"] StringUtils.splitPreserveAllTokens("abc def") = ["abc", "", "def"] StringUtils.splitPreserveAllTokens(" abc ") = ["", "abc", ""]
- Parameters:
str
- the String to parse, may benull
- Returns:
- an array of parsed Strings,
null
if null String input - Since:
- 2.1
-
splitPreserveAllTokens
public static java.lang.String[] splitPreserveAllTokens(java.lang.String str, char separatorChar)
Splits the provided text into an array, separator specified, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer.
The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.
A
null
input String returnsnull
.StringUtils.splitPreserveAllTokens(null, *) = null StringUtils.splitPreserveAllTokens("", *) = [] StringUtils.splitPreserveAllTokens("a.b.c", '.') = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a..b.c", '.') = ["a", "", "b", "c"] StringUtils.splitPreserveAllTokens("a:b:c", '.') = ["a:b:c"] StringUtils.splitPreserveAllTokens("a\tb\nc", null) = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a b c", ' ') = ["a", "b", "c"] StringUtils.splitPreserveAllTokens("a b c ", ' ') = ["a", "b", "c", ""] StringUtils.splitPreserveAllTokens("a b c ", ' ') = ["a", "b", "c", "", ""] StringUtils.splitPreserveAllTokens(" a b c", ' ') = ["", a", "b", "c"] StringUtils.splitPreserveAllTokens(" a b c", ' ') = ["", "", a", "b", "c"] StringUtils.splitPreserveAllTokens(" a b c ", ' ') = ["", a", "b", "c", ""]
- Parameters:
str
- the String to parse, may benull
separatorChar
- the character used as the delimiter,null
splits on whitespace- Returns:
- an array of parsed Strings,
null
if null String input - Since:
- 2.1
-
splitPreserveAllTokens
public static java.lang.String[] splitPreserveAllTokens(java.lang.String str, java.lang.String separatorChars)
Splits the provided text into an array, separators specified, preserving all tokens, including empty tokens created by adjacent separators. This is an alternative to using StringTokenizer.
The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. For more control over the split use the StrTokenizer class.
A
null
input String returnsnull
. Anull
separatorChars splits on whitespace.StringUtils.splitPreserveAllTokens(null, *) = null StringUtils.splitPreserveAllTokens("", *) = [] StringUtils.splitPreserveAllTokens("abc def", null) = ["abc", "def"] StringUtils.splitPreserveAllTokens("abc def", " ") = ["abc", "def"] StringUtils.splitPreserveAllTokens("abc def", " ") = ["abc", "", def"] StringUtils.splitPreserveAllTokens("ab:cd:ef", ":") = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab:cd:ef:", ":") = ["ab", "cd", "ef", ""] StringUtils.splitPreserveAllTokens("ab:cd:ef::", ":") = ["ab", "cd", "ef", "", ""] StringUtils.splitPreserveAllTokens("ab::cd:ef", ":") = ["ab", "", cd", "ef"] StringUtils.splitPreserveAllTokens(":cd:ef", ":") = ["", cd", "ef"] StringUtils.splitPreserveAllTokens("::cd:ef", ":") = ["", "", cd", "ef"] StringUtils.splitPreserveAllTokens(":cd:ef:", ":") = ["", cd", "ef", ""]
- Parameters:
str
- the String to parse, may benull
separatorChars
- the characters used as the delimiters,null
splits on whitespace- Returns:
- an array of parsed Strings,
null
if null String input - Since:
- 2.1
-
splitPreserveAllTokens
public static java.lang.String[] splitPreserveAllTokens(java.lang.String str, java.lang.String separatorChars, int max)
Splits the provided text into an array with a maximum length, separators specified, preserving all tokens, including empty tokens created by adjacent separators.
The separator is not included in the returned String array. Adjacent separators are treated as separators for empty tokens. Adjacent separators are treated as one separator.
A
null
input String returnsnull
. Anull
separatorChars splits on whitespace.If more than
max
delimited substrings are found, the last returned string includes all characters after the firstmax - 1
returned strings (including separator characters).StringUtils.splitPreserveAllTokens(null, *, *) = null StringUtils.splitPreserveAllTokens("", *, *) = [] StringUtils.splitPreserveAllTokens("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab de fg", null, 0) = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 0) = ["ab", "cd", "ef"] StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 2) = ["ab", "cd:ef"] StringUtils.splitPreserveAllTokens("ab de fg", null, 2) = ["ab", " de fg"] StringUtils.splitPreserveAllTokens("ab de fg", null, 3) = ["ab", "", " de fg"] StringUtils.splitPreserveAllTokens("ab de fg", null, 4) = ["ab", "", "", "de fg"]
- Parameters:
str
- the String to parse, may benull
separatorChars
- the characters used as the delimiters,null
splits on whitespacemax
- the maximum number of elements to include in the array. A zero or negative value implies no limit- Returns:
- an array of parsed Strings,
null
if null String input - Since:
- 2.1
-
splitByCharacterType
public static java.lang.String[] splitByCharacterType(java.lang.String str)
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"]
- Parameters:
str
- the String to split, may benull
- Returns:
- an array of parsed Strings,
null
if null String input - Since:
- 2.4
-
splitByCharacterTypeCamelCase
public static java.lang.String[] splitByCharacterTypeCamelCase(java.lang.String str)
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 typeCharacter.UPPERCASE_LETTER
, if any, immediately preceding a token of typeCharacter.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"]
- Parameters:
str
- the String to split, may benull
- Returns:
- an array of parsed Strings,
null
if null String input - Since:
- 2.4
-
join
public static <T> java.lang.String join(T... elements)
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"
- Type Parameters:
T
- the specific type of values to join together- Parameters:
elements
- the values to join together, may be null- Returns:
- the joined String,
null
if null array input - Since:
- 2.0, 3.0 Changed signature to use varargs
-
join
public static java.lang.String join(java.lang.Object[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join(["a", "b", "c"], ';') = "a;b;c" StringUtils.join(["a", "b", "c"], null) = "abc" StringUtils.join([null, "", "a"], ';') = ";;a"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null array input - Since:
- 2.0
-
join
public static java.lang.String join(long[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(int[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(short[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(byte[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(char[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(float[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(double[] array, char separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(java.lang.Object[] array, char separator, int startIndex, int endIndex)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. Null objects or empty strings within the array are represented by empty strings.
StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join(["a", "b", "c"], ';') = "a;b;c" StringUtils.join(["a", "b", "c"], null) = "abc" StringUtils.join([null, "", "a"], ';') = ";;a"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to usestartIndex
- the first index to start joining from. It is an error to pass in an end index past the end of the arrayendIndex
- the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array- Returns:
- the joined String,
null
if null array input - Since:
- 2.0
-
join
public static java.lang.String join(long[] array, char separator, int startIndex, int endIndex)
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([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to usestartIndex
- the first index to start joining from. It is an error to pass in an end index past the end of the arrayendIndex
- the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(int[] array, char separator, int startIndex, int endIndex)
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([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to usestartIndex
- the first index to start joining from. It is an error to pass in an end index past the end of the arrayendIndex
- the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(byte[] array, char separator, int startIndex, int endIndex)
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([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to usestartIndex
- the first index to start joining from. It is an error to pass in an end index past the end of the arrayendIndex
- the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(short[] array, char separator, int startIndex, int endIndex)
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([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to usestartIndex
- the first index to start joining from. It is an error to pass in an end index past the end of the arrayendIndex
- the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(char[] array, char separator, int startIndex, int endIndex)
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([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to usestartIndex
- the first index to start joining from. It is an error to pass in an end index past the end of the arrayendIndex
- the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(double[] array, char separator, int startIndex, int endIndex)
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([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to usestartIndex
- the first index to start joining from. It is an error to pass in an end index past the end of the arrayendIndex
- the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(float[] array, char separator, int startIndex, int endIndex)
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([1, 2, 3], ';') = "1;2;3" StringUtils.join([1, 2, 3], null) = "123"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to usestartIndex
- the first index to start joining from. It is an error to pass in an end index past the end of the arrayendIndex
- the index to stop joining from (exclusive). It is an error to pass in an end index past the end of the array- Returns:
- the joined String,
null
if null array input - Since:
- 3.2
-
join
public static java.lang.String join(java.lang.Object[] array, java.lang.String separator)
Joins the elements of the provided array into a single String containing the provided list of elements.
No delimiter is added before or after the list. A
null
separator is the same as an empty String (""). Null objects or empty strings within the array are represented by empty strings.StringUtils.join(null, *) = null StringUtils.join([], *) = "" StringUtils.join([null], *) = "" StringUtils.join(["a", "b", "c"], "--") = "a--b--c" StringUtils.join(["a", "b", "c"], null) = "abc" StringUtils.join(["a", "b", "c"], "") = "abc" StringUtils.join([null, "", "a"], ',') = ",,a"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use, null treated as ""- Returns:
- the joined String,
null
if null array input
-
join
public static java.lang.String join(java.lang.Object[] array, java.lang.String separator, int startIndex, int endIndex)
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"], "--", 0, 3) = "a--b--c" StringUtils.join(["a", "b", "c"], "--", 1, 3) = "b--c" StringUtils.join(["a", "b", "c"], "--", 2, 3) = "c" StringUtils.join(["a", "b", "c"], "--", 2, 2) = "" StringUtils.join(["a", "b", "c"], null, 0, 3) = "abc" StringUtils.join(["a", "b", "c"], "", 0, 3) = "abc" StringUtils.join([null, "", "a"], ',', 0, 3) = ",,a"
- Parameters:
array
- the array of values to join together, may be nullseparator
- the separator character to use, null treated as ""startIndex
- the first index to start joining from.endIndex
- the index to stop joining from (exclusive).- Returns:
- the joined String,
null
if null array input; or the empty string ifendIndex - startIndex <= 0
. The number of joined entries is given byendIndex - startIndex
- Throws:
java.lang.ArrayIndexOutOfBoundsException
- ife
startIndex < 0
or
startIndex >= array.length()
or
endIndex < 0
or
endIndex > array.length()
-
join
public static java.lang.String join(java.util.Iterator<?> iterator, char separator)
Joins the elements of the provided
Iterator
into a single String containing the provided elements.No delimiter is added before or after the list. Null objects or empty strings within the iteration are represented by empty strings.
See the examples here:
join(Object[],char)
.- Parameters:
iterator
- theIterator
of values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null iterator input - Since:
- 2.0
-
join
public static java.lang.String join(java.util.Iterator<?> iterator, java.lang.String separator)
Joins the elements of the provided
Iterator
into a single String containing the provided elements.No delimiter is added before or after the list. A
null
separator is the same as an empty String ("").See the examples here:
join(Object[],String)
.- Parameters:
iterator
- theIterator
of values to join together, may be nullseparator
- the separator character to use, null treated as ""- Returns:
- the joined String,
null
if null iterator input
-
join
public static java.lang.String join(java.lang.Iterable<?> iterable, char separator)
Joins the elements of the provided
Iterable
into a single String containing the provided elements.No delimiter is added before or after the list. Null objects or empty strings within the iteration are represented by empty strings.
See the examples here:
join(Object[],char)
.- Parameters:
iterable
- theIterable
providing the values to join together, may be nullseparator
- the separator character to use- Returns:
- the joined String,
null
if null iterator input - Since:
- 2.3
-
join
public static java.lang.String join(java.lang.Iterable<?> iterable, java.lang.String separator)
Joins the elements of the provided
Iterable
into a single String containing the provided elements.No delimiter is added before or after the list. A
null
separator is the same as an empty String ("").See the examples here:
join(Object[],String)
.- Parameters:
iterable
- theIterable
providing the values to join together, may be nullseparator
- the separator character to use, null treated as ""- Returns:
- the joined String,
null
if null iterator input - Since:
- 2.3
-
deleteWhitespace
public static java.lang.String deleteWhitespace(java.lang.String str)
Deletes all whitespaces from a String as defined by
Character.isWhitespace(char)
.StringUtils.deleteWhitespace(null) = null StringUtils.deleteWhitespace("") = "" StringUtils.deleteWhitespace("abc") = "abc" StringUtils.deleteWhitespace(" ab c ") = "abc"
- Parameters:
str
- the String to delete whitespace from, may be null- Returns:
- the String without whitespaces,
null
if null String input
-
removeStart
public static java.lang.String removeStart(java.lang.String str, java.lang.String remove)
Removes a substring only if it is at the beginning of a source string, otherwise returns the source string.
A
null
source string will returnnull
. An empty ("") source string will return the empty string. Anull
search string will return the source string.StringUtils.removeStart(null, *) = null StringUtils.removeStart("", *) = "" StringUtils.removeStart(*, null) = * StringUtils.removeStart("www.domain.com", "www.") = "domain.com" StringUtils.removeStart("domain.com", "www.") = "domain.com" StringUtils.removeStart("www.domain.com", "domain") = "www.domain.com" StringUtils.removeStart("abc", "") = "abc"
- Parameters:
str
- the source String to search, may be nullremove
- the String to search for and remove, may be null- Returns:
- the substring with the string removed if found,
null
if null String input - Since:
- 2.1
-
removeStartIgnoreCase
public static java.lang.String removeStartIgnoreCase(java.lang.String str, java.lang.String remove)
Case insensitive removal of a substring if it is at the beginning of a source string, otherwise returns the source string.
A
null
source string will returnnull
. An empty ("") source string will return the empty string. Anull
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"
- Parameters:
str
- the source String to search, may be nullremove
- the String to search for (case insensitive) and remove, may be null- Returns:
- the substring with the string removed if found,
null
if null String input - Since:
- 2.4
-
removeEnd
public static java.lang.String removeEnd(java.lang.String str, java.lang.String remove)
Removes a substring only if it is at the end of a source string, otherwise returns the source string.
A
null
source string will returnnull
. An empty ("") source string will return the empty string. Anull
search string will return the source string.StringUtils.removeEnd(null, *) = null StringUtils.removeEnd("", *) = "" StringUtils.removeEnd(*, null) = * StringUtils.removeEnd("www.domain.com", ".com.") = "www.domain.com" StringUtils.removeEnd("www.domain.com", ".com") = "www.domain" StringUtils.removeEnd("www.domain.com", "domain") = "www.domain.com" StringUtils.removeEnd("abc", "") = "abc"
- Parameters:
str
- the source String to search, may be nullremove
- the String to search for and remove, may be null- Returns:
- the substring with the string removed if found,
null
if null String input - Since:
- 2.1
-
removeEndIgnoreCase
public static java.lang.String removeEndIgnoreCase(java.lang.String str, java.lang.String remove)
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 returnnull
. An empty ("") source string will return the empty string. Anull
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")
- Parameters:
str
- the source String to search, may be nullremove
- the String to search for (case insensitive) and remove, may be null- Returns:
- the substring with the string removed if found,
null
if null String input - Since:
- 2.4
-
remove
public static java.lang.String remove(java.lang.String str, java.lang.String remove)
Removes all occurrences of a substring from within the source string.
A
null
source string will returnnull
. An empty ("") source string will return the empty string. Anull
remove string will return the source string. An empty ("") remove string will return the source string.StringUtils.remove(null, *) = null StringUtils.remove("", *) = "" StringUtils.remove(*, null) = * StringUtils.remove(*, "") = * StringUtils.remove("queued", "ue") = "qd" StringUtils.remove("queued", "zz") = "queued"
- Parameters:
str
- the source String to search, may be nullremove
- the String to search for and remove, may be null- Returns:
- the substring with the string removed if found,
null
if null String input - Since:
- 2.1
-
remove
public static java.lang.String remove(java.lang.String str, char remove)
Removes all occurrences of a character from within the source string.
A
null
source string will returnnull
. An empty ("") source string will return the empty string.StringUtils.remove(null, *) = null StringUtils.remove("", *) = "" StringUtils.remove("queued", 'u') = "qeed" StringUtils.remove("queued", 'z') = "queued"
- Parameters:
str
- the source String to search, may be nullremove
- the char to search for and remove, may be null- Returns:
- the substring with the char removed if found,
null
if null String input - Since:
- 2.1
-
replaceOnce
public static java.lang.String replaceOnce(java.lang.String text, java.lang.String searchString, java.lang.String replacement)
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"
- Parameters:
text
- text to search and replace in, may be nullsearchString
- the String to search for, may be nullreplacement
- the String to replace with, may be null- Returns:
- the text with any replacements processed,
null
if null String input - See Also:
replace(String text, String searchString, String replacement, int max)
-
replacePattern
public static java.lang.String replacePattern(java.lang.String source, java.lang.String regex, java.lang.String replacement)
Replaces each substring of the source String that matches the given regular expression with the given replacement using thePattern.DOTALL
option. DOTALL is also know as single-line mode in Perl. This call is also equivalent to:source.replaceAll("(?s)" + regex, replacement)
Pattern.compile(regex, Pattern.DOTALL).matcher(source).replaceAll(replacement)
- Parameters:
source
- the source stringregex
- the regular expression to which this string is to be matchedreplacement
- the string to be substituted for each match- Returns:
- The resulting
String
- Since:
- 3.2
- See Also:
String.replaceAll(String, String)
,Pattern.DOTALL
-
removePattern
public static java.lang.String removePattern(java.lang.String source, java.lang.String regex)
Removes each substring of the source String that matches the given regular expression using the DOTALL option.- Parameters:
source
- the source stringregex
- the regular expression to which this string is to be matched- Returns:
- The resulting
String
- Since:
- 3.2
- See Also:
String.replaceAll(String, String)
,Pattern.DOTALL
-
replace
public static java.lang.String replace(java.lang.String text, java.lang.String searchString, java.lang.String replacement)
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"
- Parameters:
text
- text to search and replace in, may be nullsearchString
- the String to search for, may be nullreplacement
- the String to replace it with, may be null- Returns:
- the text with any replacements processed,
null
if null String input - See Also:
replace(String text, String searchString, String replacement, int max)
-
replace
public static java.lang.String replace(java.lang.String text, java.lang.String searchString, java.lang.String replacement, int max)
Replaces a String with another String inside a larger String, for the first
max
values of the search String.A
null
reference passed to this method is a no-op.StringUtils.replace(null, *, *, *) = null StringUtils.replace("", *, *, *) = "" StringUtils.replace("any", null, *, *) = "any" StringUtils.replace("any", *, null, *) = "any" StringUtils.replace("any", "", *, *) = "any" StringUtils.replace("any", *, *, 0) = "any" StringUtils.replace("abaa", "a", null, -1) = "abaa" StringUtils.replace("abaa", "a", "", -1) = "b" StringUtils.replace("abaa", "a", "z", 0) = "abaa" StringUtils.replace("abaa", "a", "z", 1) = "zbaa" StringUtils.replace("abaa", "a", "z", 2) = "zbza" StringUtils.replace("abaa", "a", "z", -1) = "zbzz"
- Parameters:
text
- text to search and replace in, may be nullsearchString
- the String to search for, may be nullreplacement
- the String to replace it with, may be nullmax
- maximum number of values to replace, or-1
if no maximum- Returns:
- the text with any replacements processed,
null
if null String input
-
replaceEach
public static java.lang.String replaceEach(java.lang.String text, java.lang.String[] searchList, java.lang.String[] replacementList)
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"
- Parameters:
text
- text to search and replace in, no-op if nullsearchList
- the Strings to search for, no-op if nullreplacementList
- the Strings to replace them with, no-op if null- Returns:
- the text with any replacements processed,
null
if null String input - Throws:
java.lang.IllegalArgumentException
- if the lengths of the arrays are not the same (null is ok, and/or size 0)- Since:
- 2.4
-
replaceEachRepeatedly
public static java.lang.String replaceEachRepeatedly(java.lang.String text, java.lang.String[] searchList, java.lang.String[] replacementList)
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.replaceEachRepeatedly(null, *, *) = null StringUtils.replaceEachRepeatedly("", *, *) = "" StringUtils.replaceEachRepeatedly("aba", null, null) = "aba" StringUtils.replaceEachRepeatedly("aba", new String[0], null) = "aba" StringUtils.replaceEachRepeatedly("aba", null, new String[0]) = "aba" StringUtils.replaceEachRepeatedly("aba", new String[]{"a"}, null) = "aba" StringUtils.replaceEachRepeatedly("aba", new String[]{"a"}, new String[]{""}) = "b" StringUtils.replaceEachRepeatedly("aba", new String[]{null}, new String[]{"a"}) = "aba" StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"}) = "wcte" (example of how it repeats) StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}) = "tcte" StringUtils.replaceEachRepeatedly("abcde", new String[]{"ab", "d"}, new String[]{"d", "ab"}) = IllegalStateException
- Parameters:
text
- text to search and replace in, no-op if nullsearchList
- the Strings to search for, no-op if nullreplacementList
- the Strings to replace them with, no-op if null- Returns:
- the text with any replacements processed,
null
if null String input - Throws:
java.lang.IllegalStateException
- if the search is repeating and there is an endless loop due to outputs of one being inputs to anotherjava.lang.IllegalArgumentException
- if the lengths of the arrays are not the same (null is ok, and/or size 0)- Since:
- 2.4
-
replaceChars
public static java.lang.String replaceChars(java.lang.String str, char searchChar, char replaceChar)
Replaces all occurrences of a character in a String with another. This is a null-safe version of
String.replace(char, char)
.A
null
string input returnsnull
. An empty ("") string input returns an empty string.StringUtils.replaceChars(null, *, *) = null StringUtils.replaceChars("", *, *) = "" StringUtils.replaceChars("abcba", 'b', 'y') = "aycya" StringUtils.replaceChars("abcba", 'z', 'y') = "abcba"
- Parameters:
str
- String to replace characters in, may be nullsearchChar
- the character to search for, may be nullreplaceChar
- the character to replace, may be null- Returns:
- modified String,
null
if null string input - Since:
- 2.0
-
replaceChars
public static java.lang.String replaceChars(java.lang.String str, java.lang.String searchChars, java.lang.String replaceChars)
Replaces multiple characters in a String in one go. This method can also be used to delete characters.
For example:
replaceChars("hello", "ho", "jy") = jelly
.A
null
string input returnsnull
. An empty ("") string input returns an empty string. A null or empty set of search characters returns the input string.The length of the search characters should normally equal the length of the replace characters. If the search characters is longer, then the extra search characters are deleted. If the search characters is shorter, then the extra replace characters are ignored.
StringUtils.replaceChars(null, *, *) = null StringUtils.replaceChars("", *, *) = "" StringUtils.replaceChars("abc", null, *) = "abc" StringUtils.replaceChars("abc", "", *) = "abc" StringUtils.replaceChars("abc", "b", null) = "ac" StringUtils.replaceChars("abc", "b", "") = "ac" StringUtils.replaceChars("abcba", "bc", "yz") = "ayzya" StringUtils.replaceChars("abcba", "bc", "y") = "ayya" StringUtils.replaceChars("abcba", "bc", "yzx") = "ayzya"
- Parameters:
str
- String to replace characters in, may be nullsearchChars
- a set of characters to search for, may be nullreplaceChars
- a set of characters to replace, may be null- Returns:
- modified String,
null
if null string input - Since:
- 2.0
-
overlay
public static java.lang.String overlay(java.lang.String str, java.lang.String overlay, int start, int end)
Overlays part of a String with another String.
A
null
string input returnsnull
. A negative index is treated as zero. An index greater than the string length is treated as the string length. The start index is always the smaller of the two indices.StringUtils.overlay(null, *, *, *) = null StringUtils.overlay("", "abc", 0, 0) = "abc" StringUtils.overlay("abcdef", null, 2, 4) = "abef" StringUtils.overlay("abcdef", "", 2, 4) = "abef" StringUtils.overlay("abcdef", "", 4, 2) = "abef" StringUtils.overlay("abcdef", "zzzz", 2, 4) = "abzzzzef" StringUtils.overlay("abcdef", "zzzz", 4, 2) = "abzzzzef" StringUtils.overlay("abcdef", "zzzz", -1, 4) = "zzzzef" StringUtils.overlay("abcdef", "zzzz", 2, 8) = "abzzzz" StringUtils.overlay("abcdef", "zzzz", -2, -3) = "zzzzabcdef" StringUtils.overlay("abcdef", "zzzz", 8, 10) = "abcdefzzzz"
- Parameters:
str
- the String to do overlaying in, may be nulloverlay
- the String to overlay, may be nullstart
- the position to start overlaying atend
- the position to stop overlaying before- Returns:
- overlayed String,
null
if null String input - Since:
- 2.0
-
chomp
public static java.lang.String chomp(java.lang.String str)
Removes one newline from end of a String if it's there, otherwise leave it alone. A newline is "
\n
", "\r
", or "\r\n
".NOTE: This method changed in 2.0. It now more closely matches Perl chomp.
StringUtils.chomp(null) = null StringUtils.chomp("") = "" StringUtils.chomp("abc \r") = "abc " StringUtils.chomp("abc\n") = "abc" StringUtils.chomp("abc\r\n") = "abc" StringUtils.chomp("abc\r\n\r\n") = "abc\r\n" StringUtils.chomp("abc\n\r") = "abc\n" StringUtils.chomp("abc\n\rabc") = "abc\n\rabc" StringUtils.chomp("\r") = "" StringUtils.chomp("\n") = "" StringUtils.chomp("\r\n") = ""
- Parameters:
str
- the String to chomp a newline from, may be null- Returns:
- String without newline,
null
if null String input
-
chomp
@Deprecated public static java.lang.String chomp(java.lang.String str, java.lang.String separator)
Deprecated.This feature will be removed in Lang 4.0, useremoveEnd(String, String)
insteadRemoves
separator
from the end ofstr
if it's there, otherwise leave it alone.NOTE: This method changed in version 2.0. It now more closely matches Perl chomp. For the previous behavior, use
substringBeforeLast(String, String)
. This method usesString.endsWith(String)
.StringUtils.chomp(null, *) = null StringUtils.chomp("", *) = "" StringUtils.chomp("foobar", "bar") = "foo" StringUtils.chomp("foobar", "baz") = "foobar" StringUtils.chomp("foo", "foo") = "" StringUtils.chomp("foo ", "foo") = "foo " StringUtils.chomp(" foo", "foo") = " " StringUtils.chomp("foo", "foooo") = "foo" StringUtils.chomp("foo", "") = "foo" StringUtils.chomp("foo", null) = "foo"
- Parameters:
str
- the String to chomp from, may be nullseparator
- separator String, may be null- Returns:
- String without trailing separator,
null
if null String input
-
chop
public static java.lang.String chop(java.lang.String str)
Remove the last character from a String.
If the String ends in
\r\n
, then remove both of them.StringUtils.chop(null) = null StringUtils.chop("") = "" StringUtils.chop("abc \r") = "abc " StringUtils.chop("abc\n") = "abc" StringUtils.chop("abc\r\n") = "abc" StringUtils.chop("abc") = "ab" StringUtils.chop("abc\nabc") = "abc\nab" StringUtils.chop("a") = "" StringUtils.chop("\r") = "" StringUtils.chop("\n") = "" StringUtils.chop("\r\n") = ""
- Parameters:
str
- the String to chop last character from, may be null- Returns:
- String without last character,
null
if null String input
-
repeat
public static java.lang.String repeat(java.lang.String str, int repeat)
Repeat a String
repeat
times to form a new String.StringUtils.repeat(null, 2) = null StringUtils.repeat("", 0) = "" StringUtils.repeat("", 2) = "" StringUtils.repeat("a", 3) = "aaa" StringUtils.repeat("ab", 2) = "abab" StringUtils.repeat("a", -2) = ""
- Parameters:
str
- the String to repeat, may be nullrepeat
- number of times to repeat str, negative treated as zero- Returns:
- a new String consisting of the original String repeated,
null
if null String input
-
repeat
public static java.lang.String repeat(java.lang.String str, java.lang.String separator, int repeat)
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) = "?, ?, ?"
- Parameters:
str
- the String to repeat, may be nullseparator
- the String to inject, may be nullrepeat
- number of times to repeat str, negative treated as zero- Returns:
- a new String consisting of the original String repeated,
null
if null String input - Since:
- 2.5
-
repeat
public static java.lang.String repeat(char ch, int repeat)
Returns padding using the specified delimiter repeated to a given length.
StringUtils.repeat('e', 0) = "" StringUtils.repeat('e', 3) = "eee" StringUtils.repeat('e', -2) = ""
Note: this method doesn't not support padding with Unicode Supplementary Characters as they require a pair of
char
s to be represented. If you are needing to support full I18N of your applications consider usingrepeat(String, int)
instead.- Parameters:
ch
- character to repeatrepeat
- number of times to repeat char, negative treated as zero- Returns:
- String with repeated character
- See Also:
repeat(String, int)
-
rightPad
public static java.lang.String rightPad(java.lang.String str, int size)
Right pad a String with spaces (' ').
The String is padded to the size of
size
.StringUtils.rightPad(null, *) = null StringUtils.rightPad("", 3) = " " StringUtils.rightPad("bat", 3) = "bat" StringUtils.rightPad("bat", 5) = "bat " StringUtils.rightPad("bat", 1) = "bat" StringUtils.rightPad("bat", -1) = "bat"
- Parameters:
str
- the String to pad out, may be nullsize
- the size to pad to- Returns:
- right padded String or original String if no padding is necessary,
null
if null String input
-
rightPad
public static java.lang.String rightPad(java.lang.String str, int size, char padChar)
Right pad a String with a specified character.
The String is padded to the size of
size
.StringUtils.rightPad(null, *, *) = null StringUtils.rightPad("", 3, 'z') = "zzz" StringUtils.rightPad("bat", 3, 'z') = "bat" StringUtils.rightPad("bat", 5, 'z') = "batzz" StringUtils.rightPad("bat", 1, 'z') = "bat" StringUtils.rightPad("bat", -1, 'z') = "bat"
- Parameters:
str
- the String to pad out, may be nullsize
- the size to pad topadChar
- the character to pad with- Returns:
- right padded String or original String if no padding is necessary,
null
if null String input - Since:
- 2.0
-
rightPad
public static java.lang.String rightPad(java.lang.String str, int size, java.lang.String padStr)
Right pad a String with a specified String.
The String is padded to the size of
size
.StringUtils.rightPad(null, *, *) = null StringUtils.rightPad("", 3, "z") = "zzz" StringUtils.rightPad("bat", 3, "yz") = "bat" StringUtils.rightPad("bat", 5, "yz") = "batyz" StringUtils.rightPad("bat", 8, "yz") = "batyzyzy" StringUtils.rightPad("bat", 1, "yz") = "bat" StringUtils.rightPad("bat", -1, "yz") = "bat" StringUtils.rightPad("bat", 5, null) = "bat " StringUtils.rightPad("bat", 5, "") = "bat "
- Parameters:
str
- the String to pad out, may be nullsize
- the size to pad topadStr
- the String to pad with, null or empty treated as single space- Returns:
- right padded String or original String if no padding is necessary,
null
if null String input
-
leftPad
public static java.lang.String leftPad(java.lang.String str, int size)
Left pad a String with spaces (' ').
The String is padded to the size of
size
.StringUtils.leftPad(null, *) = null StringUtils.leftPad("", 3) = " " StringUtils.leftPad("bat", 3) = "bat" StringUtils.leftPad("bat", 5) = " bat" StringUtils.leftPad("bat", 1) = "bat" StringUtils.leftPad("bat", -1) = "bat"
- Parameters:
str
- the String to pad out, may be nullsize
- the size to pad to- Returns:
- left padded String or original String if no padding is necessary,
null
if null String input
-
leftPad
public static java.lang.String leftPad(java.lang.String str, int size, char padChar)
Left pad a String with a specified character.
Pad to a size of
size
.StringUtils.leftPad(null, *, *) = null StringUtils.leftPad("", 3, 'z') = "zzz" StringUtils.leftPad("bat", 3, 'z') = "bat" StringUtils.leftPad("bat", 5, 'z') = "zzbat" StringUtils.leftPad("bat", 1, 'z') = "bat" StringUtils.leftPad("bat", -1, 'z') = "bat"
- Parameters:
str
- the String to pad out, may be nullsize
- the size to pad topadChar
- the character to pad with- Returns:
- left padded String or original String if no padding is necessary,
null
if null String input - Since:
- 2.0
-
leftPad
public static java.lang.String leftPad(java.lang.String str, int size, java.lang.String padStr)
Left pad a String with a specified String.
Pad to a size of
size
.StringUtils.leftPad(null, *, *) = null StringUtils.leftPad("", 3, "z") = "zzz" StringUtils.leftPad("bat", 3, "yz") = "bat" StringUtils.leftPad("bat", 5, "yz") = "yzbat" StringUtils.leftPad("bat", 8, "yz") = "yzyzybat" StringUtils.leftPad("bat", 1, "yz") = "bat" StringUtils.leftPad("bat", -1, "yz") = "bat" StringUtils.leftPad("bat", 5, null) = " bat" StringUtils.leftPad("bat", 5, "") = " bat"
- Parameters:
str
- the String to pad out, may be nullsize
- the size to pad topadStr
- the String to pad with, null or empty treated as single space- Returns:
- left padded String or original String if no padding is necessary,
null
if null String input
-
length
public static int length(java.lang.CharSequence cs)
Gets a CharSequence length or0
if the CharSequence isnull
.- Parameters:
cs
- a CharSequence ornull
- Returns:
- CharSequence length or
0
if the CharSequence isnull
. - Since:
- 2.4, 3.0 Changed signature from length(String) to length(CharSequence)
-
center
public static java.lang.String center(java.lang.String str, int size)
Centers a String in a larger String of size
size
using the space character (' ').If the size is less than the String length, the String is returned. A
null
String returnsnull
. A negative size is treated as zero.Equivalent to
center(str, size, " ")
.StringUtils.center(null, *) = null StringUtils.center("", 4) = " " StringUtils.center("ab", -1) = "ab" StringUtils.center("ab", 4) = " ab " StringUtils.center("abcd", 2) = "abcd" StringUtils.center("a", 4) = " a "
- Parameters:
str
- the String to center, may be nullsize
- the int size of new String, negative treated as zero- Returns:
- centered String,
null
if null String input
-
center
public static java.lang.String center(java.lang.String str, int size, char padChar)
Centers a String in a larger String of size
size
. Uses a supplied character as the value to pad the String with.If the size is less than the String length, the String is returned. A
null
String returnsnull
. A negative size is treated as zero.StringUtils.center(null, *, *) = null StringUtils.center("", 4, ' ') = " " StringUtils.center("ab", -1, ' ') = "ab" StringUtils.center("ab", 4, ' ') = " ab " StringUtils.center("abcd", 2, ' ') = "abcd" StringUtils.center("a", 4, ' ') = " a " StringUtils.center("a", 4, 'y') = "yayy"
- Parameters:
str
- the String to center, may be nullsize
- the int size of new String, negative treated as zeropadChar
- the character to pad the new String with- Returns:
- centered String,
null
if null String input - Since:
- 2.0
-
center
public static java.lang.String center(java.lang.String str, int size, java.lang.String padStr)
Centers a String in a larger String of size
size
. Uses a supplied String as the value to pad the String with.If the size is less than the String length, the String is returned. A
null
String returnsnull
. A negative size is treated as zero.StringUtils.center(null, *, *) = null StringUtils.center("", 4, " ") = " " StringUtils.center("ab", -1, " ") = "ab" StringUtils.center("ab", 4, " ") = " ab " StringUtils.center("abcd", 2, " ") = "abcd" StringUtils.center("a", 4, " ") = " a " StringUtils.center("a", 4, "yz") = "yayz" StringUtils.center("abc", 7, null) = " abc " StringUtils.center("abc", 7, "") = " abc "
- Parameters:
str
- the String to center, may be nullsize
- the int size of new String, negative treated as zeropadStr
- the String to pad the new String with, must not be null or empty- Returns:
- centered String,
null
if null String input - Throws:
java.lang.IllegalArgumentException
- if padStr isnull
or empty
-
upperCase
public static java.lang.String upperCase(java.lang.String str)
Converts a String to upper case as per
String.toUpperCase()
.A
null
input String returnsnull
.StringUtils.upperCase(null) = null StringUtils.upperCase("") = "" StringUtils.upperCase("aBc") = "ABC"
Note: As described in the documentation for
String.toUpperCase()
, the result of this method is affected by the current locale. For platform-independent case transformations, the methodlowerCase(String, Locale)
should be used with a specific locale (e.g.Locale.ENGLISH
).- Parameters:
str
- the String to upper case, may be null- Returns:
- the upper cased String,
null
if null String input
-
upperCase
public static java.lang.String upperCase(java.lang.String str, java.util.Locale locale)
Converts a String to upper case as per
String.toUpperCase(Locale)
.A
null
input String returnsnull
.StringUtils.upperCase(null, Locale.ENGLISH) = null StringUtils.upperCase("", Locale.ENGLISH) = "" StringUtils.upperCase("aBc", Locale.ENGLISH) = "ABC"
- Parameters:
str
- the String to upper case, may be nulllocale
- the locale that defines the case transformation rules, must not be null- Returns:
- the upper cased String,
null
if null String input - Since:
- 2.5
-
lowerCase
public static java.lang.String lowerCase(java.lang.String str)
Converts a String to lower case as per
String.toLowerCase()
.A
null
input String returnsnull
.StringUtils.lowerCase(null) = null StringUtils.lowerCase("") = "" StringUtils.lowerCase("aBc") = "abc"
Note: As described in the documentation for
String.toLowerCase()
, the result of this method is affected by the current locale. For platform-independent case transformations, the methodlowerCase(String, Locale)
should be used with a specific locale (e.g.Locale.ENGLISH
).- Parameters:
str
- the String to lower case, may be null- Returns:
- the lower cased String,
null
if null String input
-
lowerCase
public static java.lang.String lowerCase(java.lang.String str, java.util.Locale locale)
Converts a String to lower case as per
String.toLowerCase(Locale)
.A
null
input String returnsnull
.StringUtils.lowerCase(null, Locale.ENGLISH) = null StringUtils.lowerCase("", Locale.ENGLISH) = "" StringUtils.lowerCase("aBc", Locale.ENGLISH) = "abc"
- Parameters:
str
- the String to lower case, may be nulllocale
- the locale that defines the case transformation rules, must not be null- Returns:
- the lower cased String,
null
if null String input - Since:
- 2.5
-
capitalize
public static java.lang.String capitalize(java.lang.String str)
Capitalizes a String changing the first letter to title case as per
Character.toTitleCase(char)
. No other letters are changed.For a word based algorithm, see
WordUtils.capitalize(String)
. Anull
input String returnsnull
.StringUtils.capitalize(null) = null StringUtils.capitalize("") = "" StringUtils.capitalize("cat") = "Cat" StringUtils.capitalize("cAt") = "CAt"
- Parameters:
str
- the String to capitalize, may be null- Returns:
- the capitalized String,
null
if null String input - Since:
- 2.0
- See Also:
WordUtils.capitalize(String)
,uncapitalize(String)
-
uncapitalize
public static java.lang.String uncapitalize(java.lang.String str)
Uncapitalizes a String changing the first letter to title case as per
Character.toLowerCase(char)
. No other letters are changed.For a word based algorithm, see
WordUtils.uncapitalize(String)
. Anull
input String returnsnull
.StringUtils.uncapitalize(null) = null StringUtils.uncapitalize("") = "" StringUtils.uncapitalize("Cat") = "cat" StringUtils.uncapitalize("CAT") = "cAT"
- Parameters:
str
- the String to uncapitalize, may be null- Returns:
- the uncapitalized String,
null
if null String input - Since:
- 2.0
- See Also:
WordUtils.uncapitalize(String)
,capitalize(String)
-
swapCase
public static java.lang.String swapCase(java.lang.String str)
Swaps the case of a String changing upper and title case to lower case, and lower case to upper case.
- Upper case character converts to Lower case
- Title case character converts to Lower case
- Lower case character converts to Upper case
For a word based algorithm, see
WordUtils.swapCase(String)
. Anull
input String returnsnull
.StringUtils.swapCase(null) = null StringUtils.swapCase("") = "" StringUtils.swapCase("The dog has a BONE") = "tHE DOG HAS A bone"
NOTE: This method changed in Lang version 2.0. It no longer performs a word based algorithm. If you only use ASCII, you will notice no change. That functionality is available in org.apache.commons.lang3.text.WordUtils.
- Parameters:
str
- the String to swap case, may be null- Returns:
- the changed String,
null
if null String input
-
countMatches
public static int countMatches(java.lang.CharSequence str, java.lang.CharSequence sub)
Counts how many times the substring appears in the larger string.
A
null
or empty ("") String input returns0
.StringUtils.countMatches(null, *) = 0 StringUtils.countMatches("", *) = 0 StringUtils.countMatches("abba", null) = 0 StringUtils.countMatches("abba", "") = 0 StringUtils.countMatches("abba", "a") = 2 StringUtils.countMatches("abba", "ab") = 1 StringUtils.countMatches("abba", "xxx") = 0
- Parameters:
str
- the CharSequence to check, may be nullsub
- the substring to count, may be null- Returns:
- the number of occurrences, 0 if either CharSequence is
null
- Since:
- 3.0 Changed signature from countMatches(String, String) to countMatches(CharSequence, CharSequence)
-
countMatches
public static int countMatches(java.lang.CharSequence str, char ch)
Counts how many times the char appears in the given string.
A
null
or empty ("") String input returns0
.StringUtils.countMatches(null, *) = 0 StringUtils.countMatches("", *) = 0 StringUtils.countMatches("abba", 0) = 0 StringUtils.countMatches("abba", 'a') = 2 StringUtils.countMatches("abba", 'b') = 2 StringUtils.countMatches("abba", 'x') = 0
- Parameters:
str
- the CharSequence to check, may be nullch
- the char to count- Returns:
- the number of occurrences, 0 if the CharSequence is
null
- Since:
- 3.4
-
isAlpha
public static boolean isAlpha(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode letters.
null
will returnfalse
. An empty CharSequence (length()=0) will returnfalse
.StringUtils.isAlpha(null) = false StringUtils.isAlpha("") = false StringUtils.isAlpha(" ") = false StringUtils.isAlpha("abc") = true StringUtils.isAlpha("ab2c") = false StringUtils.isAlpha("ab-c") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if only contains letters, and is non-null- Since:
- 3.0 Changed signature from isAlpha(String) to isAlpha(CharSequence), 3.0 Changed "" to return false and not true
-
isAlphaSpace
public static boolean isAlphaSpace(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode letters and space (' ').
null
will returnfalse
An empty CharSequence (length()=0) will returntrue
.StringUtils.isAlphaSpace(null) = false StringUtils.isAlphaSpace("") = true StringUtils.isAlphaSpace(" ") = true StringUtils.isAlphaSpace("abc") = true StringUtils.isAlphaSpace("ab c") = true StringUtils.isAlphaSpace("ab2c") = false StringUtils.isAlphaSpace("ab-c") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if only contains letters and space, and is non-null- Since:
- 3.0 Changed signature from isAlphaSpace(String) to isAlphaSpace(CharSequence)
-
isAlphanumeric
public static boolean isAlphanumeric(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode letters or digits.
null
will returnfalse
. An empty CharSequence (length()=0) will returnfalse
.StringUtils.isAlphanumeric(null) = false StringUtils.isAlphanumeric("") = false StringUtils.isAlphanumeric(" ") = false StringUtils.isAlphanumeric("abc") = true StringUtils.isAlphanumeric("ab c") = false StringUtils.isAlphanumeric("ab2c") = true StringUtils.isAlphanumeric("ab-c") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if only contains letters or digits, and is non-null- Since:
- 3.0 Changed signature from isAlphanumeric(String) to isAlphanumeric(CharSequence), 3.0 Changed "" to return false and not true
-
isAlphanumericSpace
public static boolean isAlphanumericSpace(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode letters, digits or space (
' '
).null
will returnfalse
. An empty CharSequence (length()=0) will returntrue
.StringUtils.isAlphanumericSpace(null) = false StringUtils.isAlphanumericSpace("") = true StringUtils.isAlphanumericSpace(" ") = true StringUtils.isAlphanumericSpace("abc") = true StringUtils.isAlphanumericSpace("ab c") = true StringUtils.isAlphanumericSpace("ab2c") = true StringUtils.isAlphanumericSpace("ab-c") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if only contains letters, digits or space, and is non-null- Since:
- 3.0 Changed signature from isAlphanumericSpace(String) to isAlphanumericSpace(CharSequence)
-
isAsciiPrintable
public static boolean isAsciiPrintable(java.lang.CharSequence cs)
Checks if the CharSequence contains only ASCII printable characters.
null
will returnfalse
. An empty CharSequence (length()=0) will returntrue
.StringUtils.isAsciiPrintable(null) = false StringUtils.isAsciiPrintable("") = true StringUtils.isAsciiPrintable(" ") = true StringUtils.isAsciiPrintable("Ceki") = true StringUtils.isAsciiPrintable("ab2c") = true StringUtils.isAsciiPrintable("!ab-c~") = true StringUtils.isAsciiPrintable(" ") = true StringUtils.isAsciiPrintable("!") = true StringUtils.isAsciiPrintable("~") = true StringUtils.isAsciiPrintable("") = false StringUtils.isAsciiPrintable("Ceki Gülcü") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if every character is in the range 32 thru 126- Since:
- 2.1, 3.0 Changed signature from isAsciiPrintable(String) to isAsciiPrintable(CharSequence)
-
isNumeric
public static boolean isNumeric(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode digits. A decimal point is not a Unicode digit and returns false.
null
will returnfalse
. An empty CharSequence (length()=0) will returnfalse
.Note that the method does not allow for a leading sign, either positive or negative. Also, if a String passes the numeric test, it may still generate a NumberFormatException when parsed by Integer.parseInt or Long.parseLong, e.g. if the value is outside the range for int or long respectively.
StringUtils.isNumeric(null) = false StringUtils.isNumeric("") = false StringUtils.isNumeric(" ") = false StringUtils.isNumeric("123") = true StringUtils.isNumeric("???") = true StringUtils.isNumeric("12 3") = false StringUtils.isNumeric("ab2c") = false StringUtils.isNumeric("12-3") = false StringUtils.isNumeric("12.3") = false StringUtils.isNumeric("-123") = false StringUtils.isNumeric("+123") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if only contains digits, and is non-null- Since:
- 3.0 Changed signature from isNumeric(String) to isNumeric(CharSequence), 3.0 Changed "" to return false and not true
-
isNumericSpace
public static boolean isNumericSpace(java.lang.CharSequence cs)
Checks if the CharSequence contains only Unicode digits or space (
' '
). A decimal point is not a Unicode digit and returns false.null
will returnfalse
. An empty CharSequence (length()=0) will returntrue
.StringUtils.isNumericSpace(null) = false StringUtils.isNumericSpace("") = true StringUtils.isNumericSpace(" ") = true StringUtils.isNumericSpace("123") = true StringUtils.isNumericSpace("12 3") = true StringUtils.isNumeric("???") = true StringUtils.isNumeric("?? ?") = true StringUtils.isNumericSpace("ab2c") = false StringUtils.isNumericSpace("12-3") = false StringUtils.isNumericSpace("12.3") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if only contains digits or space, and is non-null- Since:
- 3.0 Changed signature from isNumericSpace(String) to isNumericSpace(CharSequence)
-
isWhitespace
public static boolean isWhitespace(java.lang.CharSequence cs)
Checks if the CharSequence contains only whitespace.
null
will returnfalse
. An empty CharSequence (length()=0) will returntrue
.StringUtils.isWhitespace(null) = false StringUtils.isWhitespace("") = true StringUtils.isWhitespace(" ") = true StringUtils.isWhitespace("abc") = false StringUtils.isWhitespace("ab2c") = false StringUtils.isWhitespace("ab-c") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if only contains whitespace, and is non-null- Since:
- 2.0, 3.0 Changed signature from isWhitespace(String) to isWhitespace(CharSequence)
-
isAllLowerCase
public static boolean isAllLowerCase(java.lang.CharSequence cs)
Checks if the CharSequence contains only lowercase characters.
null
will returnfalse
. An empty CharSequence (length()=0) will returnfalse
.StringUtils.isAllLowerCase(null) = false StringUtils.isAllLowerCase("") = false StringUtils.isAllLowerCase(" ") = false StringUtils.isAllLowerCase("abc") = true StringUtils.isAllLowerCase("abC") = false StringUtils.isAllLowerCase("ab c") = false StringUtils.isAllLowerCase("ab1c") = false StringUtils.isAllLowerCase("ab/c") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if only contains lowercase characters, and is non-null- Since:
- 2.5, 3.0 Changed signature from isAllLowerCase(String) to isAllLowerCase(CharSequence)
-
isAllUpperCase
public static boolean isAllUpperCase(java.lang.CharSequence cs)
Checks if the CharSequence contains only uppercase characters.
null
will returnfalse
. An empty String (length()=0) will returnfalse
.StringUtils.isAllUpperCase(null) = false StringUtils.isAllUpperCase("") = false StringUtils.isAllUpperCase(" ") = false StringUtils.isAllUpperCase("ABC") = true StringUtils.isAllUpperCase("aBC") = false StringUtils.isAllUpperCase("A C") = false StringUtils.isAllUpperCase("A1C") = false StringUtils.isAllUpperCase("A/C") = false
- Parameters:
cs
- the CharSequence to check, may be null- Returns:
true
if only contains uppercase characters, and is non-null- Since:
- 2.5, 3.0 Changed signature from isAllUpperCase(String) to isAllUpperCase(CharSequence)
-
defaultString
public static java.lang.String defaultString(java.lang.String str)
Returns either the passed in String, or if the String is
null
, an empty String ("").StringUtils.defaultString(null) = "" StringUtils.defaultString("") = "" StringUtils.defaultString("bat") = "bat"
- Parameters:
str
- the String to check, may be null- Returns:
- the passed in String, or the empty String if it
was
null
- See Also:
ObjectUtils.toString(Object)
,String.valueOf(Object)
-
defaultString
public static java.lang.String defaultString(java.lang.String str, java.lang.String defaultStr)
Returns either the passed in String, or if the String is
null
, the value ofdefaultStr
.StringUtils.defaultString(null, "NULL") = "NULL" StringUtils.defaultString("", "NULL") = "" StringUtils.defaultString("bat", "NULL") = "bat"
- Parameters:
str
- the String to check, may be nulldefaultStr
- the default String to return if the input isnull
, may be null- Returns:
- the passed in String, or the default if it was
null
- See Also:
ObjectUtils.toString(Object,String)
,String.valueOf(Object)
-
defaultIfBlank
public static <T extends java.lang.CharSequence> T defaultIfBlank(T str, T defaultStr)
Returns either the passed in CharSequence, or if the CharSequence is whitespace, empty ("") or
null
, the value ofdefaultStr
.StringUtils.defaultIfBlank(null, "NULL") = "NULL" StringUtils.defaultIfBlank("", "NULL") = "NULL" StringUtils.defaultIfBlank(" ", "NULL") = "NULL" StringUtils.defaultIfBlank("bat", "NULL") = "bat" StringUtils.defaultIfBlank("", null) = null
- Type Parameters:
T
- the specific kind of CharSequence- Parameters:
str
- the CharSequence to check, may be nulldefaultStr
- the default CharSequence to return if the input is whitespace, empty ("") ornull
, may be null- Returns:
- the passed in CharSequence, or the default
- See Also:
defaultString(String, String)
-
defaultIfEmpty
public static <T extends java.lang.CharSequence> T defaultIfEmpty(T str, T defaultStr)
Returns either the passed in CharSequence, or if the CharSequence is empty or
null
, the value ofdefaultStr
.StringUtils.defaultIfEmpty(null, "NULL") = "NULL" StringUtils.defaultIfEmpty("", "NULL") = "NULL" StringUtils.defaultIfEmpty(" ", "NULL") = " " StringUtils.defaultIfEmpty("bat", "NULL") = "bat" StringUtils.defaultIfEmpty("", null) = null
- Type Parameters:
T
- the specific kind of CharSequence- Parameters:
str
- the CharSequence to check, may be nulldefaultStr
- the default CharSequence to return if the input is empty ("") ornull
, may be null- Returns:
- the passed in CharSequence, or the default
- See Also:
defaultString(String, String)
-
reverse
public static java.lang.String reverse(java.lang.String str)
Reverses a String as per
StringBuilder.reverse()
.A
null
String returnsnull
.StringUtils.reverse(null) = null StringUtils.reverse("") = "" StringUtils.reverse("bat") = "tab"
- Parameters:
str
- the String to reverse, may be null- Returns:
- the reversed String,
null
if null String input
-
reverseDelimited
public static java.lang.String reverseDelimited(java.lang.String str, char separatorChar)
Reverses a String that is delimited by a specific character.
The Strings between the delimiters are not reversed. Thus java.lang.String becomes String.lang.java (if the delimiter is
'.'
).StringUtils.reverseDelimited(null, *) = null StringUtils.reverseDelimited("", *) = "" StringUtils.reverseDelimited("a.b.c", 'x') = "a.b.c" StringUtils.reverseDelimited("a.b.c", ".") = "c.b.a"
- Parameters:
str
- the String to reverse, may be nullseparatorChar
- the separator character to use- Returns:
- the reversed String,
null
if null String input - Since:
- 2.0
-
abbreviate
public static java.lang.String abbreviate(java.lang.String str, int maxWidth)
Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "Now is the time for..."
Specifically:
- If the number of characters in
str
is less than or equal tomaxWidth
, returnstr
. - Else abbreviate it to
(substring(str, 0, max-3) + "...")
. - If
maxWidth
is less than4
, throw anIllegalArgumentException
. - In no case will it return a String of length greater than
maxWidth
.
StringUtils.abbreviate(null, *) = null StringUtils.abbreviate("", 4) = "" StringUtils.abbreviate("abcdefg", 6) = "abc..." StringUtils.abbreviate("abcdefg", 7) = "abcdefg" StringUtils.abbreviate("abcdefg", 8) = "abcdefg" StringUtils.abbreviate("abcdefg", 4) = "a..." StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException
- Parameters:
str
- the String to check, may be nullmaxWidth
- maximum length of result String, must be at least 4- Returns:
- abbreviated String,
null
if null String input - Throws:
java.lang.IllegalArgumentException
- if the width is too small- Since:
- 2.0
- If the number of characters in
-
abbreviate
public static java.lang.String abbreviate(java.lang.String str, int offset, int maxWidth)
Abbreviates a String using ellipses. This will turn "Now is the time for all good men" into "...is the time for..."
Works like
abbreviate(String, int)
, but allows you to specify a "left edge" offset. Note that this left edge is not necessarily going to be the leftmost character in the result, or the first character following the ellipses, but it will appear somewhere in the result.In no case will it return a String of length greater than
maxWidth
.StringUtils.abbreviate(null, *, *) = null StringUtils.abbreviate("", 0, 4) = "" StringUtils.abbreviate("abcdefghijklmno", -1, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 0, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 1, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 4, 10) = "abcdefg..." StringUtils.abbreviate("abcdefghijklmno", 5, 10) = "...fghi..." StringUtils.abbreviate("abcdefghijklmno", 6, 10) = "...ghij..." StringUtils.abbreviate("abcdefghijklmno", 8, 10) = "...ijklmno" StringUtils.abbreviate("abcdefghijklmno", 10, 10) = "...ijklmno" StringUtils.abbreviate("abcdefghijklmno", 12, 10) = "...ijklmno" StringUtils.abbreviate("abcdefghij", 0, 3) = IllegalArgumentException StringUtils.abbreviate("abcdefghij", 5, 6) = IllegalArgumentException
- Parameters:
str
- the String to check, may be nulloffset
- left edge of source StringmaxWidth
- maximum length of result String, must be at least 4- Returns:
- abbreviated String,
null
if null String input - Throws:
java.lang.IllegalArgumentException
- if the width is too small- Since:
- 2.0
-
abbreviateMiddle
public static java.lang.String abbreviateMiddle(java.lang.String str, java.lang.String middle, int length)
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"
- Parameters:
str
- the String to abbreviate, may be nullmiddle
- the String to replace the middle characters with, may be nulllength
- the length to abbreviatestr
to.- Returns:
- the abbreviated String if the above criteria is met, or the original String supplied for abbreviation.
- Since:
- 2.5
-
difference
public static java.lang.String difference(java.lang.String str1, java.lang.String str2)
Compares two Strings, and returns the portion where they differ. More precisely, return the remainder of the second String, starting from where it's different from the first. This means that the difference between "abc" and "ab" is the empty String and not "c".
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("abc", "ab") = "" StringUtils.difference("ab", "abxyz") = "xyz" StringUtils.difference("abcde", "abxyz") = "xyz" StringUtils.difference("abcde", "xyz") = "xyz"
- Parameters:
str1
- the first String, may be nullstr2
- the second String, may be null- Returns:
- the portion of str2 where it differs from str1; returns the empty String if they are equal
- Since:
- 2.0
- See Also:
indexOfDifference(CharSequence,CharSequence)
-
indexOfDifference
public static int indexOfDifference(java.lang.CharSequence cs1, java.lang.CharSequence cs2)
Compares two CharSequences, and returns the index at which the CharSequences begin to differ.
For example,
indexOfDifference("i am a machine", "i am a robot") -> 7
StringUtils.indexOfDifference(null, null) = -1 StringUtils.indexOfDifference("", "") = -1 StringUtils.indexOfDifference("", "abc") = 0 StringUtils.indexOfDifference("abc", "") = 0 StringUtils.indexOfDifference("abc", "abc") = -1 StringUtils.indexOfDifference("ab", "abxyz") = 2 StringUtils.indexOfDifference("abcde", "abxyz") = 2 StringUtils.indexOfDifference("abcde", "xyz") = 0
- Parameters:
cs1
- the first CharSequence, may be nullcs2
- the second CharSequence, may be null- Returns:
- the index where cs1 and cs2 begin to differ; -1 if they are equal
- Since:
- 2.0, 3.0 Changed signature from indexOfDifference(String, String) to indexOfDifference(CharSequence, CharSequence)
-
indexOfDifference
public static int indexOfDifference(java.lang.CharSequence... css)
Compares all CharSequences in an array and returns the index at which the CharSequences 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
- Parameters:
css
- array of CharSequences, entries may be null- Returns:
- the index where the strings begin to differ; -1 if they are all equal
- Since:
- 2.4, 3.0 Changed signature from indexOfDifference(String...) to indexOfDifference(CharSequence...)
-
getCommonPrefix
public static java.lang.String getCommonPrefix(java.lang.String... strs)
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 "
- Parameters:
strs
- array of String objects, entries may be null- Returns:
- 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
-
getLevenshteinDistance
public static int getLevenshteinDistance(java.lang.CharSequence s, java.lang.CharSequence t)
Find the Levenshtein distance between two Strings.
This is the number of changes needed to change one String into another, where each change is a single character modification (deletion, insertion or substitution).
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.htmStringUtils.getLevenshteinDistance(null, *) = IllegalArgumentException StringUtils.getLevenshteinDistance(*, null) = IllegalArgumentException StringUtils.getLevenshteinDistance("","") = 0 StringUtils.getLevenshteinDistance("","a") = 1 StringUtils.getLevenshteinDistance("aaapppp", "") = 7 StringUtils.getLevenshteinDistance("frog", "fog") = 1 StringUtils.getLevenshteinDistance("fly", "ant") = 3 StringUtils.getLevenshteinDistance("elephant", "hippo") = 7 StringUtils.getLevenshteinDistance("hippo", "elephant") = 7 StringUtils.getLevenshteinDistance("hippo", "zzzzzzzz") = 8 StringUtils.getLevenshteinDistance("hello", "hallo") = 1
- Parameters:
s
- the first String, must not be nullt
- the second String, must not be null- Returns:
- result distance
- Throws:
java.lang.IllegalArgumentException
- if either String inputnull
- Since:
- 3.0 Changed signature from getLevenshteinDistance(String, String) to getLevenshteinDistance(CharSequence, CharSequence)
-
getLevenshteinDistance
public static int getLevenshteinDistance(java.lang.CharSequence s, java.lang.CharSequence t, int threshold)
Find the Levenshtein distance between two Strings if it's less than or equal to a given threshold.
This is the number of changes needed to change one String into another, where each change is a single character modification (deletion, insertion or substitution).
This implementation follows from Algorithms on Strings, Trees and Sequences by Dan Gusfield and Chas Emerick's implementation of the Levenshtein distance algorithm from http://www.merriampark.com/ld.htm
StringUtils.getLevenshteinDistance(null, *, *) = IllegalArgumentException StringUtils.getLevenshteinDistance(*, null, *) = IllegalArgumentException StringUtils.getLevenshteinDistance(*, *, -1) = IllegalArgumentException StringUtils.getLevenshteinDistance("","", 0) = 0 StringUtils.getLevenshteinDistance("aaapppp", "", 8) = 7 StringUtils.getLevenshteinDistance("aaapppp", "", 7) = 7 StringUtils.getLevenshteinDistance("aaapppp", "", 6)) = -1 StringUtils.getLevenshteinDistance("elephant", "hippo", 7) = 7 StringUtils.getLevenshteinDistance("elephant", "hippo", 6) = -1 StringUtils.getLevenshteinDistance("hippo", "elephant", 7) = 7 StringUtils.getLevenshteinDistance("hippo", "elephant", 6) = -1
- Parameters:
s
- the first String, must not be nullt
- the second String, must not be nullthreshold
- the target threshold, must not be negative- Returns:
- result distance, or
-1
if the distance would be greater than the threshold - Throws:
java.lang.IllegalArgumentException
- if either String inputnull
or negative threshold
-
getJaroWinklerDistance
public static double getJaroWinklerDistance(java.lang.CharSequence first, java.lang.CharSequence second)
Find the Jaro Winkler Distance which indicates the similarity score between two Strings.
The Jaro measure is the weighted sum of percentage of matched characters from each file and transposed characters. Winkler increased this measure for matching initial characters.
This implementation is based on the Jaro Winkler similarity algorithm from http://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance.
StringUtils.getJaroWinklerDistance(null, null) = IllegalArgumentException StringUtils.getJaroWinklerDistance("","") = 0.0 StringUtils.getJaroWinklerDistance("","a") = 0.0 StringUtils.getJaroWinklerDistance("aaapppp", "") = 0.0 StringUtils.getJaroWinklerDistance("frog", "fog") = 0.93 StringUtils.getJaroWinklerDistance("fly", "ant") = 0.0 StringUtils.getJaroWinklerDistance("elephant", "hippo") = 0.44 StringUtils.getJaroWinklerDistance("hippo", "elephant") = 0.44 StringUtils.getJaroWinklerDistance("hippo", "zzzzzzzz") = 0.0 StringUtils.getJaroWinklerDistance("hello", "hallo") = 0.88 StringUtils.getJaroWinklerDistance("ABC Corporation", "ABC Corp") = 0.91 StringUtils.getJaroWinklerDistance("D N H Enterprises Inc", "D & H Enterprises, Inc.") = 0.93 StringUtils.getJaroWinklerDistance("My Gym Children's Fitness Center", "My Gym. Childrens Fitness") = 0.94 StringUtils.getJaroWinklerDistance("PENNSYLVANIA", "PENNCISYLVNIA") = 0.9
- Parameters:
first
- the first String, must not be nullsecond
- the second String, must not be null- Returns:
- result distance
- Throws:
java.lang.IllegalArgumentException
- if either String inputnull
- Since:
- 3.3
-
getFuzzyDistance
public static int getFuzzyDistance(java.lang.CharSequence term, java.lang.CharSequence query, java.util.Locale locale)
Find the Fuzzy Distance which indicates the similarity score between two Strings.
This string matching algorithm is similar to the algorithms of editors such as Sublime Text, TextMate, Atom and others. One point is given for every matched character. Subsequent matches yield two bonus points. A higher score indicates a higher similarity.
StringUtils.getFuzzyDistance(null, null, null) = IllegalArgumentException StringUtils.getFuzzyDistance("", "", Locale.ENGLISH) = 0 StringUtils.getFuzzyDistance("Workshop", "b", Locale.ENGLISH) = 0 StringUtils.getFuzzyDistance("Room", "o", Locale.ENGLISH) = 1 StringUtils.getFuzzyDistance("Workshop", "w", Locale.ENGLISH) = 1 StringUtils.getFuzzyDistance("Workshop", "ws", Locale.ENGLISH) = 2 StringUtils.getFuzzyDistance("Workshop", "wo", Locale.ENGLISH) = 4 StringUtils.getFuzzyDistance("Apache Software Foundation", "asf", Locale.ENGLISH) = 3
- Parameters:
term
- a full term that should be matched against, must not be nullquery
- the query that will be matched against a term, must not be nulllocale
- This string matching logic is case insensitive. A locale is necessary to normalize both Strings to lower case.- Returns:
- result score
- Throws:
java.lang.IllegalArgumentException
- if either String inputnull
or Locale inputnull
- Since:
- 3.4
-
startsWith
public static boolean startsWith(java.lang.CharSequence str, java.lang.CharSequence prefix)
Check if a CharSequence starts with a specified prefix.
null
s are handled without exceptions. Twonull
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
- Parameters:
str
- the CharSequence to check, may be nullprefix
- the prefix to find, may be null- Returns:
true
if the CharSequence starts with the prefix, case sensitive, or bothnull
- Since:
- 2.4, 3.0 Changed signature from startsWith(String, String) to startsWith(CharSequence, CharSequence)
- See Also:
String.startsWith(String)
-
startsWithIgnoreCase
public static boolean startsWithIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence prefix)
Case insensitive check if a CharSequence starts with a specified prefix.
null
s are handled without exceptions. Twonull
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
- Parameters:
str
- the CharSequence to check, may be nullprefix
- the prefix to find, may be null- Returns:
true
if the CharSequence starts with the prefix, case insensitive, or bothnull
- Since:
- 2.4, 3.0 Changed signature from startsWithIgnoreCase(String, String) to startsWithIgnoreCase(CharSequence, CharSequence)
- See Also:
String.startsWith(String)
-
startsWithAny
public static boolean startsWithAny(java.lang.CharSequence string, java.lang.CharSequence... searchStrings)
Check if a CharSequence 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
- Parameters:
string
- the CharSequence to check, may be nullsearchStrings
- the CharSequences to find, may be null or empty- Returns:
true
if the CharSequence starts with any of the the prefixes, case insensitive, or bothnull
- Since:
- 2.5, 3.0 Changed signature from startsWithAny(String, String[]) to startsWithAny(CharSequence, CharSequence...)
-
endsWith
public static boolean endsWith(java.lang.CharSequence str, java.lang.CharSequence suffix)
Check if a CharSequence ends with a specified suffix.
null
s are handled without exceptions. Twonull
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
- Parameters:
str
- the CharSequence to check, may be nullsuffix
- the suffix to find, may be null- Returns:
true
if the CharSequence ends with the suffix, case sensitive, or bothnull
- Since:
- 2.4, 3.0 Changed signature from endsWith(String, String) to endsWith(CharSequence, CharSequence)
- See Also:
String.endsWith(String)
-
endsWithIgnoreCase
public static boolean endsWithIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence suffix)
Case insensitive check if a CharSequence ends with a specified suffix.
null
s are handled without exceptions. Twonull
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
- Parameters:
str
- the CharSequence to check, may be nullsuffix
- the suffix to find, may be null- Returns:
true
if the CharSequence ends with the suffix, case insensitive, or bothnull
- Since:
- 2.4, 3.0 Changed signature from endsWithIgnoreCase(String, String) to endsWithIgnoreCase(CharSequence, CharSequence)
- See Also:
String.endsWith(String)
-
normalizeSpace
public static java.lang.String normalizeSpace(java.lang.String str)
Similar to http://www.w3.org/TR/xpath/#function-normalize -space
The function returns the argument string with whitespace normalized by using
In XML Whitespace characters are the same as those allowed by the S production, which is S ::= (#x20 | #x9 | #xD | #xA)+
to remove leading and trailing whitespace and then replacing sequences of whitespace characters by a single space.trim(String)
Java's regexp pattern \s defines whitespace as [ \t\n\x0B\f\r]
For reference:
- \x0B = vertical tab
- \f = #xC = form feed
- #x20 = space
- #x9 = \t
- #xA = \n
- #xD = \r
The difference is that Java's whitespace includes vertical tab and form feed, which this functional will also normalize. Additionally
removes control characters (char <= 32) from both ends of this String.trim(String)
- Parameters:
str
- the source String to normalize whitespaces from, may be null- Returns:
- the modified string with whitespace normalized,
null
if null String input - Since:
- 3.0
- See Also:
Pattern
,trim(String)
, http://www.w3.org/TR/xpath/#function-normalize-space
-
endsWithAny
public static boolean endsWithAny(java.lang.CharSequence string, java.lang.CharSequence... searchStrings)
Check if a CharSequence 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
- Parameters:
string
- the CharSequence to check, may be nullsearchStrings
- the CharSequences to find, may be null or empty- Returns:
true
if the CharSequence ends with any of the the prefixes, case insensitive, or bothnull
- Since:
- 3.0
-
appendIfMissing
public static java.lang.String appendIfMissing(java.lang.String str, java.lang.CharSequence suffix, java.lang.CharSequence... suffixes)
Appends the suffix to the end of the string if the string does not already end with any the suffixes.StringUtils.appendIfMissing(null, null) = null StringUtils.appendIfMissing("abc", null) = "abc" StringUtils.appendIfMissing("", "xyz") = "xyz" StringUtils.appendIfMissing("abc", "xyz") = "abcxyz" StringUtils.appendIfMissing("abcxyz", "xyz") = "abcxyz" StringUtils.appendIfMissing("abcXYZ", "xyz") = "abcXYZxyz"
With additional suffixes,
StringUtils.appendIfMissing(null, null, null) = null StringUtils.appendIfMissing("abc", null, null) = "abc" StringUtils.appendIfMissing("", "xyz", null) = "xyz" StringUtils.appendIfMissing("abc", "xyz", new CharSequence[]{null}) = "abcxyz" StringUtils.appendIfMissing("abc", "xyz", "") = "abc" StringUtils.appendIfMissing("abc", "xyz", "mno") = "abcxyz" StringUtils.appendIfMissing("abcxyz", "xyz", "mno") = "abcxyz" StringUtils.appendIfMissing("abcmno", "xyz", "mno") = "abcmno" StringUtils.appendIfMissing("abcXYZ", "xyz", "mno") = "abcXYZxyz" StringUtils.appendIfMissing("abcMNO", "xyz", "mno") = "abcMNOxyz"
- Parameters:
str
- The string.suffix
- The suffix to append to the end of the string.suffixes
- Additional suffixes that are valid terminators.- Returns:
- A new String if suffix was appened, the same string otherwise.
- Since:
- 3.2
-
appendIfMissingIgnoreCase
public static java.lang.String appendIfMissingIgnoreCase(java.lang.String str, java.lang.CharSequence suffix, java.lang.CharSequence... suffixes)
Appends the suffix to the end of the string if the string does not already end, case insensitive, with any of the suffixes.StringUtils.appendIfMissingIgnoreCase(null, null) = null StringUtils.appendIfMissingIgnoreCase("abc", null) = "abc" StringUtils.appendIfMissingIgnoreCase("", "xyz") = "xyz" StringUtils.appendIfMissingIgnoreCase("abc", "xyz") = "abcxyz" StringUtils.appendIfMissingIgnoreCase("abcxyz", "xyz") = "abcxyz" StringUtils.appendIfMissingIgnoreCase("abcXYZ", "xyz") = "abcXYZ"
With additional suffixes,
StringUtils.appendIfMissingIgnoreCase(null, null, null) = null StringUtils.appendIfMissingIgnoreCase("abc", null, null) = "abc" StringUtils.appendIfMissingIgnoreCase("", "xyz", null) = "xyz" StringUtils.appendIfMissingIgnoreCase("abc", "xyz", new CharSequence[]{null}) = "abcxyz" StringUtils.appendIfMissingIgnoreCase("abc", "xyz", "") = "abc" StringUtils.appendIfMissingIgnoreCase("abc", "xyz", "mno") = "axyz" StringUtils.appendIfMissingIgnoreCase("abcxyz", "xyz", "mno") = "abcxyz" StringUtils.appendIfMissingIgnoreCase("abcmno", "xyz", "mno") = "abcmno" StringUtils.appendIfMissingIgnoreCase("abcXYZ", "xyz", "mno") = "abcXYZ" StringUtils.appendIfMissingIgnoreCase("abcMNO", "xyz", "mno") = "abcMNO"
- Parameters:
str
- The string.suffix
- The suffix to append to the end of the string.suffixes
- Additional suffixes that are valid terminators.- Returns:
- A new String if suffix was appened, the same string otherwise.
- Since:
- 3.2
-
prependIfMissing
public static java.lang.String prependIfMissing(java.lang.String str, java.lang.CharSequence prefix, java.lang.CharSequence... prefixes)
Prepends the prefix to the start of the string if the string does not already start with any of the prefixes.StringUtils.prependIfMissing(null, null) = null StringUtils.prependIfMissing("abc", null) = "abc" StringUtils.prependIfMissing("", "xyz") = "xyz" StringUtils.prependIfMissing("abc", "xyz") = "xyzabc" StringUtils.prependIfMissing("xyzabc", "xyz") = "xyzabc" StringUtils.prependIfMissing("XYZabc", "xyz") = "xyzXYZabc"
With additional prefixes,
StringUtils.prependIfMissing(null, null, null) = null StringUtils.prependIfMissing("abc", null, null) = "abc" StringUtils.prependIfMissing("", "xyz", null) = "xyz" StringUtils.prependIfMissing("abc", "xyz", new CharSequence[]{null}) = "xyzabc" StringUtils.prependIfMissing("abc", "xyz", "") = "abc" StringUtils.prependIfMissing("abc", "xyz", "mno") = "xyzabc" StringUtils.prependIfMissing("xyzabc", "xyz", "mno") = "xyzabc" StringUtils.prependIfMissing("mnoabc", "xyz", "mno") = "mnoabc" StringUtils.prependIfMissing("XYZabc", "xyz", "mno") = "xyzXYZabc" StringUtils.prependIfMissing("MNOabc", "xyz", "mno") = "xyzMNOabc"
- Parameters:
str
- The string.prefix
- The prefix to prepend to the start of the string.prefixes
- Additional prefixes that are valid.- Returns:
- A new String if prefix was prepended, the same string otherwise.
- Since:
- 3.2
-
prependIfMissingIgnoreCase
public static java.lang.String prependIfMissingIgnoreCase(java.lang.String str, java.lang.CharSequence prefix, java.lang.CharSequence... prefixes)
Prepends the prefix to the start of the string if the string does not already start, case insensitive, with any of the prefixes.StringUtils.prependIfMissingIgnoreCase(null, null) = null StringUtils.prependIfMissingIgnoreCase("abc", null) = "abc" StringUtils.prependIfMissingIgnoreCase("", "xyz") = "xyz" StringUtils.prependIfMissingIgnoreCase("abc", "xyz") = "xyzabc" StringUtils.prependIfMissingIgnoreCase("xyzabc", "xyz") = "xyzabc" StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz") = "XYZabc"
With additional prefixes,
StringUtils.prependIfMissingIgnoreCase(null, null, null) = null StringUtils.prependIfMissingIgnoreCase("abc", null, null) = "abc" StringUtils.prependIfMissingIgnoreCase("", "xyz", null) = "xyz" StringUtils.prependIfMissingIgnoreCase("abc", "xyz", new CharSequence[]{null}) = "xyzabc" StringUtils.prependIfMissingIgnoreCase("abc", "xyz", "") = "abc" StringUtils.prependIfMissingIgnoreCase("abc", "xyz", "mno") = "xyzabc" StringUtils.prependIfMissingIgnoreCase("xyzabc", "xyz", "mno") = "xyzabc" StringUtils.prependIfMissingIgnoreCase("mnoabc", "xyz", "mno") = "mnoabc" StringUtils.prependIfMissingIgnoreCase("XYZabc", "xyz", "mno") = "XYZabc" StringUtils.prependIfMissingIgnoreCase("MNOabc", "xyz", "mno") = "MNOabc"
- Parameters:
str
- The string.prefix
- The prefix to prepend to the start of the string.prefixes
- Additional prefixes that are valid (optional).- Returns:
- A new String if prefix was prepended, the same string otherwise.
- Since:
- 3.2
-
toString
@Deprecated public static java.lang.String toString(byte[] bytes, java.lang.String charsetName) throws java.io.UnsupportedEncodingException
Deprecated.usetoEncodedString(byte[], Charset)
instead of String constants in your codeConverts abyte[]
to a String using the specified character encoding.- Parameters:
bytes
- the byte array to read fromcharsetName
- the encoding to use, if null then use the platform default- Returns:
- a new String
- Throws:
java.io.UnsupportedEncodingException
- If the named charset is not supportedjava.lang.NullPointerException
- if the input is null- Since:
- 3.1
-
toEncodedString
public static java.lang.String toEncodedString(byte[] bytes, java.nio.charset.Charset charset)
Converts abyte[]
to a String using the specified character encoding.- Parameters:
bytes
- the byte array to read fromcharset
- the encoding to use, if null then use the platform default- Returns:
- a new String
- Throws:
java.lang.NullPointerException
- ifbytes
is null- Since:
- 3.2, 3.3 No longer throws
UnsupportedEncodingException
.
-
wrap
public static java.lang.String wrap(java.lang.String str, char wrapWith)
Wraps a string with a char.
StringUtils.wrap(null, *) = null StringUtils.wrap("", *) = "" StringUtils.wrap("ab", '\0') = "ab" StringUtils.wrap("ab", 'x') = "xabx" StringUtils.wrap("ab", '\'') = "'ab'" StringUtils.wrap("\"ab\"", '\"') = "\"\"ab\"\""
- Parameters:
str
- the string to be wrapped, may benull
wrapWith
- the char that will wrapstr
- Returns:
- the wrapped string, or
null
ifstr==null
- Since:
- 3.4
-
wrap
public static java.lang.String wrap(java.lang.String str, java.lang.String wrapWith)
Wraps a String with another String.
A
null
input String returnsnull
.StringUtils.wrap(null, *) = null StringUtils.wrap("", *) = "" StringUtils.wrap("ab", null) = "ab" StringUtils.wrap("ab", "x") = "xabx" StringUtils.wrap("ab", "\"") = "\"ab\"" StringUtils.wrap("\"ab\"", "\"") = "\"\"ab\"\"" StringUtils.wrap("ab", "'") = "'ab'" StringUtils.wrap("'abcd'", "'") = "''abcd''" StringUtils.wrap("\"abcd\"", "'") = "'\"abcd\"'" StringUtils.wrap("'abcd'", "\"") = "\"'abcd'\""
- Parameters:
str
- the String to be wrapper, may be nullwrapWith
- the String that will wrap str- Returns:
- wrapped String,
null
if null String input - Since:
- 3.4
-
-