package Torello.Java;

import java.util.function.*;
import java.util.stream.*;

import Torello.Java.Function.*;
import Torello.Java.HelperPackages.StrReplace.*;

/**
 * An efficient way to replace multiple substring's, or single-characters, inside of a single
 * Java String, <I>in place, without rebuilding the returned {@code String} more than once.</I>
 * 
 * <EMBED CLASS=external-html DATA-FILE-ID=STR_REPLACE>
 */
@Torello.JavaDoc.StaticFunctional
public class StrReplace
{
    private StrReplace() { }

    /**
     * Convenience Method.
     * <BR />Case-Sensitive
     * @see #r(boolean, String, String[], String[])
     */
    public static String r(String s, String[] matchStrs, String[] replaceStrs)
    { return StrArrToStrArr.replace(false, s, matchStrs, replaceStrs); }

    /**
     * This shall replace each instance of the elements of parameter {@code 'matchStrs'} in input
     * {@code String 's'} with the elements of <I><B>parallel array</I></B> {@code 'replaceStrs'}
     *
     * @param ignoreCase When this parameter is set to {@code TRUE}, then the comparisons that
     * determine whether a match has occurred shall ignore the case of the characters involved.
     * 
     * @param s This may be any Java {@code String}.
     * 
     * @param matchStrs This is a {@code String[] array} that should hold some sub-strings of input
     * parameter {@code 's'}.  This method shall search {@code 's'} - <I>left to right</I> - for
     * any instances of the list of {@code 'matchStrs'} and replace those sub-strings with 
     * whatever {@code String} is in the <I>same array-index location (parallel-array)</I> from
     * input parameter {@code 'replaceStrs'}
     * 
     * <BR /><BR /><B STYLE="color: red;">MULTIPLE-MATCH SCENARIOS:</B> If there are substring's
     * within parameter {@code 'matchStrs'} such that the loop-iterations of this method could
     * select multiple, different {@code String's} as a substring match with the input parameter
     * {@code 's'}, then the loops will <I><B>always replace the first match found with input
     * {@code String[] array} parameter {@code 'matchStrs'}</I></B>.
     * 
     * <DIV CLASS="EXAMPLE">{@code
     * 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"
     * }</DIV>
     * 
     * @param replaceStrs This is also an {@code String[] array} that should hold sub-strings.
     * Every time a copy of any {@code 'matchStr'} is found within {@code 's'}, the index of the
     * sub-string match from {@code 'matchStrs'} shall be used to lookup the parallel
     * {@code 'replaceStr'}, and used to over-write or replace that sub-string inside {@code 's'}.
     * 
     * <BR /><BR /><B STYLE="color: red;">PARALLEL ARRAY:</B> This array should be considered
     * parallel to input {@code String[] array 'matchStrs'}.  It provides a replacement mapping.
     * It is required to be the exact same length as array {@code 'matchStrs'}, or an exception
     * shall throw.
     * 
     * @return This shall return a new-{@code String} where the replacements that were requested
     * have been substituted.
     * 
     * @throws NullPointerException If any of the {@code String's} inside the {@code String[]
     * arrays} contain null pointers.
     * 
     * @throws ParallelArrayException If the length of array {@code matchStrs} does not equal
     * the length of array {@code 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 {@code 's'}) from the first array.
     */
    public static String r(
            boolean     ignoreCase,
            String      s,
            String[]    matchStrs,
            String[]    replaceStrs
        )
    { return StrArrToStrArr.replace(ignoreCase, s, matchStrs, replaceStrs); }

    /**
     * Convenience Method.
     * <BR />Case-Sensitive
     * @see #r(boolean, String, String[], IntTFunction)
     */
    public static String r(
        String s, String[] matchStrs, IntTFunction<String, String> replaceFunction)
    { return StrArrToReplFunc.replace(false, s, matchStrs, replaceFunction); }

