Searches for a sequence within a string and replaces it


        [<nCounter>],[<lMode>]) --> cString


     <cSearchFor>  Designates the expression for which the function

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


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


     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.


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


     .  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

        ? 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

        ? ATREPL("aa", "aaaa", "a")                      // "aa"

        ? ATREPL("aa", "aaaa", "a")                      // "a"

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

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

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

See Also: CSETATMUPA() SETATLIKE() Introduction


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.