org.apache.commons.lang3

Class StringUtils

java.lang.Object

org.apache.commons.lang3.StringUtils

public class StringUtils
extends java.lang.Object

Operations on String that are null safe.

• IsEmpty/IsBlank - checks if a String contains text
• Trim/Strip - removes leading and trailing whitespace
• Equals - compares two strings null-safe
• startsWith - check if a String starts with a prefix null-safe
• endsWith - check if a String ends with a suffix null-safe
• IndexOf/LastIndexOf/Contains - null-safe index-of checks
• IndexOfAny/LastIndexOfAny/IndexOfAnyBut/LastIndexOfAnyBut - index-of any of a set of Strings
• ContainsOnly/ContainsNone/ContainsAny - does String contains only/none/any of these characters
• Substring/Left/Right/Mid - null-safe substring extractions
• SubstringBefore/SubstringAfter/SubstringBetween - substring extraction relative to other strings
• Split/Join - splits a String into an array of substrings and vice versa
• Remove/Delete - removes part of a String
• Replace/Overlay - Searches a String and replaces one String with another
• Chomp/Chop - removes the last part of a String
• 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 handles null input Strings quietly. That is to say that a null input will return null. Where a boolean or int is being returned details vary by method.

A side effect of the null handling is that a NullPointerException should be considered a bug in StringUtils.

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

#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 and 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 and Description
StringUtils() StringUtils instances should NOT be constructed in standard programming.

Method Summary

Methods

