/* $DOC$
   $NAME$
      CharRepl()
   $CATEGORY$
      CT3 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"
   $STATUS$
      Ready
   $COMPLIANCE$
      CharRepl() is compatible with CT3's CharRepl().
   $PLATFORMS$
      All
   $FILES$
      Library is hbct.
   $SEEALSO$
      WordRepl(),  PosRepl(),  RangeRepl(), CSetRef()
   $END$
 */