Package Torello.Java

Class StrReplace

  • public class StrReplace
extends java.lang.Object
    An efficient way to replace multiple substring's, or single-characters, inside of a single Java String, in place, without rebuilding the returned String more than once.

    This class allows for a bulk-replace of all instances of a particular list of String's (as sub-strings) to be quickly, and efficiently, replaced using either a parallel array, or a java.util.function.Function to retrieve the replacement characters or String's.

    IMPORTANT:
    This class is in no way designed to replace the utility of Regular-Expressions. Repacing text inside of String's using Regular-Expressions will most often work very well. The methods provided here are designed efficiently because new String instances are only constructed once , in every one of these replacers.

    If there exists a direct mapping from one sub-string to another, these methods will run faster than Regular-Expressions, mainly because they have been optimized for finding the user-provided matches quickly. Regular-Expressions can be unwieldy, since they're intended as a general-purpose tool.



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.
    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 18 Method(s), 18 declared static
    • 0 Field(s)


    • Method Summary

       
      Replace Match-Chars
      Modifier and Type Method
      static String r​(char[] matchChars, ToCharIntCharFunc replaceFunction, String s)
      static String r​(String s, char[] matchChars, char[] replaceChars)
      static String r​(String s, char[] matchChars, String[] replaceStrs)
      static String r​(String s, char[] matchChars, IntCharFunction<String> replaceFunction)
       
      Replace Match-Chars, Case-Insensitive
      Modifier and Type Method
      static String r​(boolean ignoreCase, String s, char[] matchChars, char[] replaceChars)
      static String r​(boolean ignoreCase, String s, char[] matchChars, String[] replaceStrs)
      static String r​(boolean ignoreCase, String s, char[] matchChars, IntCharFunction<String> replaceFunction)
      static String r​(String s, boolean ignoreCase, char[] matchChars, ToCharIntCharFunc replaceFunction)
       
      Replace Match-Strings
      Modifier and Type Method
      static String r​(String s, String[] matchStrs, char[] replaceChars)
      static String r​(String s, String[] matchStrs, String[] replaceStrs)
      static String r​(String s, String[] matchStrs, IntTFunction<String,​String> replaceFunction)
      static String r​(String s, ToCharIntTFunc<String> replaceFunction, String[] matchStrs)
       
      Replace Match-Strings, Case-Insensitive
      Modifier and Type Method
      static String r​(boolean ignoreCase, String s, String[] matchStrs, char[] replaceChars)
      static String r​(boolean ignoreCase, String s, String[] matchStrs, String[] replaceStrs)
      static String r​(boolean ignoreCase, String s, String[] matchStrs, IntTFunction<String,​String> replaceFunction)
      static String r​(String s, boolean ignoreCase, String[] matchStrs, ToCharIntTFunc<String> replaceFunction)
       
      Pre-Pend a Character
      Modifier and Type Method
      static String r​(boolean ignoreCase, String s, char[] matchChars, char prependChar)
      static String r​(String s, char[] matchChars, char prependChar)

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • r

        🡇  ⇈  ⮫ 
        public static java.lang.String r​(java.lang.String s,
                                 java.lang.String[] matchStrs,
                                 java.lang.String[] replaceStrs)
        Convenience Method
        Case-Sensitive
        Invokes: r(boolean, String, String[], String[])
        Code:
        Exact Method Body:
         return r(false, s, matchStrs, replaceStrs);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​(boolean ignoreCase,
                                 java.lang.String s,
                                 java.lang.String[] matchStrs,
                                 java.lang.String[] replaceStrs)
        This shall replace each instance of the elements of parameter 'matchStrs' in input String 's' with the elements of parallel array 'replaceStrs'
        Parameters:
        ignoreCase - When this parameter is set to TRUE, then the comparisons that determine whether a match has occurred shall ignore the case of the characters involved.
        s - This may be any Java String.
        matchStrs - This is a String[] array that should hold some sub-strings of input parameter 's'. This method shall search 's' - left to right - for any instances of the list of 'matchStrs' and replace those sub-strings with whatever String is in the same array-index location (parallel-array) from input parameter 'replaceStrs'

        MULTIPLE-MATCH SCENARIOS: If there are substring's within parameter 'matchStrs' such that the loop-iterations of this method could select multiple, different String's as a substring match with the input parameter 's', then the loops will always replace the first match found with input String[] array parameter 'matchStrs'.

        Example:
         String[] matches         = { "Bell", "Belle", "Belleview" };
 String[] replacements    = { "Ring", "Flower", "Microsoft Corporate HQ" };
 String   theString       = "Microsoft Corporate Apartments are in Belleview, Washington";

 System.out.println(StrReplace.r(false, theString, matches, replacements));

 // Would print to terminal:
 // Microsoft Corporate Apartments are in Ringeview, Washington
 
 // This is because the point when the "Replace Loop" cursor reaches character 'B' in
 // 'Bellview', the first match it finds with parameter 'matches' is the String "Bell"
 // ... And because the 'replacements' parameter maps the word "Bell" to "Ring"
        replaceStrs - This is also an String[] array that should hold sub-strings. Every time a copy of any 'matchStr' is found within 's', the index of the sub-string match from 'matchStrs' shall be used to lookup the parallel 'replaceStr', and used to over-write or replace that sub-string inside 's'.

        PARALLEL ARRAY: This array should be considered parallel to input String[] array 'matchStrs'. It provides a replacement mapping. It is required to be the exact same length as array 'matchStrs', or an exception shall throw.
        Returns:
        This shall return a new-String where the replacements that were requested have been substituted.
        Throws:
        java.lang.NullPointerException - If any of the String's inside the String[] arrays contain null pointers.
        ParallelArrayException - If the length of array matchStrs does not equal the length of array replaceStrs, then this exception shall throw. This is because these arrays are intended to be parallel arrays, where the references in the second array are supposed to be used to replace sub-strings (in 's') from the first array.
        Code:
        Exact Method Body:
         // Make sure these arrays are parallel, and if not throw ParallelArrayException
 // If there are any 'null' values in these arrays, throw NullPointerException

 ParallelArrayException.check
     (matchStrs, "matchStrs", true, replaceStrs, "replaceStrs", true);

 // Java Stream's shall keep records of where and which the matches occurred
 IntStream.Builder   whereB  = IntStream.builder();
 IntStream.Builder   whichB  = IntStream.builder();
 int                 delta   = 0;

 // This part of the code finds the locations of all the matches in the input string.
 // It does not build the new String, but rather, finds indexes first.  This way a
 // char[] array can be built, and then populated with the updated sub-strings.

 TOP:
 for (int i=0; i < s.length(); i++)

     for (int j=0; j < matchStrs.length; j++)

         if (s.regionMatches(ignoreCase, i, matchStrs[j], 0, matchStrs[j].length()))
         {
             // Save the "original String index" of WHERE the match occurred
             whereB.accept(i);

             // Save the "match index" of WHICH match has occurred
             whichB.accept(j);

             // Keep a record of the 'delta' - which is the change in size of the 
             // output/returned String
             delta = delta - matchStrs[j].length() + replaceStrs[j].length();
                    
             // Make sure to advance the index-pointer, skip the most recent match
             i += matchStrs[j].length() - 1;
                    
             continue TOP;
         }

 // List of indices into the input-String for WHERE matches occurred.
 int[] whereArr = whereB.build().toArray();

 // List of indices into the match-array for WHICH matches occurred.
 int[] whichArr = whichB.build().toArray();

 // The new "Char Array" which will be built into a String.  The "change in size" was
 // computed earlier
 char[] cArr = new char[s.length() + delta];


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // If there were no matches, return the original string
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 if (whereArr.length == 0) return s;


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // "Pre-Loop Priming Update" or "Priming Read"
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 // This just copies the first non-matching sub-string portion to the cArr[]
 s.getChars(0, whereArr[0], cArr, 0);

 // These are the loop-control variables
 int oldStrPos   = whereArr[0];
 int newStrPos   = whereArr[0];
 int i           = 0;

 while (i < whichArr.length)
 {
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // Copy the next match from the "Replacement Strings Array"
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     String  replaceStr  = replaceStrs[whichArr[i]];

     replaceStr.getChars(0, replaceStr.length(), cArr, newStrPos);

     // Advance the pointers
     newStrPos += replaceStr.length();
     oldStrPos += matchStrs[whichArr[i]].length();
     i++;

     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // Copy the next non-matching sub-string section from the "Old Input String"
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     int end = (i < whichArr.length) ? whereArr[i] : s.length();
     s.getChars(oldStrPos, end, cArr, newStrPos);

     // Advance the pointers
     newStrPos += (end - oldStrPos);
     oldStrPos = end;
 }

 // Convert the character array into a String
 return new String(cArr);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​
            (java.lang.String s,
             java.lang.String[] matchStrs,
             IntTFunction<java.lang.String,​java.lang.String> replaceFunction)
        Convenience Method
        Case-Sensitive
        Invokes: r(boolean, String, String[], IntTFunction)
        Code:
        Exact Method Body:
         return r(false, s, matchStrs, replaceFunction);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​
            (boolean ignoreCase,
             java.lang.String s,
             java.lang.String[] matchStrs,
             IntTFunction<java.lang.String,​java.lang.String> replaceFunction)
        This shall replace each instance of the elements of parameter 'matchStrs' in input String 's' with the String-value returned by the 'replaceFunction' lambda-method / functional-interface.
        Parameters:
        ignoreCase - When this parameter is set to TRUE, then the comparisons that determine whether a match has occurred shall ignore the case of the characters involved.
        s - This may be any Java String.
        matchStrs - This is an String[] array that should hold some sub-strings of input parameter 's'. This method shall search 's' - left to right - for any instances of the list of 'matchStrs' and replace those sub-strings with whatever String is returned by the 'replaceFunction'.

        MULTIPLE-MATCH SCENARIOS: If there are substring's within parameter 'matchStrs' such that the loop-iterations of this method could select multiple, different String's as a substring match with the input parameter 's', then the loops will always replace the first match found with input String[] array parameter 'matchStrs'.

        Example:
         String[] matches         = { "Bell", "Belle", "Belleview" };
 String   theString       = "Microsoft Corporate Apartments are in Belleview, Washington";

 System.out.println
     (StrReplace.r(false, theString, matches, (int i, String s) -> s.toUpperCase()));

 // Would print to terminal:
 // Microsoft Corporate Apartments are in BELLeview, Washington
 
 // This is because the point when the "Replace Loop" cursor reaches character 'B' in
 // 'Bellview', the first match it finds with parameter 'matches' is the String "Bell"
 // ... And because the 'replaceFunction' parameter merely asks the match-String be
 //     converted to upper-case.
        replaceFunction - This shall receive as input a Java String that has matched one of the String's that are within 'matchStrs', along with the String-index into the String where that match occured. It must reply with a replacement String (to replace that sub-string within the input String parameter 's')

        LOOK-AROUND: The replaceFunction parameter here include both the matched String, and the index to the first character-position of that match. This means that the function-pointer or lambda you provide here has the ability to 'look ahead' (or behind) into the input-String before returning a String-replacement.
        Returns:
        This shall return a new-String where the replacements that were requested have been substituted.
        Throws:
        java.lang.NullPointerException - If any of the String's inside the String[] arrays contain null pointers.
        Code:
        Exact Method Body:
         // Loop simply checks for null pointers.
 for (int i=0; i < matchStrs.length; i++)

     if (matchStrs[i] == null) throw new NullPointerException(
         "The " + i + StringParse.ordinalIndicator(i) + " of array parameter " +
         "'matchStrs' is null."
     );

 // Use a StringBuilder to build the return String.  It is precisely what it was
 // it was designed for.

 StringBuilder sb = new StringBuilder();

 int last = 0;

 // Main Loop: Builds a replacement StringBuilder.  Looks for matches between the input
 // String 's', and the matchStrs in array String[] matchStrs.

 TOP:
 for (int i=0; i < s.length(); i++)

     for (int j=0; j < matchStrs.length; j++)

         if (s.regionMatches(ignoreCase, i, matchStrs[j], 0, matchStrs[j].length()))
         {
             // A match was found, so begin
             String nonMatchStr  = s.substring(last, i);
             String oldStr       = s.substring(i, i + matchStrs[j].length());
             String newStr       = replaceFunction.apply(i, oldStr);

             // Append them to the StringBuilder.
             if (nonMatchStr.length() > 0) sb.append(nonMatchStr);
             sb.append(newStr);

             // Update the pointers
             last    = i + oldStr.length();
             i       = last - 1; // use -1 because of the loop-incrementer at top

             continue TOP;
         }

 if (last == 0) return s; // There were no matches, return original String.

 // This happens when there are remaining characters after the last match that occurred.
 // Same as the HTML Parser - trailing READ/PARSE.

 if (last < s.length()) sb.append(s.substring(last));

 return sb.toString();

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​
            (java.lang.String s,
             boolean ignoreCase,
             java.lang.String[] matchStrs,
             ToCharIntTFunc<java.lang.String> replaceFunction)
        This shall replace each instance of the elements of parameter 'matchStrs' in input String 's' with the char-value returned by the 'replaceFunction' lambda-method / functional-interface.

        Example:
         String[] matches    = { "&Pi;", "&Rho;", "&Sigma;", "&Tau;", "&Upsilon;", "&Phi;" };
 String   theString  = "Greek: &Pi;, &Rho;, &Sigma;, &Tau;, &Upsilon;, &Phi;";
 
 System.out.println
     (StrReplace.r(theString, false, matches, (int i, String s) -> Escape.escHTMLToChar(s)));

 // Would print to terminal:
 // Greek: Π, Ρ, Σ, Τ, Υ, Φ
        Parameters:
        s - This may be any Java String.
        ignoreCase - When this parameter is set to TRUE, then the comparisons that determine whether a match has occurred shall ignore the case of the characters involved.
        matchStrs - This is an String[] array that should hold some sub-strings of input parameter 's'. This method shall search 's' - left to right - for any instances of the list of 'matchStrs' and replace those sub-strings with whatever char is returned by the 'replaceFunction' for that given match-String;

        MULTIPLE-MATCH SCENARIOS: If there are multiple copies (either ignoring case, or not ignoring case), of an identical String put into String[] array parameter 'matchStrs', this method will not generate an exception (or anything like that) in such scenarios.

        It is important to note that when invoking the replaceFunction's method apply(String), the String that is provided to apply will be the exact substring found in the original-String.
        replaceFunction - This shall receive as input a Java String that has matched one of the String's that are within 'matchStrs', along with the String-index into the String where that match occured. It must reply with a replacement 'char' (which will replace that matched sub-string found within 's').

        LOOK-AROUND: The replaceFunction parameter here include both the matched String, and the index to the first character-position of that match. This means that the function-pointer or lambda you provide here has the ability to 'look ahead' (or behind) into the input-String before returning a char-replacement.
        Returns:
        This shall return a new-String where the replacements that were requested have been substituted.
        Throws:
        java.lang.NullPointerException - If any of the String's inside the String[] arrays contain null pointers.
        Code:
        Exact Method Body:
         // Loop simply checks for null pointers.
 for (int i=0; i < matchStrs.length; i++)

     if (matchStrs[i] == null) throw new NullPointerException(
         "The " + i + StringParse.ordinalIndicator(i) + " of array parameter " +
         "'matchStrs' is null."
     );

 // NOTE: This builder used to save the indices where matches are found.
 //
 // The IntStream that we are building will be "interleaved" in the sense that each integer
 // in an *EVEN* location in the output array shall represent the starting-index of a 
 // sub-string match, and the *ODD* integer (the one that immediately follows it) represents
 // the ending-index of a sub-string match.

 IntStream.Builder b = IntStream.builder();

 // This is used to keep track of the size-change of the output string
 int delta = 0;

 // Main Loop: Builds a replacement StringBuilder.  Looks for matches between the input
 // String 's', and the matchStrs in array String[] matchStrs.

 TOP:
 for (int i=0; i < s.length(); i++)

     for (int j=0; j < matchStrs.length; j++)

         if (s.regionMatches(ignoreCase, i, matchStrs[j], 0, matchStrs[j].length()))
         {
             // SEE NOTE ABOVE: When a match is found, the starting-index of the 
             // substring match is appended to the IntStream, then IMMEDIATELY AFTERWARDS
             // the ending-index of the substring match is appended.

             int len = matchStrs[j].length();
             b.accept(i);
             b.accept(i + len);

             // The change in size of the output String is precisely the length of the
             // match minus 1.  A substring is being replaced by a character.

             delta += (len - 1);

             // A Match was found, so skip to the next location.  Move past the match
             // that was just identified.
             i += (len -1);

             continue TOP;
         }
        
 // Keeps track of all the locations in the original string where matches occurred.
 int[] whereArr = b.build().toArray();

 // If there were no matches, return the original String
 if (whereArr.length == 0) return s;

 // The output string will be stored here.
 char[] cArr = new char[s.length() - delta];

 // These are the array indices of both arrays, and the original string
 int i           = 0;    // Match-String Location Pointer Array
 int oldStrPos   = 0;    // Pointer to Input-String index
 int newStrPos   = 0;    // Pointer to Output Char-Array index

 // Iterate and replace the substrings.
 while (i < whereArr.length)
 {
     if (oldStrPos == whereArr[i])
     {
         // Ask the "Replace Function" for the replacement character for the matched
         // substring
         //
         // NOTE: Each *EVEN* location in the whereArr contains a start-index, and the
         //       *ODD* location immediately following contains an end-index.  These
         //       start-end pair identify the substring matches that were found.
         //
         // NOW:  Grab that substring, and pass it to the parameter-provided (user
         //       provided)  "replaceFunction" which informs this method what character
         //       to use when replacing a substring

         cArr[newStrPos++] = replaceFunction.apply
             (whereArr[i], s.substring(whereArr[i], whereArr[i+1]));

         // Advance the "pointers" (advance the array indices)
         //
         // The pointer to the "source array" (a.k.a. the "original array") should be
         // advanced to the location of the end of the match we just found.  That end
         // was pointed at by the start-end *PAIR* whereArr[i] ... whereArr[i+1].
         //
         // NOTE: the substring match is "exclusive of" the actual character
         //       located at whereArr[i+1].  Specifically, in the original string, there
         //       was a sub-string match to replace with a single character that began
         //       at original-string index/location whereArr[i] and continuing to 
         //       index/location (whereArr[i+1]-1)
         //
         //       Java's java.lang.String.subtring(star, end) is *ALWAYS* exclusive of
         //       the character located at 'end'

         oldStrPos = whereArr[i+1];

         // Skip the "pair" (starting-index and ending-index).   Note that at the end
         // of the loop, variable 'i' shall *ALWAYS* be an even-number.
         i += 2;
     }

     else cArr[newStrPos++] = s.charAt(oldStrPos++);
 }

 // Just like in HTMLNode Parse, the trailing ("tail") of characters after the final
 // match in the String need to be appended to the output char[] array.  These are
 // "missed" or "skipped" by the above replacement loop.  (Similar to a "trailing read")

 while (newStrPos < cArr.length) cArr[newStrPos++] = s.charAt(oldStrPos++);

 // AGAIN: All of the replacements where done on a "char[] array".  Convert that array
 //        to an actual String, and return it to the user.

 return new String(cArr);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​(java.lang.String s,
                                 java.lang.String[] matchStrs,
                                 char[] replaceChars)
        Convenience Method
        Case-Sensitive
        Invokes: r(boolean, String, String[], char[])
        Code:
        Exact Method Body:
         return r(false, s, matchStrs, replaceChars);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​(boolean ignoreCase,
                                 java.lang.String s,
                                 java.lang.String[] matchStrs,
                                 char[] replaceChars)
        This shall replace each instance of the elements of parameter 'matchStrs' in input String 's' with the provided characters in parallel array 'replaceChars'.

        Example:
         String[]  matches       = { "&Pi;", "&Rho;", "&Sigma;", "&Tau;", "&Upsilon;", "&Phi;" };
 char[]    replacements  = { 'Π', 'Ρ', 'Σ', 'Τ', 'Υ', 'Φ'  };
 String    theString     = "Greek Letters: &Pi;, &Rho;, &Sigma;, &Tau;, &Upsilon;, &Phi;";
 
 System.out.println(StrReplace.r(false, theString, matches, replacements);

 // Would print to terminal the following String:
 // Greek Letters: Π, Ρ, Σ, Τ, Υ, Φ
        Parameters:
        s - This may be any Java String.
        ignoreCase - When this parameter is set to TRUE, then the comparisons that determine whether a match has occurred shall ignore the case of the characters involved.
        matchStrs - This is a String[] array that should hold some sub-strings of input parameter 's'. This method shall search 's' - left to right - for any instances of the list of 'matchStrs' and replace those sub-strings with whatever char is in the same array-index location (parallel-array) from input parameter 'replaceChars'.

        MULTIPLE-MATCH SCENARIOS: If there are substring's within parameter 'matchStrs' such that the loop-iterations of this method could select multiple, different String's as a substring match with the input parameter 's', then the loops will always replace the first match found with input String[] array parameter 'matchStrs'.
        replaceChars - This is also a char[] array. Every time a copy of any of the 'matchStrs' is found within 's', the index of the String match from 'matchStrs' shall be used to lookup the parallel 'replaceChar', and used to over-write or replace that character inside 's'.

        PARALLEL ARRAY: This array should be considered parallel to input char[] array 'matchStrs'. It provides a replacement mapping. It is required to be the exact same length as array 'matchChars', or an exception shall throw.
        Returns:
        This shall return a new-String where the replacements that were requested have been substituted.
        Throws:
        java.lang.NullPointerException - If any of the String's inside the String[] matchStrs are null pointers.
        ParallelArrayException - If the arrays matchStrs and replaceChars are not identical lengths. These arrays must be parallel
        Code:
        Exact Method Body:
         // Check that these arrays are parallel, and if not, throw ParallelArrayException
 // If 'matchStr' has a null, throw NullPointerException

 ParallelArrayException.check
     (matchStrs, "matchStrs", true, replaceChars, "replaceChars");

 // The first stream is used to save the indices where matches are found.
 // The second stream is used to save WHICH MATCH has occurred, in order to retrieve the
 // replacement character.
 //
 // NOTE: This builder used to save the indices where matches are found.
 //
 // The IntStream that we are building will be "interleaved" in the sense that each integer
 // in an *EVEN* location in the output array shall represent the starting-index of a 
 // sub-string match, and the *ODD* integer (the one that immediately follows it) represents
 // the ending-index of a sub-string match.

 IntStream.Builder whereB = IntStream.builder();

 // This is saving which match occurred
 IntStream.Builder whichB = IntStream.builder();

 // This is used to keep track of the size-change of the output string
 int delta = 0;

 // Main Loop: Builds a replacement StringBuilder.  Looks for matches between the input
 // String 's', and the matchStrs in array String[] matchStrs.

 TOP:
 for (int i=0; i < s.length(); i++)

     for (int j=0; j < matchStrs.length; j++)

         if (s.regionMatches(ignoreCase, i, matchStrs[j], 0, matchStrs[j].length()))
         {
             // SEE NOTE ABOVE: When a match is found, the starting-index of the 
             // substring match is appended to the IntStream, then IMMEDIATELY AFTERWARDS
             // the ending-index of the substring match is appended.

             int len = matchStrs[j].length();

             whereB.accept(i);
             whereB.accept(i + len);

             // The second IntStream shall store WHICH MATCH has occurred.  The match that
             // occurred is identified by an array-index into the "replaceChars" char[] array
             // that was provided by the user to this method through the parameter list at
             // the top of this.

             whichB.accept(j);

             // The change in size of the output String is precisely the length of the
             // match minus 1.  A substring is being replaced by a character.

             delta += (len - 1);

             // A Match was found, so skip to the next location.  Move past the match
             // that was just identified.
             i += (len -1);
             continue TOP;
         }
        
 // Keeps track of all the locations in the original string where matches occurred.
 int[] whereArr = whereB.build().toArray();
 int[] whichArr = whichB.build().toArray();

 // If there were no matches, return the original String
 if (whichArr.length == 0) return s;

 // The output string will be stored here.
 char[] cArr = new char[s.length() - delta];

 // These are the array indices of both arrays, and the original string
 int i           = 0;    // Index into Match-String Location Pointer Array 
 int oldStrPos   = 0;    // Pointer / index into Input-String
 int newStrPos   = 0;    // Pointer / index into Output Char-Array
 int rArrPos     = 0;    // Pointer / index into Replace Characters Char-Array

 // Iterate and replace the substrings.
 while (i < whereArr.length)
 {
     if (oldStrPos == whereArr[i])
     {
         // Retrieve the replacement character from the 'replaceChars' array.
         // The *CORRECT INDEX* from the replacement-char array is the next location
         // in the whichArr... And *THIS INDEX* is called 'rArrPos'
         // NOTE: Good Variable Names became uncompromisingly difficult here. 

         cArr[newStrPos++] = replaceChars[whichArr[rArrPos++]];

         // Advance the "pointers" (advance the array indices)
         //
         // The pointer to the "source array" (a.k.a. the "original array") should be
         // advanced to the location of the end of the match we just found.  That end
         // was pointed at by the start-end *PAIR* whereArr[i] ... whereArr[i+1].
         //
         // NOTE: the substring match is "exclusive of" the actual character
         //       located at whereArr[i+1].  Specifically, in the original string, there
         //       was a sub-string match to replace with a single character that began
         //       at original-string index/location whereArr[i] and continuing to 
         //       index/location (whereArr[i+1]-1)
         //
         //       Java's java.lang.String.subtring(star, end) is *ALWAYs* exclusive of
         //       the character located at 'end'
        
         oldStrPos = whereArr[i+1];

         // Skip the "pair" (starting-index and ending-index).   Note that at the end
         // of the loop, variable 'i' shall *ALWAYS* be an even-number.

         i += 2;
     }

     else cArr[newStrPos++] = s.charAt(oldStrPos++);
 }

 // Just like in HTMLNode Parse, the trailing ("tail") of characters after the final
 // match in the String need to be append to the output char[] array.  These are "missed"
 // or "skipped" by the above replacement loop.  (Similar to a "trailing read")
 //
 // OLD CODE - REPLACED WITH LINE BELOW
 // while (newStrPos < cArr.length) cArr[newStrPos++] = s.charAt(oldStrPos++);

 s.getChars(oldStrPos, s.length(), cArr, newStrPos);

 // Convert the character array into a String
 return new String(cArr);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​(java.lang.String s,
                                 char[] matchChars,
                                 java.lang.String[] replaceStrs)
        Convenience Method
        Case-Sensitive
        Invokes: r(boolean, String, char[], String[])
        Code:
        Exact Method Body:
         return r(false, s, matchChars, replaceStrs);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​(boolean ignoreCase,
                                 java.lang.String s,
                                 char[] matchChars,
                                 java.lang.String[] replaceStrs)
        This shall replace each instance of the characters of parameter 'matchStrs' in input String 's' with the String's of parallel array 'replaceStrs'.
        Parameters:
        ignoreCase - When this parameter is set to TRUE, then the comparisons that determine whether a match has occurred shall ignore the case of the characters involved.
        s - This may be any Java String.
        matchChars - This is a char[] array that should hold some set of characters which are expected to be contained within the input parameter 's'. This method shall search 's' - left to right - for any instances of the list of 'matchChars' and replace those characters with whatever String is in the same array-index location (parallel-array) from input parameter 'replaceStrs'

        MULTIPLE-MATCH SCENARIOS: If there are multiple copies of an the exact same character in input parameter 'matchChars', this should be considered an error-case. The code in this method does not actually go into that level of error checking, and as such, if parameter 'matchChars' attempts to map the same char to more than one replacement-String, the loop will simply use the first-mapping found in 'replaceStrs' that is found. No exceptions will throw when presented with this type of input.

        ALSO: If an upper-case and lower-case version of the exact same character is provided in char[] array parameter 'matchChars', and the boolean flag parameter 'ignoreCase' were set to TRUE, whichever of the two characters (upper-case or lower-case) that occurs first in array parameter 'matchChars' would be used to provide a replacement-String from array parameter 'replaceStrs'
        replaceStrs - This is a String[] array that should hold sub-strings. Every time a copy of any of the 'matchChars' is found within 's', the index of the character match from 'matchChars' shall be used to lookup the parallel 'replaceStr', and used to over-write or replace that character inside 's'.

        PARALLEL ARRAY: This array should be considered parallel to input char[] array 'matchChars'. It provides a replacement mapping. It is required to be the exact same length as array 'matchChars', or an exception shall throw.
        Returns:
        This shall return a new-String where the replacements that were requested have been substituted.
        Throws:
        java.lang.NullPointerException - If any of the String's inside String[] replaceStrs are null.
        ParallelArrayException - If the length of array matchChars does not equal the length of array replaceStrs, then this exception shall throw. This is because these arrays are intended to be parallel arrays, where the references in the second array are supposed to be used to replace sub-strings (in 's') from the first array.
        Code:
        Exact Method Body:
         // Make sure these arrays are Parallel, and throw ParallelArrayException if not
 // If 'replaceStrs' contains null-values, throw NullPointerException

 ParallelArrayException.check
     (replaceStrs, "replaceStrs", true, matchChars, "matchChars");

 // If the case of the characters is being ignored, it is easier to just set them all
 // to lower-case right now.

 if (ignoreCase)
 {
     matchChars = matchChars.clone();
     for (int i=0; i < matchChars.length; i++)
         matchChars[i] = Character.toLowerCase(matchChars[i]);
 }
    
 // Java Stream's shall keep records of *WHERE* and *WHICH* the matches occurs
 IntStream.Builder   whereB  = IntStream.builder();
 IntStream.Builder   whichB  = IntStream.builder();
 int                 delta   = 0; // string length change

 // This part of the code finds the locations of all the matches in the input string.
 // It does not build the new String, but rather, finds indexes first.  This way a
 // char[] array can be built, and then populated with the updated sub-strings.

 TOP:
 for (int i=0; i < s.length(); i++)
 {
     char c = ignoreCase ? Character.toLowerCase(s.charAt(i)) : s.charAt(i);

     for (int j=0; j < matchChars.length; j++)

         if (c == matchChars[j])
         {
             // Save the "original String index" of WHERE the match occurred
             whereB.accept(i);

             // Save the "match index" of WHICH char-match has occurred
             whichB.accept(j);

             // Keep a record of the 'delta' - and this is the size of the string to insert.
             delta += replaceStrs[j].length() - 1;
                    
             continue TOP;
         }
 }

 // List of indices into the input-String for WHERE matches occurred.
 int[] whereArr = whereB.build().toArray();

 // List of indices into the match-array for WHICH matches occurred.
 int[] whichArr = whichB.build().toArray();

 // IMPORTANT: If no matches in input char[] array 'matchChars' were found or identified
 //            inside the input-string, return the original String immediately, with no
 //            changes!

 if (whereArr.length == 0) return s;

 // The new "Char Array" which will be built into a String.  The "change in size" 
 // was computed earlier

 char[]  cArr        = new char[s.length() + delta];

 // These are some loop-control variables
 int oldStrPos   = 0;
 int newStrPos   = 0;
 int matchNum    = 0;


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // "Pre-Loop Priming Update" or "PRIMING READ" - populates char array with replace-strings
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 // copies the first non-matching sub-string portion to the cArr[]
 if (whereArr[0] > 0)
 {
     s.getChars(0, whereArr[0], cArr, 0);

     // Advance the pointers
     newStrPos = oldStrPos = whereArr[0]; 
 }


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // Iterate through each of the matches
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

 while (matchNum < whichArr.length)
 {
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // Copy the next MATCHING char-substitute String from the "Replacement Strings Array"
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     String replaceStr = replaceStrs[whichArr[matchNum]];

     /*
         FROM: Java's JDK Documentation for java.lang.String

         public void getChars(   int srcBegin,
                                 int srcEnd,
                                 char[] dst,
                                 int dstBegin    )
                            
         Copies characters from this string into the destination character array.

         Parameters:
             srcBegin    - index of the first character in the string to copy.
             srcEnd      - index after the last character in the string to copy.
             dst         - the destination array.
             dstBegin    - the start offset in the destination array.

         // OLD CODE: 
         int len = replaceStr.length();
         for (int i=0; i < len; i++) cArr[newStrPos++] = replaceStr.charAt(i);

     */
     replaceStr.getChars(0, replaceStr.length(), cArr, newStrPos);

     // In the new (output) string (currently a char[]), we have added "len" characters
     newStrPos += replaceStr.length();

     // Since we are replacing a *SINGLE* character with a new (replacement) String,
     // the pointer to the source / old string is advanced by *ONLY* one.

     oldStrPos++;

     // This "index" is pointing to an array that is holding the match information.
     // Essentially, here, we are just moving on to the next match.  Therefore
     // increment by only 1.

     matchNum++;


     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
     // Copy the next NON-MATCHING PORTION sub-string from the "Old Input String"
     // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

     // Have We copied the entire string yet?
     if (oldStrPos < s.length())
     {
         int endCopyPos = (matchNum < whichArr.length) ? whereArr[matchNum] : s.length();

         s.getChars(oldStrPos, endCopyPos, cArr, newStrPos);

         // We have just copied (end - oldStrPos) characters to the new array, from the
         // old array.  Advance the newStrPos by this many characters.
         newStrPos += (endCopyPos - oldStrPos);

         // Advance the oldStr by the same number of character.  The line of code below
         // will be identical to this line of code: oldStrpos += (endCopyPos - oldStrPos);
         // Same as oldStrPos += (endCopyPos - oldStrPos) (Obviously!)
         oldStrPos = endCopyPos; 
     }
 }

 // Convert the char[] array (cArr) into a String, and return it.
 return new String(cArr);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​
            (boolean ignoreCase,
             java.lang.String s,
             char[] matchChars,
             IntCharFunction<java.lang.String> replaceFunction)
        This shall replace each instance of the characters of parameter 'matchStrs' in input String 's' with the String-value returned by the 'replaceFunction' lambda-method / functional-interface.

        Example:
         // THIS EXAMPLE SHOWS HOW THIS METHOD CAN BE USED WITH REGULAR-EXPRESSION PROCESSING.

 // These are (some / most) of the characters that would need to be 'escaped' to use
 // them for the actual characters they represent inside of a Regular-Expression Pattern.
 final char[] CHARS_TO_ESCAPE = { '*', '.', '[', ']', '(', ')', '+', '|', '?', ':' };

 // This method invocation uses a lambda-expression that simply "prepends" a forward
 // slash to whatever character is being replaced with a String.  This will "escape" any
 // punctuation in the text that needs to "bypass" the Regular-Expression Engine - meaning
 // that these symbols, when found inside the text, should not be interpreted as commands
 // to RegEx, but rather as plain old brackets, parenthesis, periods, etc...
 text = StrReplace.r(text, CHARS_TO_ESCAPE, (int i, char c) -> "\\" + c);
        Parameters:
        ignoreCase - When this parameter is set to TRUE, then the comparisons that determine whether a match has occurred shall ignore the case of the characters involved.
        s - This may be any Java String.
        matchChars - This is a char[] array that should hold some set of characters which are expected to be contained within the input parameter 's'. This method shall search 's' - left to right - for any instances of the list of 'matchChars' and replace those characters with the results from input functional-interface parameter 'replaceFunction'.
        replaceFunction - This shall receive any Java 'char' along with the index into String 's' where that 'char' is located. This function must reply with a replace-String. This shall be used to replace any instances of that character found inside the input String.

        LOOK-AROUND: The replaceFunction parameter here include both the matched char, and the index to the first character-position of that match. This means that the function-pointer or lambda you provide here has the ability to 'look ahead' (or behind) into the input-String before returning a String-replacement.
        Returns:
        This shall return a new-String where the replacements that were requested have been substituted.
        Code:
        Exact Method Body:
         // Use a StringBuilder.  It is easier since the 'Replace Function' is going to be
 // *GENERATING* a new String each and every time there is a match.  This is essentially
 // what class StringBuilder was deigned for.

 StringBuilder sb = new StringBuilder();

 // If the case of the characters is being ignored, it is easier to just set them all
 // to lower-case right now.

 if (ignoreCase)
 {
     matchChars = matchChars.clone();
     for (int i=0; i < matchChars.length; i++)
         matchChars[i] = Character.toLowerCase(matchChars[i]);
 }

 // IMPORTANT: This entire method is "The Easy Way"  Here, we are just reusing Java's
 //            StringBuilder class to build the String, piece-by-piece.  It is
 //            unknown whether this is less efficient than working with a char[] array

 TOP:
 for (int i=0; i < s.length(); i++)
 {
     char c = ignoreCase ? Character.toLowerCase(s.charAt(i)) : s.charAt(i);

     for (int j=0; j < matchChars.length; j++)

         if (c == matchChars[j])
         { 
             sb.append(replaceFunction.apply(i, c));
             continue TOP;
         }

     sb.append(s.charAt(i));
 }

 return sb.toString();

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​(java.lang.String s,
                                 char[] matchChars,
                                 char[] replaceChars)
        Convenience Method
        Case-Sensitive
        Invokes: r(boolean, String, char[], char[])
        Code:
        Exact Method Body:
         return r(false, s, matchChars, replaceChars);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​(boolean ignoreCase,
                                 java.lang.String s,
                                 char[] matchChars,
                                 char[] replaceChars)
        This shall replace any instance of any of the characters in array-parameter 'matchChars' with the character's provided in array-parameter 'replaceChars'.

        Example:
         // In this example, some of the Higher-Order UNICODE Punctuation Characters are replaced
 // With simple ASCII-Versions of similar punctuation symbols.  Occasionally, foreign
 // language news-sources will utilize these "Alternate Punctuation Symbols" in Asian
 // Language Texts.  Translating these documents necessitates converting these to simple
 // ASCII versions of the punctuation, for readability purposes.  (Since translated text
 // in English wouldn't need to use these symbols).

 char[] unicodeChars = { '〔', '〕', '〈', '〉', '《', '》', '「', '」', '〖', '〗', '【', '】' };
 char[] replacements = { '[',  ']',  '<', '>',  '\"', '\"', '[',  ']',  '{',  '}',  '<',  '>' };
 String theString    = "会议强调，制定出台《中国共产党中央委员会工作条例》";
 
 // Use this method to replace all instance of the mentioned UNICODE characters with 
 // standard punctuation.  Note, after replacing the punctuation, translation would occur
 // in the next step...
 System.out.println(StrReplace.r(theString, unicodeChars, replacements));
 
 // Prints:
 // 会议强调，制定出台"中国共产党中央委员会工作条例"
 // Which translates to:
 // The meeting emphasized the formulation and promulgation of the "Regulations on the Work
 // of the Central Committee of the Communist Party of China"
        Parameters:
        ignoreCase - When this parameter is set to TRUE, then the comparisons that determine whether a match has occurred shall ignore the case of the characters involved.
        s - This may be any valid Java String. It is expected to contain at least some of the characters that are listed in parameter 'matchChars'.
        matchChars - This is a char[] array that should hold some set of characters which are expected to be contained within the input parameter 's'. This method shall search 's' - left to right - for any instances of the list of 'matchChars' and replace those characters with whatever char is in the same array-index location (parallel-array) from input parameter 'replaceChars'

        MULTIPLE-MATCH SCENARIOS: If there are multiple copies of an the exact same character in input parameter 'matchChars', this should be considered an error-case. The code in this method does not actually go into that level of error checking, and as such, if parameter 'matchChars' attempts to map the same char to more than one replacement-char, the loop will simply use the first-mapping found in 'replaceStrs' that is found. No exceptions will throw when presented with this type of input.
        replaceChars - This is also a char[] array. Every time a copy of any of the 'matchChars' is found within 's', the index of the character match from 'matchChars' shall be used to lookup the parallel 'replaceChar', and used to over-write or replace that character inside 's'.

        PARALLEL ARRAY: This array should be considered parallel to input char[] array 'matchChars'. It provides a replacement mapping. It is required to be the exact same length as array 'matchChars', or an exception shall throw.
        Returns:
        This shall return a copy of the input String, with all characters that matched the characters in 'matchChars', replaced by the characters in 'replaceChars'.
        Throws:
        ParallelArrayException - If the length of the 'matchChars' array is not equal to the length of the 'replaceChars' array.
        Code:
        Exact Method Body:
         // Make sure these arrays are of equal length
 ParallelArrayException.check(matchChars, "matchChars", replaceChars, "replaceChars");

 // The methods in this class all perform the replacements by first creating an
 // appropriately-sized output char[] array.  The last step of each of the methods is to
 // invoke the String constructor: new String(char[]) where a character array is converted
 // into a String.

 char[] cArr = s.toCharArray();

 if (ignoreCase)
 {
     char[] matchCharsLC = new char[matchChars.length];

     for (int i=0; i < matchChars.length; i++)
         matchCharsLC[i] = Character.toLowerCase(matchChars[i]);

     matchChars = matchCharsLC;
 }

 if (ignoreCase)

     TOP1:
     for (int i=0; i < cArr.length; i++)
     {
         char c = Character.toLowerCase(cArr[i]);

         for (int j=0; j < matchChars.length; j++)

             if (c == matchChars[j])
             {
                 cArr[i] = replaceChars[j];  // If a match was found, just replace it
                 continue TOP1;              // This method, really is THAT EASY.
             }
     }

 else

     TOP2:
     for (int i=0; i < cArr.length; i++)
     {
         char c = cArr[i];

         for (int j=0; j < matchChars.length; j++)

             if (c == matchChars[j])
             {
                 cArr[i] = replaceChars[j];  // If a match was found, just replace it
                 continue TOP2;              // This method, really is THAT EASY.
             }
     }

 // Convert the character array into a String
 return new String(cArr);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​(java.lang.String s,
                                 char[] matchChars,
                                 char prependChar)
        Convenience Method
        Case-Sensitive
        Invokes: r(boolean, String, char[], char)
        Code:
        Exact Method Body:
         return r(false, s, matchChars, prependChar);

      • r

        🡅  🡇  ⇈  ⮫ 
        public static java.lang.String r​(boolean ignoreCase,
                                 java.lang.String s,
                                 char[] matchChars,
                                 char prependChar)
        This shall "prepend" a specified / chosen character before each instance of a list of characters in an input-String. LAY-SPEAK: If, for example, the 'prependChar' provided were the back-slash character '\', then this method would insert a back-slash before each and every one of the 'matchChars' that it found inside 's'.

        This method is used to escape certain characters for things like regular expressions and javascript. Note the examples below. These two methods are provided in class StringParse. These methods are StringParse.escStrForRegEx(String), StringParse.escStrForJavaScript(String).

        Example:
         protected static final char[] JS_ESCAPE_CHARS = { '\\', '/', '\n', '\"' };
 
 // When using Java to build Java-Script "Strings", escape these characters
 public static String escStrForJavaScript(String str)
 { return StrReplace.r(str, JS_ESCAPE_CHARS, '\\'); }
 
 // This is a list of "control characters" for regular-expressions.  These characters
 // need to be escaped if they are expected to be taken literally, rather than as a control
 // character in regex.
 protected static final char[] REGEX_ESCAPE_CHARS =
 { '\\', '/', '(', ')', '[', ']', '{', '}', '$', '^', '+', '*', '?', '-', '.' };
 
 public static String escStrForRegEx(String str)
 { return StrReplace.r(str, REGEX_ESCAPE_CHARS, '\\'); }
        Parameters:
        ignoreCase - When this parameter is set to TRUE, then the comparisons that determine whether a match has occurred shall ignore the case of the characters involved.
        s - This may be any valid Java String. It is expected to contain at least some of the characters that are listed in parameter 'matchChars'.
        matchChars - This is a char[] array that should hold some set of characters which are expected to be contained within the input parameter 's'. This method shall search 's' - left to right - for any instances of the list of 'matchChars' and insert the character 'prependChar' directly before each match-character identified in String-parameter 's'.
        prependChar - This character will be inserted directly before each instance of matcChars-characters that are found within input String-parameter 's'
        Returns:
        This shall return a new String with the 'prependChar' before each instance of one of the 'matchChars' identified in the original String 's'.
        Code:
        Exact Method Body:
         // Need a temporary 'count' variable
 int count = 0;

 // Improve the loop counter efficiency, use a 'len' instead of s.length()
 int len = s.length();

 if (ignoreCase)
 {
     char[] matchCharsLC = new char[matchChars.length];

     for (int i=0; i < matchChars.length; i++)
         matchCharsLC[i] = Character.toLowerCase(matchChars[i]);

     matchChars = matchCharsLC;
 }

 // Use a Java Stream to save the locations of the matches
 IntStream.Builder whereB = IntStream.builder();

 // Count how many escape-characters are in the input-string
 if (ignoreCase)

     TOP1:
     for (int i=0; i < len; i++)
     {
         char c = Character.toLowerCase(s.charAt(i));

         // This checks if the character is a match with any of the match-characters in
         // the input array.

         for (char matchChar : matchChars)

             if (matchChar == c)
             {
                 whereB.accept(i);
                 continue TOP1;
             }
     }

 else

     TOP2:
     for (int i=0; i < len; i++)
     {
         char c = s.charAt(i);

         // This checks if the character is a match with any of the match-characters in
         // the input array.

         for (char matchChar : matchChars)

             if (matchChar == c)
             {
                 whereB.accept(i);
                 continue TOP2;
             }
     }

 // Build the java stream, and turn it into an index-pointer array (int array of
 // array indices)

 int[] whereArr = whereB.build().toArray();
    
 // No matches, return original string.
 if (whereArr.length == 0) return s;

 // The 'escaped string' will be longer than the original String by
 // 'whereArr.length' characters.  Use a character array to build this string

 char[] cArr = new char[len + whereArr.length];

 // There are now three different indices to keep up with - when doing this replace.
 // The input-string index.  The index of the "Match Locations Array" (whereArr), and the
 // index into the returned String - which, for now, is represented as a char[] array.

 int oldStrPos   = 0;
 int newStrPos   = 0;
 int i           = 0;

 while (oldStrPos < len)
 {
     // The next character in the input string
     char c = s.charAt(oldStrPos);

     // Was this one of the matches - as computed in the earlier loop?
     if (oldStrPos == whereArr[i])
     {
         // if "YES", then insert the prependChar, AND the original-string-char
         cArr[newStrPos++] = prependChar;
         cArr[newStrPos++] = c;

         // Here, increment the "Match Locations Array" index-location too.
         // (We have just "used up" one of the match-locations.
         i++;
     }
     else
         // if "NO", then just insert the original-string-char
         cArr[newStrPos++] = c;

     // Only at the end should we increment the input-string index-location.
     oldStrPos++;
 }

 // Convert the char array that was built into a String, and return it.
 return String.valueOf(cArr);

      • r

        🡅  ⇈  ⮫ 
        public static java.lang.String r​(java.lang.String s,
                                 boolean ignoreCase,
                                 char[] matchChars,
                                 ToCharIntCharFunc replaceFunction)
        This method shall receive a list of 'char', and then search the input String parameter 's' for any instances of the characters listed in 'matchChars' - and replace them. The replacement characters must be provided by the Functional-Interface Parameter 'replaceFunction'.

        The character-equality comparisons may be done in a case-insensitive manner, if requested (using the 'ignoreCase' parameter).
        Parameters:
        s - This may be any valid Java String. It is expected to contain at least some of the characters that are listed in parameter 'matchChars'.
        ignoreCase - If this parameter receives TRUE, then the equality comparisons between the input String 's', and 'matchChars' will be done on a case insensitive basis.
        matchChars - This is a char[] array that should hold some set of characters which are expected to be contained insiide the input parameter 's'. This method shall search 's' - left to right - for any instances of the list of 'matchChars' and replace those characters with ones returned by 'replaceFunction.apply(i, c);'. Note that, here, 'i' is the String-index where the 'matchChar' was found, and 'c' is the character that was matched.
        replaceFunction - This shall receive any Java 'char' along with the index into String 's' where that 'char' is located. This function must reply with a replace-char. This shall be used to replace instances of that character found inside the input String.

        LOOK-AROUND: The replaceFunction parameter here include both the matched char, and the index to the first character-position of that match. This means that the function-pointer or lambda you provide here has the ability to 'look ahead' (or behind) into the input-String before returning a char-replacement.
        Returns:
        A new String where any and all characters that were listed in 'matchChars' have been replaced by the return-values of 'replaceFunction'.
        Code:
        Exact Method Body:
         char[] cArr = s.toCharArray();

 if (ignoreCase)
 {
     // Make sure the 'var-args' are not changed.  We must resort to copying
     // the input 'matchChars' array.

     char[] tempArr = matchChars;
     matchChars = new char[tempArr.length];

     // Set them to lower-case, as they are copied.
     for (int i=0; i < matchChars.length; i++)
         matchChars[i] = Character.toLowerCase(tempArr[i]);

     // Do the replacement on a case-insensitive basis
     for (int i=0; i < cArr.length; i++)
     {
         char c = Character.toLowerCase(cArr[i]);

         for (int j=0; j < matchChars.length; j++)

             if (c == matchChars[j])
             {
                 cArr[i] = replaceFunction.apply(i, cArr[i]);
                 break;
             }
     }
 }
 else

     // Do the replacement, case-sensitive.
     for (int i=0; i < cArr.length; i++)
         for (int j=0; j < matchChars.length; j++)
             if (cArr[i] == matchChars[j])
             {
                 cArr[i] = replaceFunction.apply(i, cArr[i]);
                 break;
             }

 return new String(cArr);