Modifier and Type	Method and 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 per Character.toTitleCase(char).
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 (' ').
static java.lang.String	center(java.lang.String str, int size, char padChar) Centers a String in a larger String of size size.
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.
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, use removeEnd(String, String) instead
static java.lang.String	chop(java.lang.String str) Remove the last character from a String.
static boolean	contains(java.lang.CharSequence seq, java.lang.CharSequence searchSeq) Checks if CharSequence contains a search CharSequence, handling null.
static boolean	contains(java.lang.CharSequence seq, int searchChar) Checks if CharSequence contains a search character, handling null.
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... searchCharSequences) Checks if the CharSequence contains any of the CharSequences in the given array.
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	containsIgnoreCase(java.lang.CharSequence str, java.lang.CharSequence searchStr) Checks if CharSequence contains a search CharSequence irrespective of case, handling null.
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> T	defaultIfBlank(T str, T defaultStr) Returns either the passed in CharSequence, or if the CharSequence is whitespace, empty ("") or null, the value of defaultStr.
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 of defaultStr.
static java.lang.String	defaultString(java.lang.String str) Returns either the passed in String, or if the String is null, 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 is null, the value of defaultStr.
static java.lang.String	deleteWhitespace(java.lang.String str) Deletes all whitespaces from a String as defined by Character.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, returning true if they represent equal sequences of characters.
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.
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, java.lang.CharSequence searchSeq) Finds the first index within a CharSequence, handling null.
static int	indexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq, int startPos) Finds the first index within a CharSequence, handling null.
static int	indexOf(java.lang.CharSequence seq, int searchChar) Finds the first index within a CharSequence, handling null.
static int	indexOf(java.lang.CharSequence seq, int searchChar, int startPos) Finds the first index within a CharSequence from a start position, handling null.
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(java.lang.Iterable<?> iterable, char separator) Joins the elements of the provided Iterable 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 provided Iterable into a single String containing the provided elements.
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.
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.
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(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(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 <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, java.lang.CharSequence searchSeq) Finds the last index within a CharSequence, handling null.
static int	lastIndexOf(java.lang.CharSequence seq, java.lang.CharSequence searchSeq, int startPos) Finds the last index within a CharSequence, handling null.
static int	lastIndexOf(java.lang.CharSequence seq, int searchChar) Finds the last index within a CharSequence, handling null.
static int	lastIndexOf(java.lang.CharSequence seq, int searchChar, int startPos) Finds the last index within a CharSequence from a start position, handling null.
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, handling null.
static java.lang.String	left(java.lang.String str, int len) Gets the leftmost len 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 or 0 if the CharSequence is null.
static java.lang.String	lowerCase(java.lang.String str) Converts a String to lower case as per String.toLowerCase().
static java.lang.String	lowerCase(java.lang.String str, java.util.Locale locale) Converts a String to lower case as per String.toLowerCase(Locale).
static java.lang.String	mid(java.lang.String str, int pos, int len) Gets len characters from the middle of a String.
static java.lang.String	normalizeSpace(java.lang.String str) Similar to http://www.w3.org/TR/xpath/#function-normalize -space
static int	ordinalIndexOf(java.lang.CharSequence str, java.lang.CharSequence searchStr, int ordinal) Finds the n-th index within a CharSequence, handling null.
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 String repeat times to form a new String.
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.
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 first max 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 the Pattern.DOTALL option.
static java.lang.String	reverse(java.lang.String str) Reverses a String as per StringBuilder.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 rightmost len 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 by java.lang.Character.getType(char).
static java.lang.String[]	splitByCharacterTypeCamelCase(java.lang.String str) Splits a String by Character type as returned by java.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 if null input.
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.
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 a byte[] to a String using the specified character encoding.
static java.lang.String	toString(byte[] bytes, java.lang.String charsetName) Deprecated. use toEncodedString(byte[], Charset) instead of String constants in your code
static java.lang.String	trim(java.lang.String str) Removes control characters (char <= 32) from both ends of this String, handling null by returning null.
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.
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 is null.
static java.lang.String	uncapitalize(java.lang.String str) Uncapitalizes a String changing the first letter to title case as per Character.toLowerCase(char).
static java.lang.String	upperCase(java.lang.String str) Converts a String to upper case as per String.toUpperCase().
static java.lang.String	upperCase(java.lang.String str, java.util.Locale locale) Converts a String to upper case as per String.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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

Constructor Detail

StringUtils

public StringUtils()

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

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

Method 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 returning null.

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

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

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

Parameters:

str - the String to be trimmed, may be null

Returns:

the trimmed string, null if null String input

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 is null.

The String is trimmed using String.trim(). Trim removes start and end characters <= 32. To strip whitespace use stripToNull(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 use stripToEmpty(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 by Character.isWhitespace(char).

A null input String returns null.

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

Parameters:

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

Returns:

the stripped String, null if null String input

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 by Character.isWhitespace(char).

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

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 by Character.isWhitespace(char).

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

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 returns null. An empty string ("") input returns the empty string.

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

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

Parameters:

str - the String to remove characters from, may be null

stripChars - the characters to remove, null treated as whitespace

Returns:

the stripped String, null if null String input

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 returns null. An empty string ("") input returns the empty string.

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

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

Parameters:

str - the String to remove characters from, may be null

stripChars - the characters to remove, null treated as whitespace

Returns:

the stripped String, null if null String input

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 returns null. An empty string ("") input returns the empty string.

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

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

Parameters:

str - the String to remove characters from, may be null

stripChars - 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 return null. An empty array will return itself. A null array entry will be ignored.

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

Parameters:

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

Returns:

the stripped Strings, null if null array input

stripAll

public static 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 return null. An empty array will return itself. A null array entry will be ignored. A null stripChars will strip whitespace as defined by Character.isWhitespace(char).

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

Parameters:

strs - the array to remove characters from, may be null

stripChars - the characters to remove, null treated as whitespace

Returns:

the stripped Strings, null if null array input

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.

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

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

Parameters:

cs1 - the first CharSequence, may be null

cs2 - the second CharSequence, may be null

Returns:

true if the CharSequences are equal (case-sensitive), or both null

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.

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

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

Parameters:

str1 - the first CharSequence, may be null

str2 - the second CharSequence, may be null

Returns:

true if the CharSequence are equal, case insensitive, or both null

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 uses String.indexOf(int, int) if possible.

A null or empty ("") CharSequence will return INDEX_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 null

searchChar - the character to find

Returns:

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

Since:

2.0, 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 uses String.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 null

searchChar - the character to find

startPos - 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 uses String.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 null

searchSeq - 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 uses String.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 null

searchSeq - the CharSequence to find, may be null

startPos - 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 uses String.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 null

searchStr - the CharSequence to find, may be null

ordinal - the n-th searchStr to find

Returns:

the n-th index of the search CharSequence, -1 (INDEX_NOT_FOUND) if no match or null 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 null

searchStr - 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 null

searchStr - the CharSequence to find, may be null

startPos - 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 uses String.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 null

searchChar - the character to find

Returns:

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

Since:

2.0, 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 uses String.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 null

searchChar - the character to find

startPos - 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 uses String.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 null

searchSeq - 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 uses String.lastIndexOf(String).

A null String will return -1.

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

Note that 'tail(CharSequence str, int n)' may be implemented as:

   str.substring(lastOrdinalIndexOf(str, "\n", n) + 1)
 

Parameters:

str - the CharSequence to check, may be null

searchStr - the CharSequence to find, may be null

ordinal - the n-th last searchStr to find

Returns:

the n-th last index of the search CharSequence, -1 (INDEX_NOT_FOUND) if no match or null 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 uses String.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 null

searchSeq - the CharSequence to find, may be null

startPos - 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 null

searchStr - 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 null

searchStr - the CharSequence to find, may be null

startPos - 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 uses String.indexOf(int) if possible.

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

 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 null

searchChar - 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 uses String.indexOf(String) if possible.

A null CharSequence will return false.

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

Parameters:

seq - the CharSequence to check, may be null

searchSeq - 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 by String.equalsIgnoreCase(String).

A null CharSequence will return false.

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

Parameters:

str - the CharSequence to check, may be null

searchStr - 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 be null)

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. A null or zero length search array will return -1.

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

Parameters:

cs - the CharSequence to check, may be null

searchChars - the chars to search for, may be null

Returns:

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

Since:

2.0, 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. A null search string will return -1.

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

Parameters:

cs - the CharSequence to check, may be null

searchChars - the chars to search for, may be null

Returns:

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

Since:

2.0, 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 return false. A null or zero length search array will return false.

 StringUtils.containsAny(null, *)                = false
 StringUtils.containsAny("", *)                  = false
 StringUtils.containsAny(*, null)                = false
 StringUtils.containsAny(*, [])                  = false
 StringUtils.containsAny("zzabyycdxx",['z','a']) = true
 StringUtils.containsAny("zzabyycdxx",['b','y']) = true
 StringUtils.containsAny("aba", ['z'])           = false
 

Parameters:

cs - the CharSequence to check, may be null

searchChars - 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 return false. A null search CharSequence will return false.

 StringUtils.containsAny(null, *)            = false
 StringUtils.containsAny("", *)              = false
 StringUtils.containsAny(*, null)            = false
 StringUtils.containsAny(*, "")              = false
 StringUtils.containsAny("zzabyycdxx", "za") = true
 StringUtils.containsAny("zzabyycdxx", "by") = true
 StringUtils.containsAny("aba","z")          = false
 

Parameters:

cs - the CharSequence to check, may be null

searchChars - 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 return false. A null or zero length search array will return false.

 StringUtils.containsAny(null, *)            = false
 StringUtils.containsAny("", *)              = false
 StringUtils.containsAny(*, null)            = false
 StringUtils.containsAny(*, [])              = false
 StringUtils.containsAny("abcd", "ab", "cd") = false
 StringUtils.containsAny("abc", "d", "abc")  = true
 

Parameters:

cs - The CharSequence to check, may be null

searchCharSequences - 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. A null or zero length search array will return -1.

 StringUtils.indexOfAnyBut(null, *)                              = -1
 StringUtils.indexOfAnyBut("", *)                                = -1
 StringUtils.indexOfAnyBut(*, null)                              = -1
 StringUtils.indexOfAnyBut(*, [])                                = -1
 StringUtils.indexOfAnyBut("zzabyycdxx", new char[] {'z', 'a'} ) = 3
 StringUtils.indexOfAnyBut("aba", new char[] {'z'} )             = 0
 StringUtils.indexOfAnyBut("aba", new char[] {'a', 'b'} )        = -1

 

Parameters:

cs - the CharSequence to check, may be null

searchChars - the chars to search for, may be null

Returns:

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

Since:

2.0, 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. A null or empty search string will return -1.

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

Parameters:

seq - the CharSequence to check, may be null

searchChars - the chars to search for, may be null

Returns:

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

Since:

2.0, 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 return false. A null valid character array will return false. An empty CharSequence (length()=0) always returns true.

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

Parameters:

cs - the String to check, may be null

valid - an array of valid chars, may be null

Returns:

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

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 return false. A null valid character String will return false. An empty String (length()=0) always returns true.

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

Parameters:

cs - the CharSequence to check, may be null

validChars - a String of valid chars, may be null

Returns:

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

Since:

2.0, 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 return true. A null invalid character array will return true. 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 null

searchChars - 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 return true. A null invalid character array will return true. An empty String ("") always returns true.

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

Parameters:

cs - the CharSequence to check, may be null

invalidChars - a String of invalid chars, may be null

Returns:

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

Since:

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

searchStrs - 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. A null search array will return -1. A null or zero length search array entry will be ignored, but a search array containing "" will return the length of str if str is not null. This method uses String.indexOf(String) if possible

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

Parameters:

str - the CharSequence to check, may be null

searchStrs - 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 return null. An empty ("") String will return "".

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

Parameters:

str - the String to get the substring from, may be null

start - the position to start from, negative means count back from the end of the String by this many characters

Returns:

substring from start position, null if null String input

substring

public static 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 the end position. All position counting is zero-based -- i.e., to start at the beginning of the string use start = 0. Negative start and end positions can be used to specify offsets relative to the end of the String.

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

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

Parameters:

str - the String to get the substring from, may be null

start - the position to start from, negative means count back from the end of the String by this many characters

end - the position to end at (exclusive), negative means count back from the end of the String by this many characters

Returns:

substring from start position to end 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 is null, the String will be returned without an exception. An empty String is returned if len is negative.

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

Parameters:

str - the String to get the leftmost characters from, may be null

len - 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 is null, the String will be returned without an an exception. An empty String is returned if len is negative.

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

Parameters:

str - the String to get the rightmost characters from, may be null

len - 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 is null, null will be returned. An empty String is returned if len is negative or exceeds the length of str.

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

Parameters:

str - the String to get the characters from, may be null

pos - the position to start from, negative treated as zero

len - the length of the required String

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 return null. An empty ("") string input will return the empty string. A null separator will return the input string.

If nothing is found, the string input is returned.

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

Parameters:

str - the String to get a substring from, may be null

separator - the String to search for, may be null

Returns:

the substring before the first 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 return null. An empty ("") string input will return the empty string. A null separator will return the empty string if the input string is not null.

If nothing is found, the empty string is returned.

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

Parameters:

str - the String to get a substring from, may be null

separator - the String to search for, may be null

Returns:

the substring after the first 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 return null. An empty ("") string input will return the empty string. An empty or null separator will return the input string.

If nothing is found, the string input is returned.

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

Parameters:

str - the String to get a substring from, may be null

separator - the String to search for, may be null

Returns:

the substring before the last 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 return null. An empty ("") string input will return the empty string. An empty or null separator will return the empty string if the input string is not null.

If nothing is found, the empty string is returned.

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

Parameters:

str - the String to get a substring from, may be null

separator - the String to search for, may be null

Returns:

the substring after the last 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 returns null. A null tag returns null.

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

Parameters:

str - the String containing the substring, may be null

tag - the String before and after the substring, may be null

Returns:

the substring, null if no match

Since:

2.0

substringBetween

public static 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 returns null. A null open/close returns null (no match). An empty ("") open and close returns an empty string.

 StringUtils.substringBetween("wx[b]yz", "[", "]") = "b"
 StringUtils.substringBetween(null, *, *)          = null
 StringUtils.substringBetween(*, null, *)          = null
 StringUtils.substringBetween(*, *, null)          = null
 StringUtils.substringBetween("", "", "")          = ""
 StringUtils.substringBetween("", "", "]")         = null
 StringUtils.substringBetween("", "[", "]")        = null
 StringUtils.substringBetween("yabcz", "", "")     = ""
 StringUtils.substringBetween("yabcz", "y", "z")   = "abc"
 StringUtils.substringBetween("yabczyabcz", "y", "z")   = "abc"
 

Parameters:

str - the String containing the substring, may be null

open - the String before the substring, may be null

close - the String after the substring, may be null

Returns:

the substring, null if no match

Since:

2.0

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 returns null. A null open/close returns null (no match). An empty ("") open/close returns null (no match).

 StringUtils.substringsBetween("[a][b][c]", "[", "]") = ["a","b","c"]
 StringUtils.substringsBetween(null, *, *)            = null
 StringUtils.substringsBetween(*, null, *)            = null
 StringUtils.substringsBetween(*, *, null)            = null
 StringUtils.substringsBetween("", "[", "]")          = []
 

Parameters:

str - the String containing the substrings, null returns null, empty returns empty

open - the String identifying the start of the substring, empty returns null

close - 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 returns null.

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

Parameters:

str - the String to parse, may be null

Returns:

an array of parsed Strings, null if null String input

split

public static 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 returns null.

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

Parameters:

str - the String to parse, may be null

separatorChar - 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 returns null. A null separatorChars splits on whitespace.

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

Parameters:

str - the String to parse, may be null

separatorChars - the characters used as the delimiters, null splits on whitespace

Returns:

an array of parsed Strings, null if null String input

split

public static 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 returns null. A null separatorChars splits on whitespace.

If more than max delimited substrings are found, the last returned string includes all characters after the first max - 1 returned strings (including separator characters).

 StringUtils.split(null, *, *)            = null
 StringUtils.split("", *, *)              = []
 StringUtils.split("ab 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 null

separatorChars - the characters used as the delimiters, null splits on whitespace

max - the maximum number of elements to include in the array. A zero or negative value implies no limit

Returns:

an array of parsed Strings, null if null String input

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 returns null. A null separator splits on whitespace.

 StringUtils.splitByWholeSeparator(null, *)               = null
 StringUtils.splitByWholeSeparator("", *)                 = []
 StringUtils.splitByWholeSeparator("ab de fg", null)      = ["ab", "de", "fg"]
 StringUtils.splitByWholeSeparator("ab   de fg", null)    = ["ab", "de", "fg"]
 StringUtils.splitByWholeSeparator("ab:cd:ef", ":")       = ["ab", "cd", "ef"]
 StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]
 

Parameters:

str - the String to parse, may be null

separator - 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 returns null. A null separator splits on whitespace.

 StringUtils.splitByWholeSeparator(null, *, *)               = null
 StringUtils.splitByWholeSeparator("", *, *)                 = []
 StringUtils.splitByWholeSeparator("ab de fg", null, 0)      = ["ab", "de", "fg"]
 StringUtils.splitByWholeSeparator("ab   de fg", null, 0)    = ["ab", "de", "fg"]
 StringUtils.splitByWholeSeparator("ab:cd:ef", ":", 2)       = ["ab", "cd:ef"]
 StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
 StringUtils.splitByWholeSeparator("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
 

Parameters:

str - the String to parse, may be null

separator - String containing the String to be used as a delimiter, null splits on whitespace

max - 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 returns null. A null separator splits on whitespace.

 StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *)               = null
 StringUtils.splitByWholeSeparatorPreserveAllTokens("", *)                 = []
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null)      = ["ab", "de", "fg"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null)    = ["ab", "", "", "de", "fg"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":")       = ["ab", "cd", "ef"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-") = ["ab", "cd", "ef"]
 

Parameters:

str - the String to parse, may be null

separator - 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 returns null. A null separator splits on whitespace.

 StringUtils.splitByWholeSeparatorPreserveAllTokens(null, *, *)               = null
 StringUtils.splitByWholeSeparatorPreserveAllTokens("", *, *)                 = []
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab de fg", null, 0)      = ["ab", "de", "fg"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab   de fg", null, 0)    = ["ab", "", "", "de", "fg"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab:cd:ef", ":", 2)       = ["ab", "cd:ef"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 5) = ["ab", "cd", "ef"]
 StringUtils.splitByWholeSeparatorPreserveAllTokens("ab-!-cd-!-ef", "-!-", 2) = ["ab", "cd-!-ef"]
 

Parameters:

str - the String to parse, may be null

separator - String containing the String to be used as a delimiter, null splits on whitespace

max - 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 returns null.

 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 be null

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 returns null.

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

Parameters:

str - the String to parse, may be null

separatorChar - the character used as the delimiter, null splits on whitespace

Returns:

an array of parsed Strings, null if null String input

Since:

2.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 returns null. A null separatorChars splits on whitespace.

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

Parameters:

str - the String to parse, may be null

separatorChars - the characters used as the delimiters, null splits on whitespace

Returns:

an array of parsed Strings, null if null String input

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 returns null. A null separatorChars splits on whitespace.

If more than max delimited substrings are found, the last returned string includes all characters after the first max - 1 returned strings (including separator characters).

 StringUtils.splitPreserveAllTokens(null, *, *)            = null
 StringUtils.splitPreserveAllTokens("", *, *)              = []
 StringUtils.splitPreserveAllTokens("ab de fg", null, 0)   = ["ab", "cd", "ef"]
 StringUtils.splitPreserveAllTokens("ab   de fg", null, 0) = ["ab", "cd", "ef"]
 StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 0)    = ["ab", "cd", "ef"]
 StringUtils.splitPreserveAllTokens("ab:cd:ef", ":", 2)    = ["ab", "cd:ef"]
 StringUtils.splitPreserveAllTokens("ab   de fg", null, 2) = ["ab", "  de fg"]
 StringUtils.splitPreserveAllTokens("ab   de fg", null, 3) = ["ab", "", " de fg"]
 StringUtils.splitPreserveAllTokens("ab   de fg", null, 4) = ["ab", "", "", "de fg"]
 

Parameters:

str - the String to parse, may be null

separatorChars - the characters used as the delimiters, null splits on whitespace

max - the maximum number of elements to include in the array. A zero or negative value implies no limit

Returns:

an array of parsed Strings, null if null String input

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 be null

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 type Character.UPPERCASE_LETTER, if any, immediately preceding a token of type Character.LOWERCASE_LETTER will belong to the following token rather than to the preceding, if any, Character.UPPERCASE_LETTER token.

 StringUtils.splitByCharacterTypeCamelCase(null)         = null
 StringUtils.splitByCharacterTypeCamelCase("")           = []
 StringUtils.splitByCharacterTypeCamelCase("ab de fg")   = ["ab", " ", "de", " ", "fg"]
 StringUtils.splitByCharacterTypeCamelCase("ab   de fg") = ["ab", "   ", "de", " ", "fg"]
 StringUtils.splitByCharacterTypeCamelCase("ab:cd:ef")   = ["ab", ":", "cd", ":", "ef"]
 StringUtils.splitByCharacterTypeCamelCase("number5")    = ["number", "5"]
 StringUtils.splitByCharacterTypeCamelCase("fooBar")     = ["foo", "Bar"]
 StringUtils.splitByCharacterTypeCamelCase("foo200Bar")  = ["foo", "200", "Bar"]
 StringUtils.splitByCharacterTypeCamelCase("ASFRules")   = ["ASF", "Rules"]
 

Parameters:

str - the String to split, may be null

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 null

separator - 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 null

separator - 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 null

separator - 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 null

separator - 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 null

separator - 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 null

separator - 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 null

separator - 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 null

separator - 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 null

separator - the separator character to use

startIndex - the first index to start joining from. It is an error to pass in an end index past the end of the array

endIndex - 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 null

separator - the separator character to use

startIndex - the first index to start joining from. It is an error to pass in an end index past the end of the array

endIndex - 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 null

separator - the separator character to use

startIndex - the first index to start joining from. It is an error to pass in an end index past the end of the array

endIndex - 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 null

separator - the separator character to use

startIndex - the first index to start joining from. It is an error to pass in an end index past the end of the array

endIndex - 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 null

separator - the separator character to use

startIndex - the first index to start joining from. It is an error to pass in an end index past the end of the array

endIndex - 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 null

separator - the separator character to use

startIndex - the first index to start joining from. It is an error to pass in an end index past the end of the array

endIndex - 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 null

separator - the separator character to use

startIndex - the first index to start joining from. It is an error to pass in an end index past the end of the array

endIndex - 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 null

separator - the separator character to use

startIndex - the first index to start joining from. It is an error to pass in an end index past the end of the array

endIndex - 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 null

separator - 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 null

separator - 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 if endIndex - startIndex <= 0. The number of joined entries is given by endIndex - 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 - the Iterator of values to join together, may be null

separator - the separator character to use

Returns:

the joined String, null if null iterator input

Since:

2.0

join

public static 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 - the Iterator of values to join together, may be null

separator - the separator character to use, null treated as ""

Returns:

the joined String, null if null iterator input

join

public static 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 - the Iterable providing the values to join together, may be null

separator - 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 - the Iterable providing the values to join together, may be null

separator - the separator character to use, null treated as ""

Returns:

the joined String, null if null iterator input

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 return null. An empty ("") source string will return the empty string. A null search string will return the source string.

 StringUtils.removeStart(null, *)      = null
 StringUtils.removeStart("", *)        = ""
 StringUtils.removeStart(*, null)      = *
 StringUtils.removeStart("www.domain.com", "www.")   = "domain.com"
 StringUtils.removeStart("domain.com", "www.")       = "domain.com"
 StringUtils.removeStart("www.domain.com", "domain") = "www.domain.com"
 StringUtils.removeStart("abc", "")    = "abc"
 

Parameters:

str - the source String to search, may be null

remove - 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 return null. An empty ("") source string will return the empty string. A null search string will return the source string.

 StringUtils.removeStartIgnoreCase(null, *)      = null
 StringUtils.removeStartIgnoreCase("", *)        = ""
 StringUtils.removeStartIgnoreCase(*, null)      = *
 StringUtils.removeStartIgnoreCase("www.domain.com", "www.")   = "domain.com"
 StringUtils.removeStartIgnoreCase("www.domain.com", "WWW.")   = "domain.com"
 StringUtils.removeStartIgnoreCase("domain.com", "www.")       = "domain.com"
 StringUtils.removeStartIgnoreCase("www.domain.com", "domain") = "www.domain.com"
 StringUtils.removeStartIgnoreCase("abc", "")    = "abc"
 

Parameters:

str - the source String to search, may be null

remove - 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 return null. An empty ("") source string will return the empty string. A null search string will return the source string.

 StringUtils.removeEnd(null, *)      = null
 StringUtils.removeEnd("", *)        = ""
 StringUtils.removeEnd(*, null)      = *
 StringUtils.removeEnd("www.domain.com", ".com.")  = "www.domain.com"
 StringUtils.removeEnd("www.domain.com", ".com")   = "www.domain"
 StringUtils.removeEnd("www.domain.com", "domain") = "www.domain.com"
 StringUtils.removeEnd("abc", "")    = "abc"
 

Parameters:

str - the source String to search, may be null

remove - 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 return null. An empty ("") source string will return the empty string. A null search string will return the source string.

 StringUtils.removeEndIgnoreCase(null, *)      = null
 StringUtils.removeEndIgnoreCase("", *)        = ""
 StringUtils.removeEndIgnoreCase(*, null)      = *
 StringUtils.removeEndIgnoreCase("www.domain.com", ".com.")  = "www.domain.com"
 StringUtils.removeEndIgnoreCase("www.domain.com", ".com")   = "www.domain"
 StringUtils.removeEndIgnoreCase("www.domain.com", "domain") = "www.domain.com"
 StringUtils.removeEndIgnoreCase("abc", "")    = "abc"
 StringUtils.removeEndIgnoreCase("www.domain.com", ".COM") = "www.domain")
 StringUtils.removeEndIgnoreCase("www.domain.COM", ".com") = "www.domain")
 

