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