/* $DOC$
   $NAME$
      WordRepl()
   $CATEGORY$
      CT3 string functions
   $ONELINER$
      Replacement of double characters
   $SYNTAX$
      WordRepl( <cDoubleCharacterSearchString>, <[@]cString>,
                <cDoubleCharacterReplaceString>, [<lMode>] ) -> cString
   $ARGUMENTS$
      <cDoubleCharacterSearchString>   is a string of double characters
                                       that should be replaced
      <[@]cString>                     is the processed string
      <cDoubleCharacterReplaceString>  is a string of double characters that
                                       replace the one of <cSearchString>
      [<lMode>]                        sets the replacement method (see description)
                                       Default: .F.
   $RETURNS$
      cString                          the processed string
   $DESCRIPTION$
      The WordRepl() takes the double characters of <cDoubleCharacterSearchString>
      one after the other and searches for them in <cString>.
      For <lMode> set to .F., this search is successful, if the double
      character sequence in <cString> starts at an odd position or at any
      position, if <lMode> is set to .T.
      If this happens, the double character sequence will be replaced with
      the corresponding double character sequence of <cDoubleCharacterReplaceString>.
      If <cDoubleCharacterReplaceString> is shorter than <cDoubleCharacterSearchString>
      the last double sequence of <cDoubleCharacterReplaceString> is used for
      the "rest" of <cDoubleCharacterSearchString>. Note that the last double
      character sequence in "AABBC" is "BB" in this context !!
      After the replacement the function restarts the search in <cString>
      BEHIND the replacement if the CSetAtMupa() switch is turned off, or
      BEHIND the first character of the replacement if the switch is turned on.
      (see examples for this !)
      One can omit the return value of this function by setting the CSetRef()
      to .T., but one must then pass <cString> by reference to get a result.
   $EXAMPLES$
      ? WordRepl( "CC", "AABBCCDDEE", "XX" ) // "AABBXXDDEE"
      ? WordRepl( "aa", "1aaaa", "ba" )      // "1abaa"
      ? WordRepl( "aa", "1aaaa", "ba", .T. ) // "1baba"
      CSetAtMupa( .T. )
      ? WordRepl( "aa", "1aaaa", "ba" )      // "1abaa"
      ? WordRepl( "aa", "1aaaa", "ba", .T. ) // "1bbba"
   $STATUS$
      Ready
   $COMPLIANCE$
      WordRepl() is compatible with CT3's WordRepl().
   $PLATFORMS$
      All
   $FILES$
      Library is hbct.
   $SEEALSO$
      CharRepl(), RangeRepl(), PosRepl(), CSetRef(), CSetAtMupa()
   $END$
 */