Parameters:

str - the source String to search, may be null

remove - 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 return null. An empty ("") source string will return the empty string. A null remove string will return the source string. An empty ("") remove string will return the source string.

 StringUtils.remove(null, *)        = null
 StringUtils.remove("", *)          = ""
 StringUtils.remove(*, null)        = *
 StringUtils.remove(*, "")          = *
 StringUtils.remove("queued", "ue") = "qd"
 StringUtils.remove("queued", "zz") = "queued"
 

Parameters:

str - the source String to search, may be null

remove - 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 return null. An empty ("") source string will return the empty string.

 StringUtils.remove(null, *)       = null
 StringUtils.remove("", *)         = ""
 StringUtils.remove("queued", 'u') = "qeed"
 StringUtils.remove("queued", 'z') = "queued"
 

Parameters:

str - the source String to search, may be null

remove - 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 null

searchString - the String to search for, may be null

replacement - 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 the Pattern.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 string

regex - the regular expression to which this string is to be matched

replacement - 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 string

regex - 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 null

searchString - the String to search for, may be null

replacement - 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 null

searchString - the String to search for, may be null

replacement - the String to replace it with, may be null

max - maximum number of values to replace, or -1 if no maximum

Returns:

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

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 null

searchList - the Strings to search for, no-op if null

