Package Torello.Java

Class StrReplace

java.lang.Object

Torello.Java.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.

Regular-Expressions:
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.

Hi-Lited Source-Code:

• View Here: Torello/Java/StrReplace.java
• Open New Browser-Tab: Torello/Java/StrReplace.java

File Size: 34,935 Bytes Line Count: 661 '\n' Characters Found

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

🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

public static java.lang.String r(java.lang.String s,
                                 java.lang.String[] matchStrs,
                                 java.lang.String[] replaceStrs)

Convenience Method
Case-Sensitive
See Documentation: r(boolean, String, String[], String[])

Code:

Exact Method Body:

 return StrArrToStrArr.replace(false, s, matchStrs, replaceStrs);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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 Scenarious: 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:

 return StrArrToStrArr.replace(ignoreCase, s, matchStrs, replaceStrs);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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
See Documentation: r(boolean, String, String[], IntTFunction)

Code:

Exact Method Body:

 return StrArrToReplFunc.replace(false, s, matchStrs, replaceFunction);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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 Scenarious: 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:

 return StrArrToReplFunc.replace(ignoreCase, s, matchStrs, replaceFunction);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

public static java.lang.String r
            (java.lang.String s,
             ToCharIntTFunc<java.lang.String> replaceFunction,
             java.lang.String[] matchStrs)

Convenience Method
Case-Sensitive
See Documentation: r(String, boolean, String[], ToCharIntTFunc)

Code:

Exact Method Body:

 return StrArrToCharReplFunc.replace(s, false, matchStrs, replaceFunction);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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    = { "Π", "Ρ", "Σ", "Τ", "Υ", "Φ" };
 String   theString  = "Greek: Π, Ρ, Σ, Τ, Υ, Φ";
 
 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 Scenarious: 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:

 return StrArrToCharReplFunc.replace(s, ignoreCase, matchStrs, replaceFunction);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

public static java.lang.String r(java.lang.String s,
                                 java.lang.String[] matchStrs,
                                 char[] replaceChars)

Convenience Method
Case-Sensitive
See Documentation: r(boolean, String, String[], char[])

Code:

Exact Method Body:

 return StrArrToCharArr.replace(false, s, matchStrs, replaceChars);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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       = { "Π", "Ρ", "Σ", "Τ", "Υ", "Φ" };
 char[]    replacements  = { 'Π', 'Ρ', 'Σ', 'Τ', 'Υ', 'Φ'  };
 String    theString     = "Greek Letters: Π, Ρ, Σ, Τ, Υ, Φ";
 
 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 Scenarious: 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 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[] matchStrs are null pointers.

ParallelArrayException - If the arrays matchStrs and replaceChars are not identical lengths. These arrays must be parallel

Code:

Exact Method Body:

 return StrArrToCharArr.replace(ignoreCase, s, matchStrs, replaceChars);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

public static java.lang.String r(java.lang.String s,
                                 char[] matchChars,
                                 java.lang.String[] replaceStrs)

Convenience Method
Case-Sensitive
See Documentation: r(boolean, String, char[], String[])

Code:

Exact Method Body:

 return CharArrToStrArr.replace(false, s, matchChars, replaceStrs);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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 Scenarious: 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.

Furthermore: 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 String[] 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:

 return CharArrToStrArr.replace(ignoreCase, s, matchChars, replaceStrs);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

public static java.lang.String r
            (java.lang.String s,
             char[] matchChars,
             IntCharFunction<java.lang.String> replaceFunction)

Convenience Method
Case-Sensitive
See Documentation: r(boolean, String, char[], IntCharFunction)

Code:

Exact Method Body:

 return CharArrToStrReplFunc.replace(false, s, matchChars, replaceFunction);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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:

 return CharArrToStrReplFunc.replace(ignoreCase, s, matchChars, replaceFunction);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

public static java.lang.String r(java.lang.String s,
                                 char[] matchChars,
                                 char[] replaceChars)

Convenience Method
Case-Sensitive
See Documentation: r(boolean, String, char[], char[])

Code:

Exact Method Body:

 return CharArrToCharArr.replace(false, s, matchChars, replaceChars);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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 Scenarious: 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 String[] 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:

 return CharArrToCharArr.replace(ignoreCase, s, matchChars, replaceChars);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

public static java.lang.String r(java.lang.String s,
                                 char[] matchChars,
                                 char prependChar)

Convenience Method
Case-Sensitive
See Documentation: r(boolean, String, char[], char)

Code:

Exact Method Body:

 return CharArrPrepend.replace(false, s, matchChars, prependChar);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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 StrSource. These methods are StrSource.escStrForRegEx(String), StrSource.escStrForJavaScript(String).

Example:

 private static final char[] JS_ESCAPE_CHARS_ARR = { '\\', '/', '\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_ARR, '\\'); }
 
 // 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.
 
 private static final char[] REGEX_ESCAPE_CHARS_ARR =
 { '\\', '/', '(', ')', '[', ']', '{', '}', '$', '^', '+', '*', '?', '-', '.' };
 
 public static String escStrForRegEx(String str)
 { return StrReplace.r(str, REGEX_ESCAPE_CHARS_ARR, '\\'); }

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:

 return CharArrPrepend.replace(ignoreCase, s, matchChars, prependChar);

r

🡅 🡇 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

public static java.lang.String r(char[] matchChars,
                                 ToCharIntCharFunc replaceFunction,
                                 java.lang.String s)

Convenience Method
See Documentation: r(String, boolean, char[], ToCharIntCharFunc)

Code:

Exact Method Body:

 return CharArrToCharReplFunc.replace(s, false, matchChars, replaceFunction);

r

🡅 ⇈ ⮫ External-Java: ⮫ 🗕 🗗 🗖

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:

 return CharArrToCharReplFunc.replace(s, ignoreCase, matchChars, replaceFunction);