CHARREPL()
 Replaces certain characters with others
------------------------------------------------------------------------------
 Syntax

     CHARREPL(<cSearchFor>,<cString>,   <cReplaceExpression>,
        [<lMode>]) --> cString

 Arguments

     <cSearchFor>  Designates a list of characters to search for in
     <cString>.

     <cString>  [@]  Designates the character string within which to
     search for and replace the characters in <cSearchFor>.

     <cReplaceExpression>  Designates the character list that replaces
     characters in <cString>.

     <lMode>  Designates whether multiple replacements are made.

     <lMode>  Designates one pass of the <cString> (.T.) or multiple
     replacements (.F.).  The default value is for .F..

 Returns

     The processed <cString> is returned.

 Description

     This function allows you to carry out very complex replacement
     procedures.  Every character in the <cSearchFor> is searched for within
     the <cString>.  If found, the character is replaced by the corresponding
     character in the <cReplaceExpression>.

     If <lMode> is not passed, characters are exchanged repeatedly as
     required.  This means that the function goes through each individual
     character in the found characters in sequence, and then searches the
     entire <cString>, exchanging <cSearchFor> for corresponding characters
     in <cReplaceExpression>.  When you use this technique, characters that
     have already been replaced are exchanged again if the replacement
     character also appears in the search list.

     However, if the optional <lMode> parameter is specified, the function
     proceeds differently.  It goes through each character in <cString> in
     sequence, determining whether or not it should be replaced.  Characters
     that have been replaced are not replaced again.

     As a rule, if the same characters appear within <cReplaceExpression> and
     <cSearchFor>, you must check very closely to determine which <lMode>
     parameter should be used (see example).

 Notes

     .  If the <cReplaceExpression> sequence is shorter than
        <cSearchFor>, the characters that do not have a corresponding
        replacement in <cReplaceExpression> are replaced with the last
        character of <cReplaceExpression> (see example).

     .  The return value of this function can be suppressed by
        implementing CSETREF() to save space in working memory.

 Examples

     .  The number "1" is replaced with the letter "a", the number "2"
        with the letter "b", etc..  If the number "4" appeared in the
        character string, it would be replaced with a "d":

        ? CHARREPL("1234", "1x2y3z", "abcd")              // "axbycz"

     .  The letters a-j are replaced with the numbers 0-9; for
        example, an "f" is replaced with a "6":

        ? CHARREPL("abcdefghij", "jhfdb", "1234567890")   // "08642"

     .  The third parameter makes fewer characters available for the
        exchange.  Therefore the letters f-j are replaced with the last
        characters from "12345":

        ? CHARREPL("abcdefghij", "jhfdb", "12345")        // "55542"

     .  Here is an example of the difference between a specified
        <lMode> parameter (.T.) and the default parameter (.F.):

        ? CHARREPL("1234", "1234", "234A")                // "AAAA"
        ? CHARREPL("1234", "1234", "234A", .T.)           // "234A"

See Also: WORDREPL() WORDTOCHAR() POSREPL() RANGEREPL()