replacementList - 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 null

searchList - the Strings to search for, no-op if null

replacementList - 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 another

java.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 returns null. An empty ("") string input returns an empty string.

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

Parameters:

str - String to replace characters in, may be null

searchChar - the character to search for, may be null

replaceChar - the character to replace, may be null

Returns:

modified String, null if null string input

Since:

2.0

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 returns null. An empty ("") string input returns an empty string. A null or empty set of search characters returns the input string.

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

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

Parameters:

str - String to replace characters in, may be null

searchChars - a set of characters to search for, may be null

replaceChars - a set of characters to replace, may be null

Returns:

modified String, null if null string input

Since:

2.0

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 returns null. A negative index is treated as zero. An index greater than the string length is treated as the string length. The start index is always the smaller of the two indices.

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

Parameters:

str - the String to do overlaying in, may be null

overlay - the String to overlay, may be null

start - the position to start overlaying at

end - the position to stop overlaying before

Returns:

overlayed String, null if null String input

Since:

2.0

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, use removeEnd(String, String) instead

Removes separator from the end of str if it's there, otherwise leave it alone.

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

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

Parameters:

str - the String to chomp from, may be null

separator - separator String, may be null

Returns:

String without trailing separator, null if null String input

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 null

repeat - number of times to repeat str, negative treated as zero

