StringUtils (AWS Java SDK :: Utilities 2.20.35 API)

java.lang.Object
- software.amazon.awssdk.utils.StringUtils

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

All Methods Static Methods Concrete Methods
Modifier and Type	Method and 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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

Class StringUtils

Method Summary

Methods inherited from class java.lang.Object

Method Detail

isEmpty

isBlank

isNotBlank

trim

trimToNull

trimToEmpty

equals

substring

substring

upperCase

lowerCase

capitalize

uncapitalize

fromBytes

startsWithIgnoreCase

replaceOnce

replace

replaceEach

replacePrefixIgnoreCase

findFirstOccurrence

safeStringToBoolean

repeat