    /**
     * This shall replace each instance of the elements of parameter {@code 'matchStrs'} in input
     * {@code String 's'} with the {@code String}-value returned by the {@code 'replaceFunction'}
     * lambda-method / {@code functional-interface}.
     * 
     * @param ignoreCase When this parameter is set to {@code TRUE}, then the comparisons that
     * determine whether a match has occurred shall ignore the case of the characters involved.
     * 
     * @param s This may be any Java {@code String}.
     * 
     * @param matchStrs This is an {@code String[] array} that should hold some sub-strings of input
     * parameter {@code 's'}.  This method shall search {@code 's'} - <I>left to right</I> - for
     * any instances of the list of {@code 'matchStrs'} and replace those sub-strings with 
     * whatever {@code String} is returned by the {@code 'replaceFunction'}.
     * 
     * <BR /><BR /><B STYLE="color: red;">MULTIPLE-MATCH SCENARIOS:</B> If there are substring's
     * within parameter {@code 'matchStrs'} such that the loop-iterations of this method could
     * select multiple, different {@code String's} as a substring match with the input parameter
     * {@code 's'}, then the loops will <I><B>always replace the first match found with input
     * {@code String[] array} parameter {@code 'matchStrs'}</I></B>.
     * 
     * <DIV CLASS="EXAMPLE">{@code
     * 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.
     * }</DIV>
     * 
     * @param replaceFunction This shall receive as input a Java {@code String} that has matched
     * one of the {@code String's} that are within {@code 'matchStrs'}, along with the
     * {@code String}-index into the {@code String} where that match occured.  It must reply with
     * a replacement {@code String} (to replace that sub-string within the input {@code String}
     * parameter {@code 's'})  
     * 
     * <EMBED CLASS='external-html' DATA-IN=String DATA-OUT=String
     *      DATA-FILE-ID=STR_REPLACE_LOOK_AR>
     * 
     * @return This shall return a new-{@code String} where the replacements that were requested
     * have been substituted.
     * 
     * @throws NullPointerException If any of the {@code String's} inside the {@code String[]
     * arrays} contain null pointers.
     */
    public static String r(
            boolean                         ignoreCase,
            String                          s,
            String[]                        matchStrs,
            IntTFunction<String, String>    replaceFunction
        )
    { return StrArrToReplFunc.replace(ignoreCase, s, matchStrs, replaceFunction); }

    /**
     * Convenience Method.
     * <BR />Case-Sensitive
     * @see #r(String, boolean, String[], ToCharIntTFunc)
     */
    public static String r
        (String s, ToCharIntTFunc<String> replaceFunction, String[] matchStrs)
    { return StrArrToCharReplFunc.replace(s, false, matchStrs, replaceFunction); }

    /**
     * This shall replace each instance of the elements of parameter {@code 'matchStrs'} in input
     * {@code String 's'} with the {@code char}-value returned by the {@code 'replaceFunction'}
     * lambda-method / {@code functional-interface}.
     * 
     * <DIV CLASS="EXAMPLE">{@code
     * 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: Π, Ρ, Σ, Τ, Υ, Φ 
     * }</DIV>
     * 
     * @param s This may be any Java {@code String}.
     * 
     * @param ignoreCase When this parameter is set to {@code TRUE}, then the comparisons that
     * determine whether a match has occurred shall ignore the case of the characters involved.
     * 
     * @param matchStrs This is an {@code String[] array} that should hold some sub-strings of input
     * parameter {@code 's'}.  This method shall search {@code 's'} - <I>left to right</I> - for
     * any instances of the list of {@code 'matchStrs'} and replace those sub-strings with 
     * whatever {@code char} is returned by the {@code 'replaceFunction'} for that given 
     * match-{@code String};
     * 
     * <BR /><BR /><B STYLE="color: red;">MULTIPLE-MATCH SCENARIOS:</B> If there are multiple
     * copies (either ignoring case, or not ignoring case), of an identical {@code String} put into
     * {@code String[]} array parameter {@code 'matchStrs'}, this method will not generate an
     * exception (or anything like that) in such scenarios.
     * 
     * <BR /><BR />It is important to note that when invoking the {@code replaceFunction's} method
     * {@code apply(String)}, the {@code String} that is provided to {@code apply} will be the
     * <I>exact substring</I> found in the original-{@code String}.
     * 
     * @param replaceFunction This shall receive as input a Java {@code String} that has matched
     * one of the {@code String's} that are within {@code 'matchStrs'}, along with the
     * {@code String}-index into the {@code String} where that match occured.  It must reply with
     * a replacement {@code 'char'} (which will replace that matched sub-string found within 
     * {@code 's'}).
     * 
     * <EMBED CLASS='external-html' DATA-IN=String DATA-OUT=char
     *      DATA-FILE-ID=STR_REPLACE_LOOK_AR>
     * 
     * @return This shall return a new-{@code String} where the replacements that were requested
     * have been substituted.
     * 
     * @throws NullPointerException If any of the {@code String's} inside the {@code String[]
     * arrays} contain null pointers.
     */
    public static String r(
            String                  s,
            boolean                 ignoreCase,
            String[]                matchStrs,
            ToCharIntTFunc<String>  replaceFunction
        )
    { return StrArrToCharReplFunc.replace(s, ignoreCase, matchStrs, replaceFunction); }