Returns:

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

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 null

separator - the String to inject, may be null

repeat - number of times to repeat str, negative treated as zero

Returns:

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

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 chars to be represented. If you are needing to support full I18N of your applications consider using repeat(String, int) instead.

Parameters:

ch - character to repeat

repeat - 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 null

size - the size to pad to

Returns:

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

rightPad

public static 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 null

size - the size to pad to

padChar - the character to pad with

Returns:

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

Since:

2.0

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 null

size - the size to pad to

padStr - the String to pad with, null or empty treated as single space

Returns:

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

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 null

size - the size to pad to

Returns:

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

leftPad

public static 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 null

size - the size to pad to

padChar - the character to pad with

Returns:

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

Since:

2.0

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 null

size - the size to pad to

padStr - the String to pad with, null or empty treated as single space

Returns:

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

length

public static int length(java.lang.CharSequence cs)

Gets a CharSequence length or 0 if the CharSequence is null.

Parameters:

cs - a CharSequence or null

Returns:

CharSequence length or 0 if the CharSequence is null.

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 returns null. A negative size is treated as zero.

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

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

Parameters:

str - the String to center, may be null

size - the int size of new String, negative treated as zero

Returns:

centered String, null if null String input

center

public static 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 returns null. A negative size is treated as zero.

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

