Class Strings

java.lang.Object
org.apache.commons.lang3.Strings

public abstract class Strings extends Object
String operations where you choose case-sensitive CS vs. case-insensitive CI through a singleton instance.
Since:
3.18.0
See Also:
  • Field Details

    • CI

      public static final Strings CI
      The Case-Insensitive singleton instance.
    • CS

      public static final Strings CS
      The Case-Snsensitive singleton instance.
  • Method Details

    • builder

      public static final Strings.Builder builder()
      Constructs a new Strings.Builder instance.
      Returns:
      a new Strings.Builder instance.
    • appendIfMissing

      public String appendIfMissing(String str, CharSequence suffix, CharSequence... suffixes)
      Appends the suffix to the end of the string if the string does not already end with the suffix.

      Case-sensitive examples

       Strings.CS.appendIfMissing(null, null)      = null
       Strings.CS.appendIfMissing("abc", null)     = "abc"
       Strings.CS.appendIfMissing("", "xyz"        = "xyz"
       Strings.CS.appendIfMissing("abc", "xyz")    = "abcxyz"
       Strings.CS.appendIfMissing("abcxyz", "xyz") = "abcxyz"
       Strings.CS.appendIfMissing("abcXYZ", "xyz") = "abcXYZxyz"
       

      With additional suffixes:

       Strings.CS.appendIfMissing(null, null, null)       = null
       Strings.CS.appendIfMissing("abc", null, null)      = "abc"
       Strings.CS.appendIfMissing("", "xyz", null)        = "xyz"
       Strings.CS.appendIfMissing("abc", "xyz", new CharSequence[]{null}) = "abcxyz"
       Strings.CS.appendIfMissing("abc", "xyz", "")       = "abc"
       Strings.CS.appendIfMissing("abc", "xyz", "mno")    = "abcxyz"
       Strings.CS.appendIfMissing("abcxyz", "xyz", "mno") = "abcxyz"
       Strings.CS.appendIfMissing("abcmno", "xyz", "mno") = "abcmno"
       Strings.CS.appendIfMissing("abcXYZ", "xyz", "mno") = "abcXYZxyz"
       Strings.CS.appendIfMissing("abcMNO", "xyz", "mno") = "abcMNOxyz"
       

      Case-insensitive examples

       Strings.CI.appendIfMissing(null, null)      = null
       Strings.CI.appendIfMissing("abc", null)     = "abc"
       Strings.CI.appendIfMissing("", "xyz")       = "xyz"
       Strings.CI.appendIfMissing("abc", "xyz")    = "abcxyz"
       Strings.CI.appendIfMissing("abcxyz", "xyz") = "abcxyz"
       Strings.CI.appendIfMissing("abcXYZ", "xyz") = "abcXYZ"
       

      With additional suffixes:

       Strings.CI.appendIfMissing(null, null, null)       = null
       Strings.CI.appendIfMissing("abc", null, null)      = "abc"
       Strings.CI.appendIfMissing("", "xyz", null)        = "xyz"
       Strings.CI.appendIfMissing("abc", "xyz", new CharSequence[]{null}) = "abcxyz"
       Strings.CI.appendIfMissing("abc", "xyz", "")       = "abc"
       Strings.CI.appendIfMissing("abc", "xyz", "mno")    = "abcxyz"
       Strings.CI.appendIfMissing("abcxyz", "xyz", "mno") = "abcxyz"
       Strings.CI.appendIfMissing("abcmno", "xyz", "mno") = "abcmno"
       Strings.CI.appendIfMissing("abcXYZ", "xyz", "mno") = "abcXYZ"
       Strings.CI.appendIfMissing("abcMNO", "xyz", "mno") = "abcMNO"
       
      Parameters:
      str - The string.
      suffix - The suffix to append to the end of the string.
      suffixes - Additional suffixes that are valid terminators (optional).
      Returns:
      A new String if suffix was appended, the same string otherwise.
    • compare

      public abstract int compare(String str1, String str2)
      Compare two Strings lexicographically, like String.compareTo(String).

      The return values are:

      • int = 0, if str1 is equal to str2 (or both null)
      • int < 0, if str1 is less than str2
      • int > 0, if str1 is greater than str2

      This is a null safe version of :

       str1.compareTo(str2)
       

      null value is considered less than non-null value. Two null references are considered equal.

      Case-sensitive examples

      
       Strings.CS.compare(null, null)   = 0
       Strings.CS.compare(null , "a")   < 0
       Strings.CS.compare("a", null)   > 0
       Strings.CS.compare("abc", "abc") = 0
       Strings.CS.compare("a", "b")     < 0
       Strings.CS.compare("b", "a")     > 0
       Strings.CS.compare("a", "B")     > 0
       Strings.CS.compare("ab", "abc")  < 0
       

      Case-insensitive examples

      
       Strings.CI.compareIgnoreCase(null, null)   = 0
       Strings.CI.compareIgnoreCase(null , "a")   < 0
       Strings.CI.compareIgnoreCase("a", null)    > 0
       Strings.CI.compareIgnoreCase("abc", "abc") = 0
       Strings.CI.compareIgnoreCase("abc", "ABC") = 0
       Strings.CI.compareIgnoreCase("a", "b")     < 0
       Strings.CI.compareIgnoreCase("b", "a")     > 0
       Strings.CI.compareIgnoreCase("a", "B")     < 0
       Strings.CI.compareIgnoreCase("A", "b")     < 0
       Strings.CI.compareIgnoreCase("ab", "ABC")  < 0
       
      Parameters:
      str1 - the String to compare from
      str2 - the String to compare to
      Returns:
      < 0, 0, > 0, if str1 is respectively less, equal or greater than str2
      See Also:
    • contains

      public abstract boolean contains(CharSequence seq, CharSequence searchSeq)
      Tests if CharSequence contains a search CharSequence, handling null. This method uses String.indexOf(String) if possible.

      A null CharSequence will return false.

      Case-sensitive examples

       Strings.CS.contains(null, *)     = false
       Strings.CS.contains(*, null)     = false
       Strings.CS.contains("", "")      = true
       Strings.CS.contains("abc", "")   = true
       Strings.CS.contains("abc", "a")  = true
       Strings.CS.contains("abc", "z")  = false
       

      Case-insensitive examples

       Strings.CI.containsIgnoreCase(null, *)    = false
       Strings.CI.containsIgnoreCase(*, null)    = false
       Strings.CI.containsIgnoreCase("", "")     = true
       Strings.CI.containsIgnoreCase("abc", "")  = true
       Strings.CI.containsIgnoreCase("abc", "a") = true
       Strings.CI.containsIgnoreCase("abc", "z") = false
       Strings.CI.containsIgnoreCase("abc", "A") = true
       Strings.CI.containsIgnoreCase("abc", "Z") = false
       
      Parameters:
      seq - the CharSequence to check, may be null
      searchSeq - the CharSequence to find, may be null
      Returns:
      true if the CharSequence contains the search CharSequence, false if not or null string input
    • containsAny

      public boolean containsAny(CharSequence cs, CharSequence... searchCharSequences)
      Tests if the CharSequence contains any of the CharSequences in the given array.

      A null cs CharSequence will return false. A null or zero length search array will return false.

      Case-sensitive examples

       Strings.CS.containsAny(null, *)            = false
       Strings.CS.containsAny("", *)              = false
       Strings.CS.containsAny(*, null)            = false
       Strings.CS.containsAny(*, [])              = false
       Strings.CS.containsAny("abcd", "ab", null) = true
       Strings.CS.containsAny("abcd", "ab", "cd") = true
       Strings.CS.containsAny("abc", "d", "abc")  = true
       

      Case-insensitive examples

       Strings.CI.containsAny(null, *)            = false
       Strings.CI.containsAny("", *)              = false
       Strings.CI.containsAny(*, null)            = false
       Strings.CI.containsAny(*, [])              = false
       Strings.CI.containsAny("abcd", "ab", null) = true
       Strings.CI.containsAny("abcd", "ab", "cd") = true
       Strings.CI.containsAny("abc", "d", "abc")  = true
       Strings.CI.containsAny("abc", "D", "ABC")  = true
       Strings.CI.containsAny("ABC", "d", "abc")  = true
       
      Parameters:
      cs - The CharSequence to check, may be null
      searchCharSequences - The array of CharSequences to search for, may be null. Individual CharSequences may be null as well.
      Returns:
      true if any of the search CharSequences are found, false otherwise
    • endsWith

      public boolean endsWith(CharSequence str, CharSequence suffix)
      Tests if a CharSequence ends with a specified suffix.

      Case-sensitive examples

       Strings.CS.endsWith(null, null)      = true
       Strings.CS.endsWith(null, "def")     = false
       Strings.CS.endsWith("abcdef", null)  = false
       Strings.CS.endsWith("abcdef", "def") = true
       Strings.CS.endsWith("ABCDEF", "def") = false
       Strings.CS.endsWith("ABCDEF", "cde") = false
       Strings.CS.endsWith("ABCDEF", "")    = true
       

      Case-insensitive examples

       Strings.CI.endsWith(null, null)      = true
       Strings.CI.endsWith(null, "def")     = false
       Strings.CI.endsWith("abcdef", null)  = false
       Strings.CI.endsWith("abcdef", "def") = true
       Strings.CI.endsWith("ABCDEF", "def") = true
       Strings.CI.endsWith("ABCDEF", "cde") = false
       
      Parameters:
      str - the CharSequence to check, may be null.
      suffix - the suffix to find, may be null.
      Returns:
      true if the CharSequence starts with the prefix or both null.
      See Also:
    • endsWithAny

      public boolean endsWithAny(CharSequence sequence, CharSequence... searchStrings)
      Tests if a CharSequence ends with any of the provided suffixes.

      Case-sensitive examples

       Strings.CS.endsWithAny(null, null)                  = false
       Strings.CS.endsWithAny(null, new String[] {"abc"})  = false
       Strings.CS.endsWithAny("abcxyz", null)              = false
       Strings.CS.endsWithAny("abcxyz", new String[] {""}) = true
       Strings.CS.endsWithAny("abcxyz", new String[] {"xyz"}) = true
       Strings.CS.endsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
       Strings.CS.endsWithAny("abcXYZ", "def", "XYZ")      = true
       Strings.CS.endsWithAny("abcXYZ", "def", "xyz")      = false
       
      Parameters:
      sequence - the CharSequence to check, may be null
      searchStrings - the CharSequence suffixes to find, may be empty or contain null
      Returns:
      true if the input sequence is null AND no searchStrings are provided, or the input sequence ends in any of the provided searchStrings.
      See Also:
    • equals

      public abstract boolean equals(CharSequence cs1, CharSequence cs2)
      Compares two CharSequences, returning true if they represent equal sequences of characters.

      nulls are handled without exceptions. Two null references are considered to be equal.

      Case-sensitive examples

       Strings.CS.equals(null, null)   = true
       Strings.CS.equals(null, "abc")  = false
       Strings.CS.equals("abc", null)  = false
       Strings.CS.equals("abc", "abc") = true
       Strings.CS.equals("abc", "ABC") = false
       

      Case-insensitive examples

       Strings.CI.equalsIgnoreCase(null, null)   = true
       Strings.CI.equalsIgnoreCase(null, "abc")  = false
       Strings.CI.equalsIgnoreCase("abc", null)  = false
       Strings.CI.equalsIgnoreCase("abc", "abc") = true
       Strings.CI.equalsIgnoreCase("abc", "ABC") = true
       
      Parameters:
      cs1 - the first CharSequence, may be null
      cs2 - the second CharSequence, may be null
      Returns:
      true if the CharSequences are equal (case-sensitive), or both null
      See Also:
    • equals

      public abstract boolean equals(String str1, String str2)
      Compares two CharSequences, returning true if they represent equal sequences of characters.

      nulls are handled without exceptions. Two null references are considered to be equal.

      Case-sensitive examples

       Strings.CS.equals(null, null)   = true
       Strings.CS.equals(null, "abc")  = false
       Strings.CS.equals("abc", null)  = false
       Strings.CS.equals("abc", "abc") = true
       Strings.CS.equals("abc", "ABC") = false
       

      Case-insensitive examples

       Strings.CI.equalsIgnoreCase(null, null)   = true
       Strings.CI.equalsIgnoreCase(null, "abc")  = false
       Strings.CI.equalsIgnoreCase("abc", null)  = false
       Strings.CI.equalsIgnoreCase("abc", "abc") = true
       Strings.CI.equalsIgnoreCase("abc", "ABC") = true
       
      Parameters:
      str1 - the first CharSequence, may be null
      str2 - the second CharSequence, may be null
      Returns:
      true if the CharSequences are equal (case-sensitive), or both null
      See Also:
    • equalsAny

      public boolean equalsAny(CharSequence string, CharSequence... searchStrings)
      Compares given string to a CharSequences vararg of searchStrings, returning true if the string is equal to any of the searchStrings.

      Case-sensitive examples

       Strings.CS.equalsAny(null, (CharSequence[]) null) = false
       Strings.CS.equalsAny(null, null, null)    = true
       Strings.CS.equalsAny(null, "abc", "def")  = false
       Strings.CS.equalsAny("abc", null, "def")  = false
       Strings.CS.equalsAny("abc", "abc", "def") = true
       Strings.CS.equalsAny("abc", "ABC", "DEF") = false
       

      Case-insensitive examples

       Strings.CI.equalsAny(null, (CharSequence[]) null) = false
       Strings.CI.equalsAny(null, null, null)    = true
       Strings.CI.equalsAny(null, "abc", "def")  = false
       Strings.CI.equalsAny("abc", null, "def")  = false
       Strings.CI.equalsAny("abc", "abc", "def") = true
       Strings.CI.equalsAny("abc", "ABC", "DEF") = false
       
      Parameters:
      string - to compare, may be null.
      searchStrings - a vararg of strings, may be null.
      Returns:
      true if the string is equal (case-sensitive) to any other element of searchStrings; false if searchStrings is null or contains no matches.
    • indexOf

      public int indexOf(CharSequence seq, CharSequence searchSeq)
      Finds the first index within a CharSequence, handling null. This method uses String.indexOf(String, int) if possible.

      A null CharSequence will return -1.

      Case-sensitive examples

       Strings.CS.indexOf(null, *)          = -1
       Strings.CS.indexOf(*, null)          = -1
       Strings.CS.indexOf("", "")           = 0
       Strings.CS.indexOf("", *)            = -1 (except when * = "")
       Strings.CS.indexOf("aabaabaa", "a")  = 0
       Strings.CS.indexOf("aabaabaa", "b")  = 2
       Strings.CS.indexOf("aabaabaa", "ab") = 1
       Strings.CS.indexOf("aabaabaa", "")   = 0
       

      Case-insensitive examples

       Strings.CI.indexOfIgnoreCase(null, *)          = -1
       Strings.CI.indexOfIgnoreCase(*, null)          = -1
       Strings.CI.indexOfIgnoreCase("", "")           = 0
       Strings.CI.indexOfIgnoreCase(" ", " ")         = 0
       Strings.CI.indexOfIgnoreCase("aabaabaa", "a")  = 0
       Strings.CI.indexOfIgnoreCase("aabaabaa", "b")  = 2
       Strings.CI.indexOfIgnoreCase("aabaabaa", "ab") = 1
       
      Parameters:
      seq - the CharSequence to check, may be null
      searchSeq - the CharSequence to find, may be null
      Returns:
      the first index of the search CharSequence, -1 if no match or null string input
    • indexOf

      public abstract int indexOf(CharSequence seq, CharSequence searchSeq, int startPos)
      Finds the first index within a CharSequence, handling null. This method uses String.indexOf(String, int) if possible.

      A null CharSequence will return -1. A negative start position is treated as zero. An empty ("") search CharSequence always matches. A start position greater than the string length only matches an empty search CharSequence.

      Case-sensitive examples

       Strings.CS.indexOf(null, *, *)          = -1
       Strings.CS.indexOf(*, null, *)          = -1
       Strings.CS.indexOf("", "", 0)           = 0
       Strings.CS.indexOf("", *, 0)            = -1 (except when * = "")
       Strings.CS.indexOf("aabaabaa", "a", 0)  = 0
       Strings.CS.indexOf("aabaabaa", "b", 0)  = 2
       Strings.CS.indexOf("aabaabaa", "ab", 0) = 1
       Strings.CS.indexOf("aabaabaa", "b", 3)  = 5
       Strings.CS.indexOf("aabaabaa", "b", 9)  = -1
       Strings.CS.indexOf("aabaabaa", "b", -1) = 2
       Strings.CS.indexOf("aabaabaa", "", 2)   = 2
       Strings.CS.indexOf("abc", "", 9)        = 3
       

      Case-insensitive examples

       Strings.CI.indexOfIgnoreCase(null, *, *)          = -1
       Strings.CI.indexOfIgnoreCase(*, null, *)          = -1
       Strings.CI.indexOfIgnoreCase("", "", 0)           = 0
       Strings.CI.indexOfIgnoreCase("aabaabaa", "A", 0)  = 0
       Strings.CI.indexOfIgnoreCase("aabaabaa", "B", 0)  = 2
       Strings.CI.indexOfIgnoreCase("aabaabaa", "AB", 0) = 1
       Strings.CI.indexOfIgnoreCase("aabaabaa", "B", 3)  = 5
       Strings.CI.indexOfIgnoreCase("aabaabaa", "B", 9)  = -1
       Strings.CI.indexOfIgnoreCase("aabaabaa", "B", -1) = 2
       Strings.CI.indexOfIgnoreCase("aabaabaa", "", 2)   = 2
       Strings.CI.indexOfIgnoreCase("abc", "", 9)        = -1
       
      Parameters:
      seq - the CharSequence to check, may be null
      searchSeq - the CharSequence to find, may be null
      startPos - the start position, negative treated as zero
      Returns:
      the first index of the search CharSequence (always ≥ startPos), -1 if no match or null string input
    • isCaseSensitive

      public boolean isCaseSensitive()
      Tests whether to ignore case.
      Returns:
      whether to ignore case.
    • lastIndexOf

      public int lastIndexOf(CharSequence str, CharSequence searchStr)
      Finds the last index within a CharSequence, handling null. This method uses String.lastIndexOf(String) if possible.

      A null CharSequence will return -1.

      Case-sensitive examples

       Strings.CS.lastIndexOf(null, *)          = -1
       Strings.CS.lastIndexOf(*, null)          = -1
       Strings.CS.lastIndexOf("", "")           = 0
       Strings.CS.lastIndexOf("aabaabaa", "a")  = 7
       Strings.CS.lastIndexOf("aabaabaa", "b")  = 5
       Strings.CS.lastIndexOf("aabaabaa", "ab") = 4
       Strings.CS.lastIndexOf("aabaabaa", "")   = 8
       

      Case-insensitive examples

       Strings.CI.lastIndexOfIgnoreCase(null, *)          = -1
       Strings.CI.lastIndexOfIgnoreCase(*, null)          = -1
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "A")  = 7
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "B")  = 5
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "AB") = 4
       
      Parameters:
      str - the CharSequence to check, may be null
      searchStr - the CharSequence to find, may be null
      Returns:
      the last index of the search String, -1 if no match or null string input
    • lastIndexOf

      public abstract int lastIndexOf(CharSequence seq, CharSequence searchSeq, int startPos)
      Finds the last index within a CharSequence, handling null. This method uses String.lastIndexOf(String, int) if possible.

      A null CharSequence will return -1. A negative start position returns -1. An empty ("") search CharSequence always matches unless the start position is negative. A start position greater than the string length searches the whole string. The search starts at the startPos and works backwards; matches starting after the start position are ignored.

      Case-sensitive examples

       Strings.CS.lastIndexOf(null, *, *)          = -1
       Strings.CS.lastIndexOf(*, null, *)          = -1
       Strings.CS.lastIndexOf("aabaabaa", "a", 8)  = 7
       Strings.CS.lastIndexOf("aabaabaa", "b", 8)  = 5
       Strings.CS.lastIndexOf("aabaabaa", "ab", 8) = 4
       Strings.CS.lastIndexOf("aabaabaa", "b", 9)  = 5
       Strings.CS.lastIndexOf("aabaabaa", "b", -1) = -1
       Strings.CS.lastIndexOf("aabaabaa", "a", 0)  = 0
       Strings.CS.lastIndexOf("aabaabaa", "b", 0)  = -1
       Strings.CS.lastIndexOf("aabaabaa", "b", 1)  = -1
       Strings.CS.lastIndexOf("aabaabaa", "b", 2)  = 2
       Strings.CS.lastIndexOf("aabaabaa", "ba", 2)  = 2
       

      Case-insensitive examples

       Strings.CI.lastIndexOfIgnoreCase(null, *, *)          = -1
       Strings.CI.lastIndexOfIgnoreCase(*, null, *)          = -1
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "A", 8)  = 7
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "B", 8)  = 5
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "AB", 8) = 4
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "B", 9)  = 5
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "B", -1) = -1
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "A", 0)  = 0
       Strings.CI.lastIndexOfIgnoreCase("aabaabaa", "B", 0)  = -1
       
      Parameters:
      seq - the CharSequence to check, may be null
      searchSeq - the CharSequence to find, may be null
      startPos - the start position, negative treated as zero
      Returns:
      the last index of the search CharSequence (always ≤ startPos), -1 if no match or null string input
    • prependIfMissing

      public String prependIfMissing(String str, CharSequence prefix, CharSequence... prefixes)
      Prepends the prefix to the start of the string if the string does not already start with any of the prefixes.

      Case-sensitive examples

       Strings.CS.prependIfMissing(null, null) = null
       Strings.CS.prependIfMissing("abc", null) = "abc"
       Strings.CS.prependIfMissing("", "xyz") = "xyz"
       Strings.CS.prependIfMissing("abc", "xyz") = "xyzabc"
       Strings.CS.prependIfMissing("xyzabc", "xyz") = "xyzabc"
       Strings.CS.prependIfMissing("XYZabc", "xyz") = "xyzXYZabc"
       

      With additional prefixes,

       Strings.CS.prependIfMissing(null, null, null) = null
       Strings.CS.prependIfMissing("abc", null, null) = "abc"
       Strings.CS.prependIfMissing("", "xyz", null) = "xyz"
       Strings.CS.prependIfMissing("abc", "xyz", new CharSequence[]{null}) = "xyzabc"
       Strings.CS.prependIfMissing("abc", "xyz", "") = "abc"
       Strings.CS.prependIfMissing("abc", "xyz", "mno") = "xyzabc"
       Strings.CS.prependIfMissing("xyzabc", "xyz", "mno") = "xyzabc"
       Strings.CS.prependIfMissing("mnoabc", "xyz", "mno") = "mnoabc"
       Strings.CS.prependIfMissing("XYZabc", "xyz", "mno") = "xyzXYZabc"
       Strings.CS.prependIfMissing("MNOabc", "xyz", "mno") = "xyzMNOabc"
       

      Case-insensitive examples

       Strings.CI.prependIfMissingIgnoreCase(null, null) = null
       Strings.CI.prependIfMissingIgnoreCase("abc", null) = "abc"
       Strings.CI.prependIfMissingIgnoreCase("", "xyz") = "xyz"
       Strings.CI.prependIfMissingIgnoreCase("abc", "xyz") = "xyzabc"
       Strings.CI.prependIfMissingIgnoreCase("xyzabc", "xyz") = "xyzabc"
       Strings.CI.prependIfMissingIgnoreCase("XYZabc", "xyz") = "XYZabc"
       

      With additional prefixes,

       Strings.CI.prependIfMissingIgnoreCase(null, null, null) = null
       Strings.CI.prependIfMissingIgnoreCase("abc", null, null) = "abc"
       Strings.CI.prependIfMissingIgnoreCase("", "xyz", null) = "xyz"
       Strings.CI.prependIfMissingIgnoreCase("abc", "xyz", new CharSequence[]{null}) = "xyzabc"
       Strings.CI.prependIfMissingIgnoreCase("abc", "xyz", "") = "abc"
       Strings.CI.prependIfMissingIgnoreCase("abc", "xyz", "mno") = "xyzabc"
       Strings.CI.prependIfMissingIgnoreCase("xyzabc", "xyz", "mno") = "xyzabc"
       Strings.CI.prependIfMissingIgnoreCase("mnoabc", "xyz", "mno") = "mnoabc"
       Strings.CI.prependIfMissingIgnoreCase("XYZabc", "xyz", "mno") = "XYZabc"
       Strings.CI.prependIfMissingIgnoreCase("MNOabc", "xyz", "mno") = "MNOabc"
       
      Parameters:
      str - The string.
      prefix - The prefix to prepend to the start of the string.
      prefixes - Additional prefixes that are valid.
      Returns:
      A new String if prefix was prepended, the same string otherwise.
    • remove

      public String remove(String str, String remove)
      Removes all occurrences of a substring from within the source string.

      A null source string will return null. An empty ("") source string will return the empty string. A null remove string will return the source string. An empty ("") remove string will return the source string.

      Case-sensitive examples

       Strings.CS.remove(null, *)        = null
       Strings.CS.remove("", *)          = ""
       Strings.CS.remove(*, null)        = *
       Strings.CS.remove(*, "")          = *
       Strings.CS.remove("queued", "ue") = "qd"
       Strings.CS.remove("queued", "zz") = "queued"
       

      Case-insensitive examples

       Strings.CI.removeIgnoreCase(null, *)        = null
       Strings.CI.removeIgnoreCase("", *)          = ""
       Strings.CI.removeIgnoreCase(*, null)        = *
       Strings.CI.removeIgnoreCase(*, "")          = *
       Strings.CI.removeIgnoreCase("queued", "ue") = "qd"
       Strings.CI.removeIgnoreCase("queued", "zz") = "queued"
       Strings.CI.removeIgnoreCase("quEUed", "UE") = "qd"
       Strings.CI.removeIgnoreCase("queued", "zZ") = "queued"
       
      Parameters:
      str - the source String to search, may be null
      remove - the String to search for and remove, may be null
      Returns:
      the substring with the string removed if found, null if null String input
    • removeEnd

      public String removeEnd(String str, CharSequence remove)
      Case-insensitive removal of a substring if it is at the end of a source string, otherwise returns the source string.

      A null source string will return null. An empty ("") source string will return the empty string. A null search string will return the source string.

      Case-sensitive examples

       Strings.CS.removeEnd(null, *)      = null
       Strings.CS.removeEnd("", *)        = ""
       Strings.CS.removeEnd(*, null)      = *
       Strings.CS.removeEnd("www.domain.com", ".com.")  = "www.domain.com"
       Strings.CS.removeEnd("www.domain.com", ".com")   = "www.domain"
       Strings.CS.removeEnd("www.domain.com", "domain") = "www.domain.com"
       Strings.CS.removeEnd("abc", "")    = "abc"
       

      Case-insensitive examples

       Strings.CI.removeEndIgnoreCase(null, *)      = null
       Strings.CI.removeEndIgnoreCase("", *)        = ""
       Strings.CI.removeEndIgnoreCase(*, null)      = *
       Strings.CI.removeEndIgnoreCase("www.domain.com", ".com.")  = "www.domain.com"
       Strings.CI.removeEndIgnoreCase("www.domain.com", ".com")   = "www.domain"
       Strings.CI.removeEndIgnoreCase("www.domain.com", "domain") = "www.domain.com"
       Strings.CI.removeEndIgnoreCase("abc", "")    = "abc"
       Strings.CI.removeEndIgnoreCase("www.domain.com", ".COM") = "www.domain")
       Strings.CI.removeEndIgnoreCase("www.domain.COM", ".com") = "www.domain")
       
      Parameters:
      str - the source String to search, may be null
      remove - the String to search for (case-insensitive) and remove, may be null
      Returns:
      the substring with the string removed if found, null if null String input
    • removeStart

      public String removeStart(String str, CharSequence remove)
      Case-insensitive removal of a substring if it is at the beginning of a source string, otherwise returns the source string.

      A null source string will return null. An empty ("") source string will return the empty string. A null search string will return the source string.

      Case-sensitive examples

       Strings.CS.removeStart(null, *)      = null
       Strings.CS.removeStart("", *)        = ""
       Strings.CS.removeStart(*, null)      = *
       Strings.CS.removeStart("www.domain.com", "www.")   = "domain.com"
       Strings.CS.removeStart("domain.com", "www.")       = "domain.com"
       Strings.CS.removeStart("www.domain.com", "domain") = "www.domain.com"
       Strings.CS.removeStart("abc", "")    = "abc"
       

      Case-insensitive examples

       Strings.CI.removeStartIgnoreCase(null, *)      = null
       Strings.CI.removeStartIgnoreCase("", *)        = ""
       Strings.CI.removeStartIgnoreCase(*, null)      = *
       Strings.CI.removeStartIgnoreCase("www.domain.com", "www.")   = "domain.com"
       Strings.CI.removeStartIgnoreCase("www.domain.com", "WWW.")   = "domain.com"
       Strings.CI.removeStartIgnoreCase("domain.com", "www.")       = "domain.com"
       Strings.CI.removeStartIgnoreCase("www.domain.com", "domain") = "www.domain.com"
       Strings.CI.removeStartIgnoreCase("abc", "")    = "abc"
       
      Parameters:
      str - the source String to search, may be null
      remove - the String to search for (case-insensitive) and remove, may be null
      Returns:
      the substring with the string removed if found, null if null String input
    • replace

      public String replace(String text, String searchString, String replacement)
      Case insensitively replaces all occurrences of a String within another String.

      A null reference passed to this method is a no-op.

      Case-sensitive examples

       Strings.CS.replace(null, *, *)        = null
       Strings.CS.replace("", *, *)          = ""
       Strings.CS.replace("any", null, *)    = "any"
       Strings.CS.replace("any", *, null)    = "any"
       Strings.CS.replace("any", "", *)      = "any"
       Strings.CS.replace("aba", "a", null)  = "aba"
       Strings.CS.replace("aba", "a", "")    = "b"
       Strings.CS.replace("aba", "a", "z")   = "zbz"
       

      Case-insensitive examples

       Strings.CI.replaceIgnoreCase(null, *, *)        = null
       Strings.CI.replaceIgnoreCase("", *, *)          = ""
       Strings.CI.replaceIgnoreCase("any", null, *)    = "any"
       Strings.CI.replaceIgnoreCase("any", *, null)    = "any"
       Strings.CI.replaceIgnoreCase("any", "", *)      = "any"
       Strings.CI.replaceIgnoreCase("aba", "a", null)  = "aba"
       Strings.CI.replaceIgnoreCase("abA", "A", "")    = "b"
       Strings.CI.replaceIgnoreCase("aba", "A", "z")   = "zbz"
       
      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
      See Also:
    • replace

      public String replace(String text, String searchString, 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.

      Case-sensitive examples

       Strings.CS.replace(null, *, *, *)         = null
       Strings.CS.replace("", *, *, *)           = ""
       Strings.CS.replace("any", null, *, *)     = "any"
       Strings.CS.replace("any", *, null, *)     = "any"
       Strings.CS.replace("any", "", *, *)       = "any"
       Strings.CS.replace("any", *, *, 0)        = "any"
       Strings.CS.replace("abaa", "a", null, -1) = "abaa"
       Strings.CS.replace("abaa", "a", "", -1)   = "b"
       Strings.CS.replace("abaa", "a", "z", 0)   = "abaa"
       Strings.CS.replace("abaa", "a", "z", 1)   = "zbaa"
       Strings.CS.replace("abaa", "a", "z", 2)   = "zbza"
       Strings.CS.replace("abaa", "a", "z", -1)  = "zbzz"
       

      Case-insensitive examples

       Strings.CI.replaceIgnoreCase(null, *, *, *)         = null
       Strings.CI.replaceIgnoreCase("", *, *, *)           = ""
       Strings.CI.replaceIgnoreCase("any", null, *, *)     = "any"
       Strings.CI.replaceIgnoreCase("any", *, null, *)     = "any"
       Strings.CI.replaceIgnoreCase("any", "", *, *)       = "any"
       Strings.CI.replaceIgnoreCase("any", *, *, 0)        = "any"
       Strings.CI.replaceIgnoreCase("abaa", "a", null, -1) = "abaa"
       Strings.CI.replaceIgnoreCase("abaa", "a", "", -1)   = "b"
       Strings.CI.replaceIgnoreCase("abaa", "a", "z", 0)   = "abaa"
       Strings.CI.replaceIgnoreCase("abaa", "A", "z", 1)   = "zbaa"
       Strings.CI.replaceIgnoreCase("abAa", "a", "z", 2)   = "zbza"
       Strings.CI.replaceIgnoreCase("abAa", "a", "z", -1)  = "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
      max - maximum number of values to replace, or -1 if no maximum
      Returns:
      the text with any replacements processed, null if null String input
    • replaceOnce

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

      Case-sensitive examples

       Strings.CS.replaceOnce(null, *, *)        = null
       Strings.CS.replaceOnce("", *, *)          = ""
       Strings.CS.replaceOnce("any", null, *)    = "any"
       Strings.CS.replaceOnce("any", *, null)    = "any"
       Strings.CS.replaceOnce("any", "", *)      = "any"
       Strings.CS.replaceOnce("aba", "a", null)  = "aba"
       Strings.CS.replaceOnce("aba", "a", "")    = "ba"
       Strings.CS.replaceOnce("aba", "a", "z")   = "zba"
       

      Case-insensitive examples

       Strings.CI.replaceOnceIgnoreCase(null, *, *)        = null
       Strings.CI.replaceOnceIgnoreCase("", *, *)          = ""
       Strings.CI.replaceOnceIgnoreCase("any", null, *)    = "any"
       Strings.CI.replaceOnceIgnoreCase("any", *, null)    = "any"
       Strings.CI.replaceOnceIgnoreCase("any", "", *)      = "any"
       Strings.CI.replaceOnceIgnoreCase("aba", "a", null)  = "aba"
       Strings.CI.replaceOnceIgnoreCase("aba", "a", "")    = "ba"
       Strings.CI.replaceOnceIgnoreCase("aba", "a", "z")   = "zba"
       Strings.CI.replaceOnceIgnoreCase("FoOFoofoo", "foo", "") = "Foofoo"
       
      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:
    • startsWith

      public boolean startsWith(CharSequence str, CharSequence prefix)
      Tests if a CharSequence starts with a specified prefix.

      nulls are handled without exceptions. Two null references are considered to be equal.

      Case-sensitive examples

       Strings.CS.startsWith(null, null)      = true
       Strings.CS.startsWith(null, "abc")     = false
       Strings.CS.startsWith("abcdef", null)  = false
       Strings.CS.startsWith("abcdef", "abc") = true
       Strings.CS.startsWith("ABCDEF", "abc") = false
       

      Case-insensitive examples

       Strings.CI.startsWithIgnoreCase(null, null)      = true
       Strings.CI.startsWithIgnoreCase(null, "abc")     = false
       Strings.CI.startsWithIgnoreCase("abcdef", null)  = false
       Strings.CI.startsWithIgnoreCase("abcdef", "abc") = true
       Strings.CI.startsWithIgnoreCase("ABCDEF", "abc") = true
       
      Parameters:
      str - the CharSequence to check, may be null
      prefix - the prefix to find, may be null
      Returns:
      true if the CharSequence starts with the prefix, case-sensitive, or both null
      See Also:
    • startsWithAny

      public boolean startsWithAny(CharSequence sequence, CharSequence... searchStrings)
      Tests if a CharSequence starts with any of the provided prefixes.

      Case-sensitive examples

       Strings.CS.startsWithAny(null, null)      = false
       Strings.CS.startsWithAny(null, new String[] {"abc"})  = false
       Strings.CS.startsWithAny("abcxyz", null)     = false
       Strings.CS.startsWithAny("abcxyz", new String[] {""}) = true
       Strings.CS.startsWithAny("abcxyz", new String[] {"abc"}) = true
       Strings.CS.startsWithAny("abcxyz", new String[] {null, "xyz", "abc"}) = true
       Strings.CS.startsWithAny("abcxyz", null, "xyz", "ABCX") = false
       Strings.CS.startsWithAny("ABCXYZ", null, "xyz", "abc") = false
       

      Case-insensitive examples

       Strings.CI.startsWithAny(null, null)      = false
       Strings.CI.startsWithAny(null, new String[] {"aBc"})  = false
       Strings.CI.startsWithAny("AbCxYz", null)     = false
       Strings.CI.startsWithAny("AbCxYz", new String[] {""}) = true
       Strings.CI.startsWithAny("AbCxYz", new String[] {"aBc"}) = true
       Strings.CI.startsWithAny("AbCxYz", new String[] {null, "XyZ", "aBc"}) = true
       Strings.CI.startsWithAny("abcxyz", null, "xyz", "ABCX") = true
       Strings.CI.startsWithAny("ABCXYZ", null, "xyz", "abc") = true
       
      Parameters:
      sequence - the CharSequence to check, may be null
      searchStrings - the CharSequence prefixes, may be empty or contain null
      Returns:
      true if the input sequence is null AND no searchStrings are provided, or the input sequence begins with any of the provided searchStrings.
      See Also: