Click above to get retro games delivered to your door ever month!

 ATREPL()
 Searches for a sequence within a string and replaces it
------------------------------------------------------------------------------
 Syntax

     ATREPL(<cSearchFor>,<cString>,<cReplace>,
        [<nCounter>],[<lMode>]) --> cString

 Arguments

     <cSearchFor>  Designates the expression for which the function
     searches.

     <cString>  [@]  Designates the character string that is searched.

     <cReplace>  Designates the character string that is exchanged for
     the sequence in <cString>.

     <nCounter>  Designates which or how many occurrences of <cSearchFor>
     within <cString> are replaced by <cReplace>.  The default value is for
     the last occurrence of the search expression.

     <lMode>  Designates if only the nth (<nCounter>) sequence is
     replaced (.T.), or if all sequences up to the nth (<nCounter>) are
     replaced (.F.).  The default value (.F.) designates that all sequences
     are replaced.

 Returns

     The function returns a character string in which one or many of the
     <cSearchFor> sequences have been replaced by <cReplace>.

 Description

     ATREPL() allows you to replace one or more sequences within <cString>.
     <cReplace> can be shorter or longer than <cSearchFor>.

     <nCounter> specifies that the function searches for the nth occurrence
     of the sequence.  If no value is specified, then the last occurrence is
     used.  All occurrences of <cSearchFor>, up to and including the one
     sought, are replaced unless <nCounter> is assigned a value greater than
     0 and <lMode> is designated .T..

     The CSETATMUPA() setting is only checked when the length of <cReplace>
     is shorter than or equal to that of <cSearchFor>, yielding different
     results.  Beginning on the left, the character string is searched for
     each occurrence of the <cSearchFor> sequence.  If CSETATMUPA() is off
     (.F.), then the search continues after the last character of the
     replaced sequence.  However, if CSETATMUPA() is on, the search always
     continues from the first character of the replaced sequence.

 Notes

     .  By implementing SETATLIKE() you can use wildcard characters
        within the search sequence.

     .  <cString> can be passed by reference.  If this is the case,
        then both <cSearchFor> and <cReplace> must be the same length.

     .  If <cSearchFor> and <cReplace> are identical, the function
        terminates immediately.  Such an exchange makes no sense, and if
        CSETATMUPA() is (.T.), the exchange results in an endless loop.

 Examples

     .  Exchange all "123" with "ab":

        ? ATREPL("123", "123_123_123", "ab")             // "ab_ab_ab"

     .  Replace "789" with a longer string "abcd" (ignore multi-pass):

        ? ATREPL("789", "789_789", "abcd")               // "abcd_abcd"

     .  Exchange all "123" with "ab", up to and including the second
        occurrence:

        ? ATREPL("123", "123_123_123", "ab", 2)          // "ab_ab_123"

     .  Exchange only the second occurrence of "123" with "ab":

        ? ATREPL("123", "123_123_123", "ab", 2, .T.)     // "123_ab_123"

     .  Exchange all "aa" for "a" and the change the influence of
        CSETATMUPA():

        CSETATMUPA(.F.)
        ? ATREPL("aa", "aaaa", "a")                      // "aa"

        CSETATMUPA(.T.)
        ? ATREPL("aa", "aaaa", "a")                      // "a"

     .  Exchange "abc" with "ab", with and without multi-pass:

        CSETATMUPA(.F.)
        ? ATREPL("abc", "123abcc456", "ab")              // "123abc456"

        CSETATMUPA(.T.)
        ? ATREPL("abc", "123abcc456", "ab")              // "123ab456"