WORDREPL()
 Replaces particular double characters with others
------------------------------------------------------------------------------
 Syntax

     WORDREPL(<cSearchDoubleCharacterstring>,<cString>,
        <cReplaceDoubleCharacterstring>,[<lMode>])
        --> cString

 Arguments

     <cSearchDoubleCharacterstring>  Designates multiple 2-byte character
     strings which are replaced by corresponding character strings from
     <cReplaceDoubleCharacterstring> within <cString>.

     <cString>  [@]  Designates the character string within which the 2-
     byte length sequences are exchanged.

     <cReplaceDoubleCharacterstring>  Designates multiple 2-byte
     character strings which replace corresponding character strings from
     <cSearchDoubleCharacterstring> within <cString>.

     <lMode>  Designates whether the character string <cString> is run
     through in single steps (.T.) or in ordered pairs (.F.).  The default
     value (.F.) designates ordered pairs.

 Returns

     The modified character string is returned.

 Description

     With this function, 2-byte sequences in a string can be exchanged for
     another sequence of the same length.  By using WORDREPL() and its analog
     function CHARREPL(), you can develop a very fast algorithm for SOUNDEX()
     functions.  Strings read from screen memory or generated by the
     Clipper I2BIN() function can be easily processed.

     The <cString> can be processed in a number of different ways.  It is
     here that the <lMode> parameter plays an important role, similar to the
     CSETATMUPA() functions.

     There are different modes of execution for the function:

     .  Depending on the <lMode> parameter, the string is processed in
        single steps or ordered pairs.

     .  CSETATMUPA() is successful only when <lMode> is designated
        as .T..  If CSETATMUPA() is .T., then WORDREPL() continues with the
        second character exchanged in a sequence.  If CSETATMUPA() is not
        .T., WORDREPL() continues with the character behind the second
        character.

 Notes

     .  The term "word" is not used here in the textual sense, but
        rather as it is used in assembler programming.  A "word" consists of
        units of 16 bits, or more precisely, 2 bytes.  The
        <cReplaceDoubleCharacterstring> parameter can be shorter than
        <cSearchDoubleCharacterstring>.

     .  The function exchanges sequences in
        <cSearchDoubleCharacterstring> that do not have corresponding
        sequences in <cReplaceDoubleCharacterstring> with the last sequence
        in <cReplaceDoubleCharacterstring>.

     .  The return value of the function can be suppressed by
        implementing CSETREF() to save space in working memory.

 Examples

     .  Exchange "XX" for "CC":

        ? WORDREPL("CC", "AABBCCDDEE", "XX")         // "AABBXXDDEE"

     .  Here is an example of use with CSETATMUPA() and <lMode>:

        CSETATMUPA(.F.)                              // Default
        ? WORDREPL("aa", "laaaa", "ba")              // "labaa"
        ? WORDREPL("aa", "laaaa", "ba", .T.)         // "lbaba"

     .  CSETATMUPA() only affects the function call when <lMode> is
        .T.:

        CSETATMUPA(.T.)                              // Multi-pass mode on
        ? WORDREPL("aa", "laaaa", "ba")              // "labaa"
        ? WORDREPL("aa", "laaaa", "ba", .T.)         // "lbbba"

See Also: CSETATMUPA() CHARREPL() CSETREF()