Parameters:

str - the String to center, may be null

size - the int size of new String, negative treated as zero

padChar - the character to pad the new String with

Returns:

centered String, null if null String input

Since:

2.0

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 returns null. A negative size is treated as zero.

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

Parameters:

str - the String to center, may be null

size - the int size of new String, negative treated as zero

padStr - the String to pad the new String with, must not be null or empty

Returns:

centered String, null if null String input

Throws:

java.lang.IllegalArgumentException - if padStr is null 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 returns null.

 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 method lowerCase(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 returns null.

 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 null

locale - 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 returns null.

 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 method lowerCase(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 returns null.

 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 null

locale - 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). A null input String returns null.

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

Parameters:

str - the String to capitalize, may be null

Returns:

the capitalized String, null if null String input

Since:

2.0

See Also:

WordUtils.capitalize(String), uncapitalize(String)

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). A null input String returns null.

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

Parameters:

str - the String to uncapitalize, may be null

Returns:

the uncapitalized String, null if null String input

Since:

2.0

See Also:

WordUtils.uncapitalize(String), capitalize(String)

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). A null input String returns null.

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

NOTE: This method changed in Lang version 2.0. It no longer performs a word based algorithm. If you only use ASCII, you will notice no change. That functionality is available in 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 returns 0.

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

