Package com.helger.base.string

Class StringReplace

java.lang.Object
com.helger.base.string.StringReplace
@Immutable public final class StringReplace extends Object
Helper class for replacing characters and substrings within strings, with support for multiple replacements and streaming output.
Author:
Philip Helger

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    getReplaceMultipleResultLength(char @NonNull [] aInputString, @com.helger.annotation.Nonempty char @NonNull [] aSearchChars, @com.helger.annotation.Nonempty char[] @NonNull [] aReplacementStrings)
    Get the result length (in characters) when replacing all patterns with the replacements on the passed input array.
    static @Nullable String
    replaceAll(@Nullable String sInputString, char cSearchChar, char cReplacementChar)
    This is a fast replacement for String.replace(char, char) for characters.
    static @Nullable String
    replaceAll(@Nullable String sInputString, @NonNull String sSearchText, @NonNull CharSequence aReplacementText)
    This is a fast replacement for String.replace(CharSequence, CharSequence).
    static @Nullable String
    replaceAllRepeatedly(@Nullable String sInputString, @NonNull String sSearchText, @NonNull String sReplacementText)
    Just calls replaceAll as long as there are still replacements found
    static String
    replaceAllSafe(@Nullable String sInputString, @NonNull String sSearchText, @Nullable CharSequence aReplacementText)
    Same as replaceAll(String, String, CharSequence) but allowing for a null new-value, which is than interpreted as an empty string instead.
    static char @NonNull []
    replaceMultiple(char @Nullable [] aInput, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings)
    Optimized replace method that replaces a set of characters with a set of strings.
    static char @NonNull []
    replaceMultiple(@Nullable String sInputString, char @NonNull [] aSearchChars, char cReplacementChar)
    Optimized replace method that replaces a set of characters with another character.
    static char @NonNull []
    replaceMultiple(@Nullable String sInputString, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings)
    Optimized replace method that replaces a set of characters with a set of strings.
    static @Nullable String
    replaceMultiple(@Nullable String sInputString, @Nullable String[] aSearchTexts, @Nullable String[] aReplacementTexts)
    Perform all string replacements on the input string as defined by the passed map.
    static @Nullable String
    replaceMultiple(@Nullable String sInputString, @Nullable Map<String,String> aTransTable)
    Perform all string replacements on the input string as defined by the passed map.
    static @NonNull String
    replaceMultipleAsString(@Nullable String sInputString, char @NonNull [] aSearchChars, char cReplacementChar)
    Optimized replace method that replaces a set of characters with another character.
    static int
    replaceMultipleTo(char @Nullable [] aInput, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings, @NonNull Writer aTarget)
    Specialized version of replaceMultiple(String, char[], char[][]) where the object where the output should be appended is passed in as a parameter.
    static int
    replaceMultipleTo(char @Nullable [] aInput, int nOfs, int nLen, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings, @NonNull Writer aTarget)
    Specialized version of replaceMultiple(String, char[], char[][]) where the object where the output should be appended is passed in as a parameter.
    static int
    replaceMultipleTo(@Nullable String sInputString, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings, @NonNull Writer aTarget)
    Specialized version of replaceMultiple(String, char[], char[][]) where the object where the output should be appended is passed in as a parameter.
    static void
    replaceMultipleTo(@Nullable String sInputString, char @NonNull [] aSearchChars, char cReplacementChar, @NonNull Writer aTarget)
    Optimized replace method that replaces a set of characters with another character.
    static void
    replaceMultipleTo(@Nullable String sInputString, char @NonNull [] aSearchChars, char cReplacementChar, @NonNull StringBuilder aTarget)
    Optimized replace method that replaces a set of characters with another character.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • replaceAllSafe

      public static String replaceAllSafe(@Nullable String sInputString, @NonNull String sSearchText, @Nullable CharSequence aReplacementText)
      Same as replaceAll(String, String, CharSequence) but allowing for a null new-value, which is than interpreted as an empty string instead.
      Parameters:
      sInputString - The input string where the text should be replace. If this parameter is null or empty, no replacement is done.
      sSearchText - The string to be replaced. May neither be null nor empty.
      aReplacementText - The string with the replacement. May be null or empty.
      Returns:
      The input string as is, if the input string is empty or if the string to be replaced is not contained.

    • replaceAll

      public static @Nullable String replaceAll(@Nullable String sInputString, @NonNull String sSearchText, @NonNull CharSequence aReplacementText)
      This is a fast replacement for String.replace(CharSequence, CharSequence). The problem with the mentioned String method is, that is uses internally regular expressions which use a synchronized block to compile the patterns. This method is inherently thread safe since String is immutable and we're operating on different temporary StringBuilder objects.
      Parameters:
      sInputString - The input string where the text should be replace. If this parameter is null or empty, no replacement is done.
      sSearchText - The string to be replaced. May neither be null nor empty.
      aReplacementText - The string with the replacement. May not be null but may be empty.
      Returns:
      The input string as is, if the input string is empty or if the search pattern and the replacement are equal or if the string to be replaced is not contained.

    • replaceAll

      public static @Nullable String replaceAll(@Nullable String sInputString, char cSearchChar, char cReplacementChar)
      This is a fast replacement for String.replace(char, char) for characters. The problem with the mentioned String method is, that is uses internally regular expressions which use a synchronized block to compile the patterns. This method is inherently thread safe since String is immutable and we're operating on different temporary StringBuilder objects.
      Parameters:
      sInputString - The input string where the text should be replace. If this parameter is null or empty, no replacement is done.
      cSearchChar - The character to be replaced.
      cReplacementChar - The character with the replacement.
      Returns:
      The input string as is, if the input string is empty or if the search pattern and the replacement are equal or if the string to be replaced is not contained.

    • replaceAllRepeatedly

      public static @Nullable String replaceAllRepeatedly(@Nullable String sInputString, @NonNull String sSearchText, @NonNull String sReplacementText)
      Just calls replaceAll as long as there are still replacements found
      Parameters:
      sInputString - The input string where the text should be replace. If this parameter is null or empty, no replacement is done.
      sSearchText - The string to be replaced. May neither be null nor empty.
      sReplacementText - The string with the replacement. May not be null but may be empty.
      Returns:
      The input string as is, if the input string is empty or if the string to be replaced is not contained.

    • getReplaceMultipleResultLength

      public static int getReplaceMultipleResultLength(char @NonNull [] aInputString, @Nonempty @com.helger.annotation.Nonempty char @NonNull [] aSearchChars, @Nonempty @com.helger.annotation.Nonempty char[] @NonNull [] aReplacementStrings)
      Get the result length (in characters) when replacing all patterns with the replacements on the passed input array.
      Parameters:
      aInputString - Input char array. May not be null.
      aSearchChars - The one-character search patterns. May not be null.
      aReplacementStrings - The replacements to be performed. May not be null. The first dimension of this array must have exactly the same amount of elements as the patterns parameter array.
      Returns:
      CGlobal.ILLEGAL_UINT if no replacement was needed, and therefore the length of the input array could be used.

    • replaceMultiple

      public static char @NonNull [] replaceMultiple(@Nullable String sInputString, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings)
      Optimized replace method that replaces a set of characters with a set of strings. This method was created for efficient XML special character replacements!
      Parameters:
      sInputString - The input string.
      aSearchChars - The characters to replace.
      aReplacementStrings - The new strings to be inserted instead. Must have the same array length as aPatterns.
      Returns:
      The replaced version of the string or an empty char array if the input string was null.

    • replaceMultiple

      public static char @NonNull [] replaceMultiple(char @Nullable [] aInput, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings)
      Optimized replace method that replaces a set of characters with a set of strings. This method was created for efficient XML special character replacements!
      Parameters:
      aInput - The input string.
      aSearchChars - The characters to replace.
      aReplacementStrings - The new strings to be inserted instead. Must have the same array length as aPatterns.
      Returns:
      The replaced version of the string or an empty char array if the input string was null.

    • replaceMultipleTo

      @Nonnegative public static int replaceMultipleTo(@Nullable String sInputString, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings, @NonNull Writer aTarget) throws IOException
      Specialized version of replaceMultiple(String, char[], char[][]) where the object where the output should be appended is passed in as a parameter. This has the advantage, that not length calculation needs to take place!
      Parameters:
      sInputString - The input string.
      aSearchChars - The characters to replace.
      aReplacementStrings - The new strings to be inserted instead. Must have the same array length as aPatterns.
      aTarget - Where the replaced objects should be written to. May not be null.
      Returns:
      The number of replacements performed. Always ≥ 0.
      Throws:
      IOException - In case writing to the Writer fails

    • replaceMultipleTo

      @Nonnegative public static int replaceMultipleTo(char @Nullable [] aInput, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings, @NonNull Writer aTarget) throws IOException
      Specialized version of replaceMultiple(String, char[], char[][]) where the object where the output should be appended is passed in as a parameter. This has the advantage, that not length calculation needs to take place!
      Parameters:
      aInput - The input char array. May not be null.
      aSearchChars - The characters to replace.
      aReplacementStrings - The new strings to be inserted instead. Must have the same array length as aPatterns.
      aTarget - Where the replaced objects should be written to. May not be null.
      Returns:
      The number of replacements performed. Always ≥ 0.
      Throws:
      IOException - In case writing to the Writer fails

    • replaceMultipleTo

      @Nonnegative public static int replaceMultipleTo(char @Nullable [] aInput, @Nonnegative int nOfs, @Nonnegative int nLen, char @NonNull [] aSearchChars, char[] @NonNull [] aReplacementStrings, @NonNull Writer aTarget) throws IOException
      Specialized version of replaceMultiple(String, char[], char[][]) where the object where the output should be appended is passed in as a parameter. This has the advantage, that not length calculation needs to take place!
      Parameters:
      aInput - The input char array. May be null.
      nOfs - Offset into input array. Must be ≥ 0.
      nLen - Number of characters from input array. Must be ≥ 0.
      aSearchChars - The characters to replace.
      aReplacementStrings - The new strings to be inserted instead. Must have the same array length as aPatterns.
      aTarget - Where the replaced objects should be written to. May not be null.
      Returns:
      The number of replacements performed. Always ≥ 0.
      Throws:
      IOException - In case writing to the Writer fails

    • replaceMultiple

      public static char @NonNull [] replaceMultiple(@Nullable String sInputString, char @NonNull [] aSearchChars, char cReplacementChar)
      Optimized replace method that replaces a set of characters with another character. This method was created for efficient unsafe character replacements!
      Parameters:
      sInputString - The input string.
      aSearchChars - The characters to replace.
      cReplacementChar - The new char to be used instead of the search chars.
      Returns:
      The replaced version of the string or an empty char array if the input string was null.

    • replaceMultipleTo

      public static void replaceMultipleTo(@Nullable String sInputString, char @NonNull [] aSearchChars, char cReplacementChar, @NonNull StringBuilder aTarget)
      Optimized replace method that replaces a set of characters with another character. This method was created for efficient unsafe character replacements!
      Parameters:
      sInputString - The input string.
      aSearchChars - The characters to replace.
      cReplacementChar - The new char to be used instead of the search chars.
      aTarget - The target StringBuilder to write the result to. May not be null.

    • replaceMultipleTo

      public static void replaceMultipleTo(@Nullable String sInputString, char @NonNull [] aSearchChars, char cReplacementChar, @NonNull Writer aTarget) throws IOException
      Optimized replace method that replaces a set of characters with another character. This method was created for efficient unsafe character replacements!
      Parameters:
      sInputString - The input string.
      aSearchChars - The characters to replace.
      cReplacementChar - The new char to be used instead of the search chars.
      aTarget - The target writer to write the result to. May not be null.
      Throws:
      IOException - in case writing to the Writer fails
      Since:
      8.6.3

    • replaceMultipleAsString

      public static @NonNull String replaceMultipleAsString(@Nullable String sInputString, char @NonNull [] aSearchChars, char cReplacementChar)
      Optimized replace method that replaces a set of characters with another character. This method was created for efficient unsafe character replacements!
      Parameters:
      sInputString - The input string.
      aSearchChars - The characters to replace.
      cReplacementChar - The new char to be used instead of the search chars.
      Returns:
      The replaced version of the string or an empty char array if the input string was null.
      Since:
      8.6.3

    • replaceMultiple

      public static @Nullable String replaceMultiple(@Nullable String sInputString, @Nullable Map<String,String> aTransTable)
      Perform all string replacements on the input string as defined by the passed map. All replacements are done using replaceAll(String,String,CharSequence) which is ok.
      Parameters:
      sInputString - The input string where the text should be replaced. May be null.
      aTransTable - The map with the replacements to execute. If null is passed, the input string is not altered.
      Returns:
      null if the input string was null.

    • replaceMultiple

      public static @Nullable String replaceMultiple(@Nullable String sInputString, @Nullable String[] aSearchTexts, @Nullable String[] aReplacementTexts)
      Perform all string replacements on the input string as defined by the passed map. All replacements are done using replaceAll(String,String,CharSequence) which is ok.
      Parameters:
      sInputString - The input string where the text should be replaced. May be null.
      aSearchTexts - The texts to be searched. If null is passed, the input string is not altered.
      aReplacementTexts - The texts to be used as the replacements. This array must have exactly the same number of elements than the searched texts! If null is passed, the input string is not altered.
      Returns:
      null if the input string was null. The unmodified input string if no search/replace patterns where provided.