/*
 * $Id: atrepl.txt 15102 2010-07-14 12:48:39Z vszakats $
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ATREPL()
 *  $CATEGORY$
 *      CT3 string functions
 *  $ONELINER$
 *      Search and replace sequences in a string
 *  $SYNTAX$
 *      ATREPL (<cStringToMatch>, <cString>, <cReplacement>, [<nCounter>],
 *              [<lMode>], [<nIgnore>]) --> cString
 *  $ARGUMENTS$
 *      <cStringToMatch>   is the substring searched for in <cString>
 *      <cString>          is the processed string
 *      <cReplacement>     is the replacement for sequences found
 *      [<nCounter>]       specifies the number of replacements
 *                         Default: last occurence
 *      [<lMode>]          if set to .T., only the <nCounter>th sequence
 *                         of <cStringToMatch> will be replaced, else
 *                         all sequences will be replaced.
 *                         Default: .F.
 *      [<nIgnore>])       specifies how many characters in <cString> from
 *                         the beginning should be ignored by the function
 *                         Default: 0
 *  $RETURNS$
 *      <cString>
 *  $DESCRIPTION$
 *      The ATREPL() function searches and replaces sequences in a string.
 *      First, the function ignores the first <nIgnore> characters of <cString>.
 *      Then, if <lMode> is set to .T., it searches for the <nCounter>th
 *      occurence of <cStringToMatch> in <cString>. If successful, the
 *      sequence will be replaced with <cReplacement>.
 *      If <lMode> is set to .F., the same search is performed, but EVERY
 *      occurence of <cStringToMatch> till the <nCounter>th (inclusive) will
 *      be replaced with <cReplacement>. Note that, in this case,
 *      the replacements are performed even if the <nCounter>th occurence
 *      does not exist.
 *      By using the CSETATMUPA() switch you can decide whether the
 *      function restarts searching after a found sequence of after
 *      the first character of that sequence.
 *      The function allows the use of wildcards in <cStringToMatch>
 *      and looks for the settings of SETATLIKE().
 *  $EXAMPLES$
 *      ? ATREPL("ABC", "ABCDABCDABC", "xx")    --> "xxDxxDxx"
 *      ? ATREPL("ABC", "ABCDABC", "ZYXW")      --> "ZYXWDZYXW"
 *      ? ATREPL("ABC", "ABCDABCDABC", "xx", 2) --> "xxDxxDABC"
 *      ? ATREPL("ABC", "ABCDABCDABC", "xx", 2, .T.)  --> "ABCDxxDABC"
 *  $TESTS$
 *      ATREPL("ABC", "ABCDABCDABC", "xx") == "xxDxxDxx"
 *      ATREPL("ABC", "ABCDABC", "ZYXW") == "ZYXWDZYXW"
 *      ATREPL("ABC", "ABCDABCDABC", "xx", 2) == "xxDxxDABC"
 *      ATREPL("ABC", "ABCDABCDABC", "xx", 2, .T.) == "ABCDxxDABC"
 *  $STATUS$
 *      Ready
 *  $COMPLIANCE$
 *      ATREPL() is compatible with CT3's ATREPL().
 *      Note the new, 6th parameter !
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Source is atrepl.c, library is ct3.
 *  $SEEALSO$
 *      CSETATMUPA()   SETATLIKE()
 *  $END$
 */