Parameters:

str - the CharSequence to check, may be null

sub - 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 returns 0.

 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 null

ch - 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 return false. An empty CharSequence (length()=0) will return false.

 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 return false An empty CharSequence (length()=0) will return true.

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

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 return false. An empty CharSequence (length()=0) will return false.

 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 return false. An empty CharSequence (length()=0) will return true.

 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 return false. An empty CharSequence (length()=0) will return true.

 StringUtils.isAsciiPrintable(null)     = false
 StringUtils.isAsciiPrintable("")       = true
 StringUtils.isAsciiPrintable(" ")      = true
 StringUtils.isAsciiPrintable("Ceki")   = true
 StringUtils.isAsciiPrintable("ab2c")   = true
 StringUtils.isAsciiPrintable("!ab-c~") = true
 StringUtils.isAsciiPrintable(" ") = 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 return false. An empty CharSequence (length()=0) will return false.

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 return false. An empty CharSequence (length()=0) will return true.

 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 return false. An empty CharSequence (length()=0) will return true.

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

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 return false. An empty CharSequence (length()=0) will return false.

 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 return false. An empty String (length()=0) will return false.

 StringUtils.isAllUpperCase(null)   = false
 StringUtils.isAllUpperCase("")     = false
 StringUtils.isAllUpperCase("  ")   = false
 StringUtils.isAllUpperCase("ABC")  = true
 StringUtils.isAllUpperCase("aBC")  = false
 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 of defaultStr.

 StringUtils.defaultString(null, "NULL")  = "NULL"
 StringUtils.defaultString("", "NULL")    = ""
 StringUtils.defaultString("bat", "NULL") = "bat"
 

Parameters:

str - the String to check, may be null

defaultStr - the default String to return if the input is null, may be null

Returns:

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

See Also:

ObjectUtils.toString(Object,String), String.valueOf(Object)

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 of defaultStr.

 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 null

defaultStr - the default CharSequence to return if the input is whitespace, empty ("") or null, 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 of defaultStr.

 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 null

defaultStr - the default CharSequence to return if the input is empty ("") or null, 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 returns null.

 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 null

