Class StringUtils

java.lang.Object

software.amazon.awssdk.utils.StringUtils

@SdkProtectedApi
public final class StringUtils
extends Object

Operations on String that are null 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 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.

This class's source was modified from the Apache commons-lang library: https://github.com/apache/commons-lang/

#ThreadSafe#

See Also:

• String

Method Summary

Modifier and Type	Method	Description
static String	capitalize(String str)	Capitalizes a String changing the first character to title case as per Character.toTitleCase(int).
static boolean	equals(String cs1, String cs2)	Compares two Strings, returning true 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 charset
static 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 per String.toLowerCase().
static String	repeat(String value, int count)	Returns a string whose value is the concatenation of this string repeated count times.
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 on ignoreCase 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 strict Boolean.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, handling null by returning null.
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.
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 is null.
static String	uncapitalize(String str)	Uncapitalizes a String, changing the first character to lower case as per Character.toLowerCase(int).
static String	upperCase(String str)	Converts a String to upper case as per String.toUpperCase().

Methods inherited from class java.lang.Object

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

Method Details

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

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

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.

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 String, may be null

cs2 - the second String, may be null

Returns:

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

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

upperCase

public static String upperCase(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"
 

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

 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 a CharacterCodingException 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 tested

prefix - 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 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)

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 on ignoreCase 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 null

searchString - the String to search for (case insensitive), 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

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 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:

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 replace

prefix - the prefix to find

replacement - 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 strict Boolean.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 repeated count times.

If this string is empty or count is zero then the empty string is returned.

Logical clone of JDK11's

invalid reference

String#repeat(int)

.

Parameters:

value - the string to repeat

count - 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 the count is negative.