    /**
     * Convenience Method.
     * <BR />Case-Sensitive
     * @see #r(boolean, String, String[], char[])
     */
    public static String r(String s, String[] matchStrs, char[] replaceChars)
    { return StrArrToCharArr.replace(false, s, matchStrs, replaceChars); }

    /**
     * This shall replace each instance of the elements of parameter {@code 'matchStrs'} in input
     * {@code String 's'} with the provided characters in <I><B>parallel array</I></B>
     * {@code 'replaceChars'}.
     *
     * <DIV CLASS="EXAMPLE">{@code
     * 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: Π, Ρ, Σ, Τ, Υ, Φ 
     * }</DIV>
     * 
     * @param s This may be any Java {@code String}.
     * 
     * @param ignoreCase When this parameter is set to {@code TRUE}, then the comparisons that
     * determine whether a match has occurred shall ignore the case of the characters involved.
     * 
     * @param matchStrs This is a {@code String[] array} that should hold some sub-strings of input
     * parameter {@code 's'}.  This method shall search {@code 's'} - <I>left to right</I> - for
     * any instances of the list of {@code 'matchStrs'} and replace those sub-strings with 
     * whatever {@code char} is in the <I>same array-index location (parallel-array)</I> from
     * input parameter {@code 'replaceChars'}.
     * 
     * <BR /><BR /><B STYLE="color: red;">MULTIPLE-MATCH SCENARIOS:</B> If there are substring's
     * within parameter {@code 'matchStrs'} such that the loop-iterations of this method could
     * select multiple, different {@code String's} as a substring match with the input parameter
     * {@code 's'}, then the loops will <I><B>always replace the first match found with input
     * {@code String[] array} parameter {@code 'matchStrs'}</I></B>.
     * 
     * @param replaceChars This is also a {@code char[] array}.  Every time a copy of any of the
     * {@code 'matchStrs'} is found within {@code 's'}, the index of the {@code String} match from
     * {@code 'matchStrs'} shall be used to lookup the parallel {@code 'replaceChar'}, and used
     * to over-write or replace that character inside {@code 's'}.
     * 
     * <BR /><BR /><B STYLE="color: red;">PARALLEL ARRAY:</B> This array should be considered
     * parallel to input {@code char[] array 'matchStrs'}.  It provides a replacement mapping.
     * It is required to be the exact same length as array {@code 'matchChars'}, or an exception
     * shall throw.
     * 
     * @return This shall return a new-{@code String} where the replacements that were requested
     * have been substituted.
     * 
     * @throws NullPointerException If any of the {@code String's} inside the {@code String[]
     * matchStrs} are null pointers.
     * 
     * @throws ParallelArrayException If the arrays {@code matchStrs} and {@code replaceChars}
     * are not identical lengths.  These arrays must be parallel
     */
    public static String r(
            boolean     ignoreCase,
            String      s,
            String[]    matchStrs,
            char[]      replaceChars
        )
    { return StrArrToCharArr.replace(ignoreCase, s, matchStrs, replaceChars); }

    /**
     * Convenience Method.
     * <BR />Case-Sensitive
     * @see #r(boolean, String, char[], String[])
     */
    public static String r(String s, char[] matchChars, String[] replaceStrs)
    { return CharArrToStrArr.replace(false, s, matchChars, replaceStrs); }