separatorChar - 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 to maxWidth, return str.
• Else abbreviate it to (substring(str, 0, max-3) + "...").
• If maxWidth is less than 4, throw an IllegalArgumentException.
• In no case will it return a String of length greater than maxWidth.

 StringUtils.abbreviate(null, *)      = null
 StringUtils.abbreviate("", 4)        = ""
 StringUtils.abbreviate("abcdefg", 6) = "abc..."
 StringUtils.abbreviate("abcdefg", 7) = "abcdefg"
 StringUtils.abbreviate("abcdefg", 8) = "abcdefg"
 StringUtils.abbreviate("abcdefg", 4) = "a..."
 StringUtils.abbreviate("abcdefg", 3) = IllegalArgumentException
 

Parameters:

str - the String to check, may be null

maxWidth - maximum length of result String, must be at least 4

Returns:

abbreviated String, null if null String input

Throws:

java.lang.IllegalArgumentException - if the width is too small

Since:

2.0

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 null

offset - left edge of source String

maxWidth - maximum length of result String, must be at least 4

Returns:

abbreviated String, null if null String input

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 null

middle - the String to replace the middle characters with, may be null

length - the length to abbreviate str 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 null

str2 - the second String, may be null

Returns:

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

Since:

2.0

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 null

cs2 - 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.htm

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

Parameters:

s - the first String, must not be null

t - the second String, must not be null

Returns:

result distance

Throws:

java.lang.IllegalArgumentException - if either String input null

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 null

t - the second String, must not be null

threshold - 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 input null 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 null

second - the second String, must not be null

Returns:

result distance

Throws:

java.lang.IllegalArgumentException - if either String input null

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 null

query - the query that will be matched against a term, must not be null

locale - 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 input null or Locale input null

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.

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

 StringUtils.startsWith(null, null)      = true
 StringUtils.startsWith(null, "abc")     = false
 StringUtils.startsWith("abcdef", null)  = false
 StringUtils.startsWith("abcdef", "abc") = true
 StringUtils.startsWith("ABCDEF", "abc") = false
 

Parameters:

str - the CharSequence to check, may be null

prefix - the prefix to find, may be null

Returns:

true if the CharSequence starts with the prefix, case sensitive, or both null

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.

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

 StringUtils.startsWithIgnoreCase(null, null)      = true
 StringUtils.startsWithIgnoreCase(null, "abc")     = false
 StringUtils.startsWithIgnoreCase("abcdef", null)  = false
 StringUtils.startsWithIgnoreCase("abcdef", "abc") = true
 StringUtils.startsWithIgnoreCase("ABCDEF", "abc") = true
 

Parameters:

str - the CharSequence to check, may be null

prefix - the prefix to find, may be null

Returns:

true if the CharSequence starts with the prefix, case insensitive, or both null

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 null

searchStrings - the CharSequences to find, may be null or empty

Returns:

true if the CharSequence starts with any of the the prefixes, case insensitive, or both null

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.

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

 StringUtils.endsWith(null, null)      = true
 StringUtils.endsWith(null, "def")     = false
 StringUtils.endsWith("abcdef", null)  = false
 StringUtils.endsWith("abcdef", "def") = true
 StringUtils.endsWith("ABCDEF", "def") = false
 StringUtils.endsWith("ABCDEF", "cde") = false
 

Parameters:

str - the CharSequence to check, may be null

suffix - the suffix to find, may be null

Returns:

true if the CharSequence ends with the suffix, case sensitive, or both null

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.

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

 StringUtils.endsWithIgnoreCase(null, null)      = true
 StringUtils.endsWithIgnoreCase(null, "def")     = false
 StringUtils.endsWithIgnoreCase("abcdef", null)  = false
 StringUtils.endsWithIgnoreCase("abcdef", "def") = true
 StringUtils.endsWithIgnoreCase("ABCDEF", "def") = true
 StringUtils.endsWithIgnoreCase("ABCDEF", "cde") = false
 

Parameters:

str - the CharSequence to check, may be null

suffix - the suffix to find, may be null

Returns:

true if the CharSequence ends with the suffix, case insensitive, or both null

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 trim(String) to remove leading and trailing whitespace and then replacing sequences of whitespace characters by a single space.

In XML Whitespace characters are the same as those allowed by the S production, which is S ::= (#x20 | #x9 | #xD | #xA)+

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 trim(String) removes control characters (char <= 32) from both ends of this 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 null

searchStrings - the CharSequences to find, may be null or empty

Returns:

true if the CharSequence ends with any of the the prefixes, case insensitive, or both null

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. use toEncodedString(byte[], Charset) instead of String constants in your code

Converts a byte[] to a String using the specified character encoding.

Parameters:

bytes - the byte array to read from

charsetName - 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 supported

java.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 a byte[] to a String using the specified character encoding.

Parameters:

bytes - the byte array to read from

charset - the encoding to use, if null then use the platform default

Returns:

a new String

Throws:

java.lang.NullPointerException - if bytes 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 be null

wrapWith - the char that will wrap str

Returns:

the wrapped string, or null if str==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 returns null.

 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 null

wrapWith - the String that will wrap str

Returns:

wrapped String, null if null String input

Since:

3.4