Class StringUtils
- java.lang.Object
-
- software.amazon.awssdk.utils.StringUtils
-
public final class StringUtils extends Object
Operations on
String
that arenull
safe.- IsEmpty/IsBlank - checks if a String contains text
- Trim/Strip - removes leading and trailing whitespace
- Equals/Compare - 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
- Rotate - rotate (circular shift) a String
- Reverse/ReverseDelimited - reverses a String
- Abbreviate - abbreviates a string using ellipsis or another given String
- Difference - compares Strings and reports on their differences
- LevenshteinDistance - the number of changes needed to change one String into another
The
StringUtils
class defines certain words related to String handling.- null -
null
- empty - a zero-length string (
""
) - space - the space character (
' '
, char 32) - whitespace - the characters defined by
Character.isWhitespace(char)
- trim - the characters <= 32 as in
String.trim()
StringUtils
handlesnull
input Strings quietly. That is to say that anull
input will returnnull
. Where aboolean
orint
is being returned details vary by method.A side effect of the
null
handling is that aNullPointerException
should be considered a bug inStringUtils
.This class's source was modified from the Apache commons-lang library: https://github.com/apache/commons-lang/
#ThreadSafe#
- See Also:
String
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static String
capitalize(String str)
Capitalizes a String changing the first character to title case as perCharacter.toTitleCase(int)
.static boolean
equals(String cs1, String cs2)
Compares two Strings, returningtrue
if they represent equal sequences of characters.static Character
findFirstOccurrence(String s, char... charsToMatch)
Searches a string for the first occurrence of a character specified by a list of characters.static String
fromBytes(byte[] bytes, Charset charset)
Encode the given bytes as a string using the given charsetstatic boolean
isBlank(CharSequence cs)
Checks if a CharSequence is empty (""), null or whitespace only.static boolean
isEmpty(CharSequence cs)
Checks if a CharSequence is empty ("") or null.static boolean
isNotBlank(CharSequence cs)
Checks if a CharSequence is not empty (""), not null and not whitespace only.static String
lowerCase(String str)
Converts a String to lower case as perString.toLowerCase()
.static String
repeat(String value, int count)
Returns a string whose value is the concatenation of this string repeatedcount
times.static String
replace(String text, String searchString, String replacement)
Replaces a String with another String inside a larger String, for the firstmax
values of the search String, case sensitively/insensitively based onignoreCase
value.static String
replaceEach(String text, String[] searchList, String[] replacementList)
Replaces all occurrences of Strings within another String.static String
replaceOnce(String text, String searchString, String replacement)
Replaces a String with another String inside a larger String, once.static String
replacePrefixIgnoreCase(String str, String prefix, String replacement)
Replace the prefix of the string provided ignoring case considerations.static boolean
safeStringToBoolean(String value)
Convert a string to boolean safely (as opposed to the less strictBoolean.parseBoolean(String)
).static boolean
startsWithIgnoreCase(String str, String prefix)
Tests if this string starts with the specified prefix ignoring case considerations.static String
substring(String str, int start)
Gets a substring from the specified String avoiding exceptions.static String
substring(String str, int start, int end)
Gets a substring from the specified String avoiding exceptions.static String
trim(String str)
Removes control characters (char <= 32) from both ends of this String, handlingnull
by returningnull
.static String
trimToEmpty(String str)
Removes control characters (char <= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if it isnull
.static String
trimToNull(String str)
Removes control characters (char <= 32) from both ends of this String returningnull
if the String is empty ("") after the trim or if it isnull
.static String
uncapitalize(String str)
Uncapitalizes a String, changing the first character to lower case as perCharacter.toLowerCase(int)
.static String
upperCase(String str)
Converts a String to upper case as perString.toUpperCase()
.
-
-
-
Method Detail
-
isEmpty
public static boolean isEmpty(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)
-
isBlank
public static boolean isBlank(CharSequence cs)
Checks if a CharSequence is empty (""), null or whitespace only.
Whitespace is defined by
Character.isWhitespace(char)
.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 only- Since:
- 2.0, 3.0 Changed signature from isBlank(String) to isBlank(CharSequence)
-
isNotBlank
public static boolean isNotBlank(CharSequence cs)
Checks if a CharSequence is not empty (""), not null and not whitespace only.
Whitespace is defined by
Character.isWhitespace(char)
.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 only- Since:
- 2.0, 3.0 Changed signature from isNotBlank(String) to isNotBlank(CharSequence)
-
trim
public static String trim(String str)
Removes control characters (char <= 32) from both ends of this String, handling
null
by returningnull
.The String is trimmed using
String.trim()
. Trim removes start and end characters <= 32.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 String trimToNull(String str)
Removes control characters (char <= 32) from both ends of this String returning
null
if the String is empty ("") after the trim or if it isnull
.The String is trimmed using
String.trim()
. Trim removes start and end characters <= 32.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 String trimToEmpty(String str)
Removes control characters (char <= 32) from both ends of this String returning an empty String ("") if the String is empty ("") after the trim or if it is
null
.The String is trimmed using
String.trim()
. Trim removes start and end characters <= 32.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
-
equals
public static boolean equals(String cs1, String cs2)
Compares two Strings, returning
true
if they represent equal sequences of characters.null
s are handled without exceptions. Twonull
references are considered to be equal. The comparison is case sensitive.StringUtils.equals(null, null) = true StringUtils.equals(null, "abc") = false StringUtils.equals("abc", null) = false StringUtils.equals("abc", "abc") = true StringUtils.equals("abc", "ABC") = false
- Parameters:
cs1
- the first String, may benull
cs2
- the second String, may benull
- Returns:
true
if the Strings are equal (case-sensitive), or bothnull
- See Also:
Object.equals(Object)
-
substring
public static String substring(String str, int start)
Gets a substring from the specified String avoiding exceptions.
A negative start position can be used to start
n
characters from the end of the String.A
null
String will returnnull
. An empty ("") String will return "".StringUtils.substring(null, *) = null StringUtils.substring("", *) = "" StringUtils.substring("abc", 0) = "abc" StringUtils.substring("abc", 2) = "c" StringUtils.substring("abc", 4) = "" StringUtils.substring("abc", -2) = "bc" StringUtils.substring("abc", -4) = "abc"
- Parameters:
str
- the String to get the substring from, may be nullstart
- the position to start from, negative means count back from the end of the String by this many characters- Returns:
- substring from start position,
null
if null String input
-
substring
public static String substring(String str, int start, int end)
Gets a substring from the specified String avoiding exceptions.
A negative start position can be used to start/end
n
characters from the end of the String.The returned substring starts with the character in the
start
position and ends before theend
position. All position counting is zero-based -- i.e., to start at the beginning of the string usestart = 0
. Negative start and end positions can be used to specify offsets relative to the end of the String.If
start
is not strictly to the left ofend
, "" is returned.StringUtils.substring(null, *, *) = null StringUtils.substring("", * , *) = ""; StringUtils.substring("abc", 0, 2) = "ab" StringUtils.substring("abc", 2, 0) = "" StringUtils.substring("abc", 2, 4) = "c" StringUtils.substring("abc", 4, 6) = "" StringUtils.substring("abc", 2, 2) = "" StringUtils.substring("abc", -2, -1) = "b" StringUtils.substring("abc", -4, 2) = "ab"
- Parameters:
str
- the String to get the substring from, may be nullstart
- the position to start from, negative means count back from the end of the String by this many charactersend
- the position to end at (exclusive), negative means count back from the end of the String by this many characters- Returns:
- substring from start position to end position,
null
if null String input
-
upperCase
public static String upperCase(String str)
Converts a String to upper case as per
String.toUpperCase()
.A
null
input String returnsnull
.StringUtils.upperCase(null) = null StringUtils.upperCase("") = "" StringUtils.upperCase("aBc") = "ABC"
This uses "ENGLISH" as the locale.
- Parameters:
str
- the String to upper case, may be null- Returns:
- the upper cased String,
null
if null String input
-
lowerCase
public static String lowerCase(String str)
Converts a String to lower case as per
String.toLowerCase()
.A
null
input String returnsnull
.StringUtils.lowerCase(null) = null StringUtils.lowerCase("") = "" StringUtils.lowerCase("aBc") = "abc"
This uses "ENGLISH" as the locale.
- Parameters:
str
- the String to lower case, may be null- Returns:
- the lower cased String,
null
if null String input
-
capitalize
public static String capitalize(String str)
Capitalizes a String changing the first character to title case as per
Character.toTitleCase(int)
. No other characters are changed.StringUtils.capitalize(null) = null StringUtils.capitalize("") = "" StringUtils.capitalize("cat") = "Cat" 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:
uncapitalize(String)
-
uncapitalize
public static String uncapitalize(String str)
Uncapitalizes a String, changing the first character to lower case as per
Character.toLowerCase(int)
. No other characters are changed.StringUtils.uncapitalize(null) = null StringUtils.uncapitalize("") = "" StringUtils.uncapitalize("cat") = "cat" 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:
capitalize(String)
-
fromBytes
public static String fromBytes(byte[] bytes, Charset charset) throws UncheckedIOException
Encode the given bytes as a string using the given charset- Throws:
UncheckedIOException
- with aCharacterCodingException
as the cause if the bytes cannot be encoded using the provided charset.
-
startsWithIgnoreCase
public static boolean startsWithIgnoreCase(String str, String prefix)
Tests if this string starts with the specified prefix ignoring case considerations.- Parameters:
str
- the string to be testedprefix
- the prefix- Returns:
- true if the string starts with the prefix ignoring case
-
replaceOnce
public static String replaceOnce(String text, String searchString, String replacement)
Replaces a String with another String inside a larger String, once.
A
null
reference passed to this method is a no-op.StringUtils.replaceOnce(null, *, *) = null StringUtils.replaceOnce("", *, *) = "" StringUtils.replaceOnce("any", null, *) = "any" StringUtils.replaceOnce("any", *, null) = "any" StringUtils.replaceOnce("any", "", *) = "any" StringUtils.replaceOnce("aba", "a", null) = "aba" StringUtils.replaceOnce("aba", "a", "") = "ba" StringUtils.replaceOnce("aba", "a", "z") = "zba"
- Parameters:
text
- text to search and replace in, may be nullsearchString
- the String to search for, may be nullreplacement
- the String to replace with, may be null- Returns:
- the text with any replacements processed,
null
if null String input - See Also:
replace(String text, String searchString, String replacement, int max)
-
replace
public static String replace(String text, String searchString, String replacement)
Replaces a String with another String inside a larger String, for the first
max
values of the search String, case sensitively/insensitively based onignoreCase
value.A
null
reference passed to this method is a no-op.StringUtils.replace(null, *, *, *, false) = null StringUtils.replace("", *, *, *, false) = "" StringUtils.replace("any", null, *, *, false) = "any" StringUtils.replace("any", *, null, *, false) = "any" StringUtils.replace("any", "", *, *, false) = "any" StringUtils.replace("any", *, *, 0, false) = "any" StringUtils.replace("abaa", "a", null, -1, false) = "abaa" StringUtils.replace("abaa", "a", "", -1, false) = "b" StringUtils.replace("abaa", "a", "z", 0, false) = "abaa" StringUtils.replace("abaa", "A", "z", 1, false) = "abaa" StringUtils.replace("abaa", "A", "z", 1, true) = "zbaa" StringUtils.replace("abAa", "a", "z", 2, true) = "zbza" StringUtils.replace("abAa", "a", "z", -1, true) = "zbzz"
- Parameters:
text
- text to search and replace in, may be nullsearchString
- the String to search for (case insensitive), may be nullreplacement
- the String to replace it with, may be null- Returns:
- the text with any replacements processed,
null
if null String input
-
replaceEach
public static String replaceEach(String text, String[] searchList, String[] replacementList)
Replaces all occurrences of Strings within another String.
A
null
reference passed to this method is a no-op, or if any "search string" or "string to replace" is null, that replace will be ignored. This will not repeat. For repeating replaces, call the overloaded method.StringUtils.replaceEach(null, *, *) = null StringUtils.replaceEach("", *, *) = "" StringUtils.replaceEach("aba", null, null) = "aba" StringUtils.replaceEach("aba", new String[0], null) = "aba" StringUtils.replaceEach("aba", null, new String[0]) = "aba" StringUtils.replaceEach("aba", new String[]{"a"}, null) = "aba" StringUtils.replaceEach("aba", new String[]{"a"}, new String[]{""}) = "b" StringUtils.replaceEach("aba", new String[]{null}, new String[]{"a"}) = "aba" StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"w", "t"}) = "wcte" (example of how it does not repeat) StringUtils.replaceEach("abcde", new String[]{"ab", "d"}, new String[]{"d", "t"}) = "dcte"
- Parameters:
text
- text to search and replace in, no-op if nullsearchList
- the Strings to search for, no-op if nullreplacementList
- the Strings to replace them with, no-op if null- Returns:
- the text with any replacements processed,
null
if null String input - Throws:
IllegalArgumentException
- if the lengths of the arrays are not the same (null is ok, and/or size 0)- Since:
- 2.4
-
replacePrefixIgnoreCase
public static String replacePrefixIgnoreCase(String str, String prefix, String replacement)
Replace the prefix of the string provided ignoring case considerations.The unmatched part is unchanged.
- Parameters:
str
- the string to replaceprefix
- the prefix to findreplacement
- the replacement- Returns:
- the replaced string
-
findFirstOccurrence
public static Character findFirstOccurrence(String s, char... charsToMatch)
Searches a string for the first occurrence of a character specified by a list of characters.- Parameters:
s
- The string to search.charsToMatch
- A list of characters to search the string for.- Returns:
- The character that was first matched in the string or null if none of the characters were found.
-
safeStringToBoolean
public static boolean safeStringToBoolean(String value)
Convert a string to boolean safely (as opposed to the less strictBoolean.parseBoolean(String)
). If a customer specifies a boolean value it should be "true" or "false" (case insensitive) or an exception will be thrown.
-
repeat
public static String repeat(String value, int count)
Returns a string whose value is the concatenation of this string repeatedcount
times.If this string is empty or count is zero then the empty string is returned.
Logical clone of JDK11's
String#repeat(int)
.- Parameters:
value
- the string to repeatcount
- number of times to repeat- Returns:
- A string composed of this string repeated
count
times or the empty string if this string is empty or count is zero - Throws:
IllegalArgumentException
- if thecount
is negative.
-
-