Package io.microsphere.util

Class StringUtils

  • All Implemented Interfaces:
    Utils
    public abstract class StringUtils
extends java.lang.Object
implements Utils
    The utilities class for String
    Since:
    1.0.0
    Author:
    Mercy

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String EMPTY
      Represents an empty string constant : ""
      static java.lang.String EMPTY_STRING
      Represents an empty string constant: ""
      static java.lang.String[] EMPTY_STRING_ARRAY
      An empty array of String.
      static int INDEX_NOT_FOUND
      Represents a failed index search.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String capitalize​(java.lang.String str)
      Capitalizes the first character of the given String, converting it to uppercase using Character.toUpperCase(char).
      static boolean contains​(java.lang.String value, java.lang.CharSequence part)
      Checks if a CharSequence contains another CharSequence.
      static boolean containsWhitespace​(java.lang.String str)
      Checks whether the given String contains any whitespace characters.
      static boolean endsWith​(java.lang.String value, java.lang.String part)
      Checks if a String ends with another String.
      static boolean isBlank​(java.lang.String value)
      Checks if a String is whitespace, empty, or null.
      static boolean isNotBlank​(java.lang.String value)
      Checks if a String is not blank.
      static boolean isNumeric​(java.lang.String str)
      Checks if the String contains only unicode digits.
      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[] split​(java.lang.String value, char delimiter)
      Splits the provided String into an array of Strings using the specified char delimiter.
      static java.lang.String[] split​(java.lang.String value, java.lang.String delimiter)
      Splits the provided String into an array of Strings using the specified String delimiter.
      static boolean startsWith​(java.lang.String value, java.lang.String part)
      Checks if a String starts with another String.
      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 trimAllWhitespace​(java.lang.String str)
      Trims all whitespace characters from the given String.
      static java.lang.String trimLeadingWhitespace​(java.lang.String str)
      Trims leading whitespace from the given String.
      static java.lang.String trimTrailingWhitespace​(java.lang.String str)
      Trims trailing whitespace from the given String.
      static java.lang.String trimWhitespace​(java.lang.String str)
      Trims leading and trailing whitespace from the given String.
      static java.lang.String uncapitalize​(java.lang.String str)
      Uncapitalizes the first character of the given String, converting it to lowercase using Character.toLowerCase(char).

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • EMPTY

        public static final java.lang.String EMPTY
        Represents an empty string constant : ""
        See Also:
        Constant Field Values

      • EMPTY_STRING

        public static final java.lang.String EMPTY_STRING
        Represents an empty string constant: ""
        See Also:
        Constant Field Values

      • EMPTY_STRING_ARRAY

        @Immutable
public static final java.lang.String[] EMPTY_STRING_ARRAY
        An empty array of String.

      • INDEX_NOT_FOUND

        public static final int INDEX_NOT_FOUND
        Represents a failed index search.
        See Also:
        Constant Field Values

    • Method Detail

      • isBlank

        public static boolean isBlank​(java.lang.String value)

        Checks if a String is whitespace, empty, or null.

        Whitespace is defined by the Character.isWhitespace(char) method.

        Example Usage

        
 StringUtils.isBlank(null)      = true
 StringUtils.isBlank("")        = true
 StringUtils.isBlank(" ")       = true
 StringUtils.isBlank("  a  ")   = false
 StringUtils.isBlank("abc")    = false
 StringUtils.isBlank("\t\n\f")  = true
        Parameters:
        value - the String to check, may be null
        Returns:
        true if the String is null, empty, or contains only whitespace characters

      • isNotBlank

        public static boolean isNotBlank​(java.lang.String value)

        Checks if a String is not blank.

        A string is considered not blank if it contains at least one non-whitespace character. This method is the inverse of isBlank(String).

        Example Usage

        
 StringUtils.isNotBlank(null)      = false
 StringUtils.isNotBlank("")        = false
 StringUtils.isNotBlank(" ")       = false
 StringUtils.isNotBlank("  a  ")   = true
 StringUtils.isNotBlank("abc")     = true
 StringUtils.isNotBlank("\t\n\f")  = false
        Parameters:
        value - the String to check, may be null
        Returns:
        true if the String is not null, not empty, and contains at least one non-whitespace character

      • split

        public static java.lang.String[] split​(java.lang.String value,
                                       char delimiter)

        Splits the provided String into an array of Strings using the specified char delimiter.

        A null or empty input String returns an empty array. If the delimiter is not found, an array containing just the input String is returned.

        Example Usage

        
 StringUtils.split(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"]
        Parameters:
        value - the String to split, may be null or empty
        delimiter - the char used as a delimiter to split the String
        Returns:
        an array of Strings, split by the delimiter; never null

      • split

        public static java.lang.String[] split​(java.lang.String value,
                                       java.lang.String delimiter)

        Splits the provided String into an array of Strings using the specified String delimiter.

        A null or empty input String returns an empty array. If the delimiter is not found, an array containing just the input String is returned.

        Example Usage

        
 StringUtils.split(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"]
        Parameters:
        value - the String to split, may be null or empty
        delimiter - the String used as a delimiter to split the String, may be null or empty
        Returns:
        an array of Strings, split by the delimiter; never null

      • contains

        public static boolean contains​(java.lang.String value,
                               java.lang.CharSequence part)

        Checks if a CharSequence contains another CharSequence.

        This method is case-sensitive and uses the String.contains(CharSequence) method. A null CharSequence returns false.

        Example Usage

        
 StringUtils.contains(null, null)     = false
 StringUtils.contains(null, "abc")    = false
 StringUtils.contains("abc", null)    = false
 StringUtils.contains("", "")         = true
 StringUtils.contains("abc", "")      = true
 StringUtils.contains("abc", "a")     = true
 StringUtils.contains("abc", "z")     = false
 StringUtils.contains("abc", "abc")   = true
        Parameters:
        value - the CharSequence to check, may be null
        part - the CharSequence to search for, may be null
        Returns:
        true if the value contains the part as a subsequence, case-sensitive

      • startsWith

        public static boolean startsWith​(java.lang.String value,
                                 java.lang.String part)

        Checks if a String starts with another String.

        This method is case-sensitive and uses the String.startsWith(String) method. A null reference for either parameter returns false.

        Example Usage

        
 StringUtils.startsWith(null, null)     = false
 StringUtils.startsWith(null, "abc")    = false
 StringUtils.startsWith("abc", null)    = false
 StringUtils.startsWith("", "")         = true
 StringUtils.startsWith("abc", "")      = true
 StringUtils.startsWith("abc", "a")     = true
 StringUtils.startsWith("abc", "ab")    = true
 StringUtils.startsWith("abc", "z")     = false
 StringUtils.startsWith("abc", "abcd")  = false
        Parameters:
        value - the String to check, may be null
        part - the String prefix to search for, may be null
        Returns:
        true if the value starts with the provided part, case-sensitive

      • endsWith

        public static boolean endsWith​(java.lang.String value,
                               java.lang.String part)

        Checks if a String ends with another String.

        This method is case-sensitive and uses the String.endsWith(String) method. A null reference for either parameter returns false.

        Example Usage

        
 StringUtils.endsWith(null, null)     = false
 StringUtils.endsWith(null, "abc")    = false
 StringUtils.endsWith("abc", null)    = false
 StringUtils.endsWith("", "")         = true
 StringUtils.endsWith("abc", "")      = true
 StringUtils.endsWith("abc", "c")     = true
 StringUtils.endsWith("abc", "bc")    = true
 StringUtils.endsWith("abc", "abc")   = true
 StringUtils.endsWith("abc", "d")     = false
 StringUtils.endsWith("abc", "abcd")  = false
        Parameters:
        value - the String to check, may be null
        part - the String suffix to search for, may be null
        Returns:
        true if the value ends with the provided part, case-sensitive

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

        Example Usage

        
 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.

        Example Usage

        
 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

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

        Example Usage

        
 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

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

        Example Usage

        
 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

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

        Example Usage

        
 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

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

        Example Usage

        
 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

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

        Example Usage

        
 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

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

        Example Usage

        
 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

      • isNumeric

        public static boolean isNumeric​(java.lang.String str)

        Checks if the String contains only unicode digits. A decimal point is not a unicode digit and returns false.

        null will return false. An empty String (length()=0) will return true.

        Example Usage

        
 StringUtils.isNumeric(null)   = false
 StringUtils.isNumeric("")     = true
 StringUtils.isNumeric("  ")   = false
 StringUtils.isNumeric("123")  = true
 StringUtils.isNumeric("12 3") = false
 StringUtils.isNumeric("ab2c") = false
 StringUtils.isNumeric("12-3") = false
 StringUtils.isNumeric("12.3") = false
        Parameters:
        str - the String to check, may be null
        Returns:
        true if only contains digits, and is non-null

      • containsWhitespace

        public static boolean containsWhitespace​(@Nullable
                                         java.lang.String str)
        Checks whether the given String contains any whitespace characters.

        A whitespace character is defined as any character that returns true when passed to Character.isWhitespace(char).

        Example Usage

        • containsWhitespace(null) returns false
        • containsWhitespace("") returns false
        • containsWhitespace("hello world") returns true
        • containsWhitespace("hello\tworld") returns true
        • containsWhitespace("helloworld") returns false
        Parameters:
        str - the String to check (may be null)
        Returns:
        true if the provided sequence is not empty and contains at least one whitespace character; otherwise, false

      • trimWhitespace

        public static java.lang.String trimWhitespace​(java.lang.String str)
        Trims leading and trailing whitespace from the given String.

        This method removes whitespace characters (as defined by Character.isWhitespace(char)) from the beginning and end of the input string. If the input is null or empty, it will be returned as-is.

        Example Usage

        • trimWhitespace(null) returns null
        • trimWhitespace("") returns ""
        • trimWhitespace(" abc ") returns "abc"
        • trimWhitespace("abc") returns "abc"
        • trimWhitespace(" abc def ") returns "abc def"
        Parameters:
        str - the String to trim (may be null)
        Returns:
        a new String with leading and trailing whitespace removed, or the original if it is null or empty

      • trimLeadingWhitespace

        public static java.lang.String trimLeadingWhitespace​(java.lang.String str)
        Trims leading whitespace from the given String.

        This method removes whitespace characters (as defined by Character.isWhitespace(char)) from the beginning of the input string. If the input is null or empty, it will be returned as-is.

        Example Usage

        • trimLeadingWhitespace(null) returns null
        • trimLeadingWhitespace("") returns ""
        • trimLeadingWhitespace(" abc ") returns "abc "
        • trimLeadingWhitespace("abc") returns "abc"
        • trimLeadingWhitespace(" abc def ") returns "abc def "
        Parameters:
        str - the String to trim (may be null)
        Returns:
        a new String with leading whitespace removed, or the original if it is null or empty
        See Also:
        Character.isWhitespace(char)

      • trimTrailingWhitespace

        public static java.lang.String trimTrailingWhitespace​(java.lang.String str)
        Trims trailing whitespace from the given String.

        This method removes whitespace characters (as defined by Character.isWhitespace(char)) from the end of the input string. If the input is null or empty, it will be returned as-is.

        Example Usage

        • trimTrailingWhitespace(null) returns null
        • trimTrailingWhitespace("") returns ""
        • trimTrailingWhitespace(" abc ") returns " abc"
        • trimTrailingWhitespace("abc") returns "abc"
        • trimTrailingWhitespace("abc def ") returns "abc def"
        Parameters:
        str - the String to trim (may be null)
        Returns:
        a new String with trailing whitespace removed, or the original if it is null or empty
        See Also:
        Character.isWhitespace(char)

      • trimAllWhitespace

        public static java.lang.String trimAllWhitespace​(java.lang.String str)
        Trims all whitespace characters from the given String.

        This method removes all whitespace characters (as defined by Character.isWhitespace(char)) from the beginning, end, and middle of the input sequence. If the input is null or empty, it will be returned as-is.

        Example Usage

        • trimAllWhitespace(null) returns null
        • trimAllWhitespace("") returns ""
        • trimAllWhitespace(" hello world ") returns "helloworld"
        • trimAllWhitespace(" \t\n h e l l o \r\n\f") returns "hello"
        Parameters:
        str - the String to trim (may be null)
        Returns:
        a new String with all whitespace characters removed, or the original if none exist

      • capitalize

        public static java.lang.String capitalize​(java.lang.String str)
        Capitalizes the first character of the given String, converting it to uppercase using Character.toUpperCase(char). The rest of the characters remain unchanged.

        A null or empty input will be returned as-is.

        Example Usage

        • capitalize(null) returns null
        • capitalize("") returns ""
        • capitalize("hello") returns "Hello"
        • capitalize("HELLO") returns "HELLO"
        • capitalize("hELLO") returns "HELLO"
        Parameters:
        str - the String to capitalize (may be null)
        Returns:
        a new String with the first character capitalized, or the original if it is null or empty

      • uncapitalize

        public static java.lang.String uncapitalize​(java.lang.String str)
        Uncapitalizes the first character of the given String, converting it to lowercase using Character.toLowerCase(char). The rest of the characters remain unchanged.

        A null or empty input will be returned as-is.

        Example Usage

        • uncapitalize(null) returns null
        • uncapitalize("") returns ""
        • uncapitalize("Hello") returns "hello"
        • uncapitalize("HELLO") returns "hELLO"
        • uncapitalize("hELLO") returns "hELLO"
        Parameters:
        str - the String to uncapitalize (may be null)
        Returns:
        a new String with the first character uncapitalized, or the original if it is null or empty