    /**
     * This shall replace each instance of the characters of parameter {@code 'matchStrs'} in input
     * {@code String 's'} with the {@code String's} of <I><B>parallel array</I></B>
     * {@code 'replaceStrs'}.
     *
     * @param ignoreCase When this parameter is set to {@code TRUE}, then the comparisons that
     * determine whether a match has occurred shall ignore the case of the characters involved.
     * 
     * @param s This may be any Java {@code String}.
     * 
     * @param matchChars This is a {@code char[] array} that should hold some set of characters
     * which are expected to be contained within the input parameter {@code 's'}.  This method
     * shall search {@code 's'} - <I>left to right</I> - for any instances of the list of
     * {@code 'matchChars'} and replace those characters with whatever {@code String} is in the
     * <I>same array-index location (parallel-array)</I> from input parameter
     * {@code 'replaceStrs'}
     * 
     * <BR /><BR /><B STYLE="color: red;">MULTIPLE-MATCH SCENARIOS:</B> If there are multiple
     * copies of an the <I>exact same character</I> in input parameter {@code '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 {@code 'matchChars'} attempts to
     * map the same {@code char} to more than one replacement-{@code String}, the loop will
     * simply use the first-mapping found in {@code 'replaceStrs'} that is found.  No exceptions
     * will throw when presented with this type of input.
     *
     * <BR /><BR /><B>ALSO:</B> If an upper-case and lower-case version of the <I>exact same
     * character</I> is provided in {@code char[] array} parameter {@code 'matchChars'}, and the
     * {@code boolean flag} parameter {@code 'ignoreCase'} were set to {@code TRUE}, whichever of
     * the two characters (upper-case or lower-case) that <I>occurs first in array parameter
     * {@code 'matchChars'}</I> would be used to provide a replacement-{@code String} from array
     * parameter {@code 'replaceStrs'}
     * 
     * @param replaceStrs This is a {@code String[] array} that should hold sub-strings.
     * Every time a copy of any of the {@code 'matchChars'} is found within {@code 's'}, the
     * index of the character match from {@code 'matchChars'} shall be used to lookup the parallel
     * {@code 'replaceStr'}, and used to over-write or replace that character inside {@code 's'}.
     * 
     * <BR /><BR /><B STYLE="color: red;">PARALLEL ARRAY:</B> This array should be considered
     * parallel to input {@code char[] array 'matchChars'}.  It provides a replacement mapping.
     * It is required to be the exact same length as array {@code 'matchChars'}, or an exception
     * shall throw.
     * 
     * @return This shall return a new-{@code String} where the replacements that were requested
     * have been substituted.
     * 
     * @throws NullPointerException If any of the {@code String's} inside {@code String[]
     * replaceStrs} are null.
     * 
     * @throws ParallelArrayException If the length of array {@code matchChars} does not equal
     * the length of array {@code 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 {@code 's'}) from the first array.
     */
    public static String r(
            boolean     ignoreCase,
            String      s,
            char[]      matchChars,
            String[]    replaceStrs
        )
    { return CharArrToStrArr.replace(ignoreCase, s, matchChars, replaceStrs); }

    /**
     * Convenience Method.
     * <BR />Case-Sensitive
     * @see #r(boolean, String, char[], IntCharFunction)
     */
    public static String r
        (String s, char[] matchChars, IntCharFunction<String> replaceFunction)
    { return CharArrToStrReplFunc.replace(false, s, matchChars, replaceFunction); }

    /**
     * This shall replace each instance of the characters of parameter {@code 'matchStrs'} in input
     * {@code String 's'} with the {@code String}-value returned by the {@code 'replaceFunction'}
     * lambda-method / {@code functional-interface}.
     *
     * <DIV CLASS="EXAMPLE">{@code
     * // 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);
     * }</DIV>
     * 
     * @param ignoreCase When this parameter is set to {@code TRUE}, then the comparisons that
     * determine whether a match has occurred shall ignore the case of the characters involved.
     * 
     * @param s This may be any Java {@code String}.
     * 
     * @param matchChars This is a {@code char[] array} that should hold some set of characters
     * which are expected to be contained within the input parameter {@code 's'}.  This method
     * shall search {@code 's'} - <I>left to right</I> - for any instances of the list of
     * {@code 'matchChars'} and replace those characters with the results from input 
     * {@code functional-interface} parameter {@code 'replaceFunction'}.
     * 
     * @param replaceFunction This shall receive any Java {@code 'char'} along with the index into
     * {@code String 's'} where that {@code 'char'} is located.  This function must reply with a
     * replace-{@code String}.  This shall be used to replace any instances of that character
     * found inside the input {@code String}.
     * 
     * <EMBED CLASS='external-html' DATA-IN=char DATA-OUT=String
     *      DATA-FILE-ID=STR_REPLACE_LOOK_AR>
     * 
     * @return This shall return a new-{@code String} where the replacements that were requested
     * have been substituted.
     */
    public static String r(
            boolean                 ignoreCase,
            String                  s,
            char[]                  matchChars,
            IntCharFunction<String> replaceFunction
        )
    { return CharArrToStrReplFunc.replace(ignoreCase, s, matchChars, replaceFunction); }

