/*  $DOC$
 *  $FUNCNAME$
 *      CHARREPL()
 *  $CATEGORY$
 *      HBCT string functions
 *  $ONELINER$
 *      Replacement of characters
 *  $SYNTAX$
 *      CHARREPL (<cSearchString>, <[@]cString>,
 *                <cReplaceString>, [<lMode>]) -> cString
 *  $ARGUMENTS$
 *      <cSearchString>    is a string of characters that should be replaced
 *      <[@]cString>       is the processed string
 *      <cReplaceString>   is a string of characters that replace the one
 *                         of <cSearchString>
 *      [<lMode>]          sets the replacement method (see description)
 *                         Default: .F.
 *  $RETURNS$
 *      <cString>          the processed string
 *  $DESCRIPTION$
 *      The CHARREPL() function replaces certain characters in <cString>
 *      with others depending on the setting of <lMode>.
 *      If <lMode> is set to .F., the function takes the characters of
 *      <cSearchString> one after the other, searches for them in <cString>
 *      and, if successful, replaces them with the corresponding character
 *      of <cReplaceString>. Be aware that if the same characters occur
 *      in both <cSearchString> and <cReplaceString>, the character on a
 *      certain position in <cString> can be replaced multiple times. 
 *      if <lMode> is set to .T., the function takes the characters in <cString>
 *      one after the other, searches for them in <cSearchString> and, if
 *      successful, replaces them with the corresponding character of
 *      <cReplaceString>. Note that no multiple replacements are possible
 *      in this mode.
 *      If <cReplaceString> is shorter than <cSearchString>, the last
 *      character of <cReplaceString> is used as corresponding character
 *      for the the "rest" of <cSearchString>.
 *      One can omit the return value by setting the CSETREF() switch to .T.,
 *      but then one must pass <cString> by reference to get the result.
 *  $EXAMPLES$
 *      ? charrepl ("1234", "1x2y3z", "abcd")            // "axbycz" 
 *      ? charrepl ("abcdefghij", "jhfdb", "1234567890") // "08642"  
 *      ? charrepl ("abcdefghij", "jhfdb", "12345")      // "55542"  
 *      ? charrepl ("1234", "1234", "234A")              // "AAAA"   
 *      ? charrepl ("1234", "1234", "234A", .T.)         // "234A"   
 *  $TESTS$
 *      charrepl ("1234", "1x2y3z", "abcd") == "axbycz" 
 *      charrepl ("abcdefghij", "jhfdb", "1234567890") == "08642"  
 *      charrepl ("abcdefghij", "jhfdb", "12345") == "55542"  
 *      charrepl ("1234", "1234", "234A") == "AAAA"   
 *      charrepl ("1234", "1234", "234A", .T.) == "234A"   
 *  $STATUS$
 *      Ready
 *  $COMPLIANCE$
 *      CHARREPL() is compatible with CT3's CHARREPL().
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Source is charrepl.c, library is ct3.
 *  $SEEALSO$
 *      WORDREPL()   POSREPL()   RANGEREPL()
 *      CSETREF()
 *  $END$
 */