    /**
     * Convenience Method.
     * <BR />Case-Sensitive
     * @see #r(boolean, String, char[], char[])
     */
    public static String r(String s, char[] matchChars, char[] replaceChars)
    { return CharArrToCharArr.replace(false, s, matchChars, replaceChars); }

    /**
     * This shall replace any instance of any of the characters in array-parameter 
     * {@code 'matchChars'} with the character's provided in array-parameter
     * {@code 'replaceChars'}.
     * 
     * <DIV CLASS="EXAMPLE">{@code
     * // 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"
     * }</DIV>
     * 
     * @param ignoreCase When this parameter is set to {@code TRUE}, then the comparisons that
     * determine whether a match has occurred shall ignore the case of the characters involved.
     * 
     * @param s This may be any valid Java {@code String}.  It is expected to contain at least
     * some of the characters that are listed in parameter {@code 'matchChars'}.
     * 
     * @param matchChars This is a {@code char[] array} that should hold some set of characters
     * which are expected to be contained within the input parameter {@code 's'}.  This method
     * shall search {@code 's'} - <I>left to right</I> - for any instances of the list of
     * {@code 'matchChars'} and replace those characters with whatever {@code char} is in the
     * <I>same array-index location (parallel-array)</I> from input parameter
     * {@code 'replaceChars'}
     * 
     * <BR /><BR /><B STYLE="color: red;">MULTIPLE-MATCH SCENARIOS:</B> If there are multiple
     * copies of an the <I>exact same character</I> in input parameter {@code '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 {@code 'matchChars'} attempts to
     * map the same {@code char} to more than one replacement-{@code char}, the loop will
     * simply use the first-mapping found in {@code 'replaceStrs'} that is found.  No exceptions
     * will throw when presented with this type of input.
     *
     * @param replaceChars This is also a {@code char[] array}.  Every time a copy of any of the
     * {@code 'matchChars'} is found within {@code 's'}, the index of the character match from
     * {@code 'matchChars'} shall be used to lookup the parallel {@code 'replaceChar'}, and used
     * to over-write or replace that character inside {@code 's'}.
     * 
     * <BR /><BR /><B STYLE="color: red;">PARALLEL ARRAY:</B> This array should be considered
     * parallel to input {@code char[] array 'matchChars'}.  It provides a replacement mapping.
     * It is required to be the exact same length as array {@code 'matchChars'}, or an exception
     * shall throw.
     * 
     * @return This shall return a copy of the input {@code String}, with all characters that
     * matched the characters in {@code 'matchChars'}, <I>replaced by the characters in 
     * {@code 'replaceChars'}</I>.
     * 
     * @throws ParallelArrayException If the length of the {@code 'matchChars' array} is not
     * equal to the length of the {@code 'replaceChars'} array.
     */
    public static String r(
            boolean ignoreCase,
            String  s,
            char[]  matchChars,
            char[]  replaceChars
        )
    { return CharArrToCharArr.replace(ignoreCase, s, matchChars, replaceChars); }

    /**
     * Convenience Method.
     * <BR />Case-Sensitive
     * @see #r(boolean, String, char[], char)
     */
    public static String r(String s, char[] matchChars, char prependChar)
    { return CharArrPrepend.replace(false, s, matchChars, prependChar); }

    /**
     * This shall "prepend" a specified / chosen character before each instance of a list
     * of characters in an input-{@code String}.  {@code LAY-SPEAK:} If, for example, the
     * {@code 'prependChar'} provided were the back-slash character {@code '\'}, then this
     * method would insert a back-slash before each and every one of the {@code 'matchChars'}
     * that it found inside {@code 's'}.
     * 
     * <BR /><BR />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
     * {@link StrSource}.  These methods are {@link StrSource#escStrForRegEx(String)},
     * {@link StrSource#escStrForJavaScript(String)}.
     * 
     * <DIV CLASS="EXAMPLE">{@code 
     * 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, '\\'); }
     * }</DIV>
     * 
     * @param ignoreCase When this parameter is set to {@code TRUE}, then the comparisons that
     * determine whether a match has occurred shall ignore the case of the characters involved.
     *
     * @param s This may be any valid Java {@code String}.  It is expected to contain at least
     * some of the characters that are listed in parameter {@code 'matchChars'}.
     * 
     * @param matchChars This is a {@code char[] array} that should hold some set of characters
     * which are expected to be contained within the input parameter {@code 's'}.  This method
     * shall search {@code 's'} - <I>left to right</I> - for any instances of the list of
     * {@code 'matchChars'} and insert the character {@code 'prependChar'} directly before each
     * match-character identified in {@code String}-parameter {@code 's'}.
     * 
     * @param prependChar This character will be inserted directly before each instance of 
     * {@code matcChars}-characters that are found within input {@code String}-parameter
     * {@code 's'}
     * 
     * @return This shall return a new {@code String} with the {@code 'prependChar'} before each
     * instance of one of the {@code 'matchChars'} identified in the original {@code String 's'}.
     */
    public static String r(
            boolean ignoreCase,
            String  s,
            char[]  matchChars,
            char    prependChar
        )
    { return CharArrPrepend.replace(ignoreCase, s, matchChars, prependChar); }

    /**
     * Convenience Method.
     * @see #r(String, boolean, char[], ToCharIntCharFunc)
     */
    public static String r(char[] matchChars, ToCharIntCharFunc replaceFunction, String s)
    { return CharArrToCharReplFunc.replace(s, false, matchChars, replaceFunction); }

    /**
     * This method shall receive a list of {@code 'char'}, and then search the input
     * {@code String} parameter {@code 's'} for any instances of the characters listed in
     * {@code 'matchChars'} - and replace them.  The replacement characters must be provided
     * by the Functional-Interface Parameter {@code 'replaceFunction'}.
     * 
     * <BR /><BR />The character-equality comparisons may be done in a case-insensitive manner,
     * if requested (using the {@code 'ignoreCase'} parameter).
     * 
     * @param s This may be any valid Java {@code String}.  It is expected to contain at least
     * some of the characters that are listed in parameter {@code 'matchChars'}.
     * 
     * @param ignoreCase If this parameter receives {@code TRUE}, then the equality comparisons
     * between the input {@code String 's'}, and {@code 'matchChars'} will be done on a case
     * insensitive basis.
     * 
     * @param matchChars This is a {@code char[] array} that should hold some set of characters
     * which are expected to be contained insiide the input parameter {@code 's'}.  This method
     * shall search {@code 's'} - <I>left to right</I> - for any instances of the list of
     * {@code 'matchChars'} and replace those characters with ones returned by
     * {@code 'replaceFunction.apply(i, c);'}.  Note that, here, {@code 'i'} is the
     * {@code String}-index where the {@code 'matchChar'} was found, and {@code 'c'} is the 
     * character that was matched.
     * 
     * @param replaceFunction This shall receive any Java {@code 'char'} along with the index into
     * {@code String 's'} where that {@code 'char'} is located.  This function must reply with a
     * replace-{@code char}.  This shall be used to replace instances of that character
     * found inside the input {@code String}. 
     * 
     * <EMBED CLASS='external-html' DATA-IN=char DATA-OUT=char
     *      DATA-FILE-ID=STR_REPLACE_LOOK_AR>
     * 
     * @return A new {@code String} where any and all characters that were listed in 
     * {@code 'matchChars'} have been replaced by the return-values of {@code 'replaceFunction'}.
     */
    public static String r(
            String              s,
            boolean             ignoreCase,
            char[]              matchChars,
            ToCharIntCharFunc   replaceFunction
        )
    { return CharArrToCharReplFunc.replace(s, ignoreCase, matchChars, replaceFunction); }
}