WORDTOCHAR()
 Exchanges double characters for individual ones
------------------------------------------------------------------------------
 Syntax

     WORDTOCHAR(<cDoubleCharacterList>,<cString>,
        <cCharacterlist>) --> cString

 Arguments

     <cDoubleCharacterList>  Designates multiple 2-byte sequences which
     are exchanged for corresponding individual characters from the
     <cCharacterlist>.

     <cString>  Designates the character string within which 2-byte
     sequences are exchanged for individual characters.

     <cCharacterlist>  Designates a sequence of individual characters
     which correspond to 2-byte sequences in <cDoubleCharacterList> for
     replacement within <cString>.

 Returns

     WORDTOCHAR() returns the modified character string.

 Description

     When you use SOUNDEX algorithms, sequences of two characters must often
     be exchanged for a single other character.  WORDTOCHAR() makes this
     process extremely simple and quick.

     The function processes the <cString> in 1-byte steps.  The behavior
     after exchanging a sequence for a character is determined by
     CSETATMUPA().  If CSETATMUPA is .F., the search for more sequences
     continues after the exchanged characters.  If CSETATMUPA is .T., the
     search for more sequences continues and includes the exchanged
     characters.

 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.

     .  <cCharacterlist> can be shorter than <cDoubleCharacterList>.
        When this occurs, the function exchanges the sequences in
        <cDoubleCharacterList> that do not have corresponding sequences in
        <cCharacterlist> for the last sequence in <cDoubleCharacterList>.

 Examples

     .  This example shows a simple replacement:

        ? WORDTOCHAR("aa", "Xaaaa", "a")      // "Xaa"

     .  This example shows WORDTOCHAR() in conjunction with
        CSETATMUPA():

        CSETATMUPA(.F.)                       // Multi pass off
        ? WORDTOCHAR("aa", "Xaaaa", "a")      // "Xaa"
        CSETATMUPA(.T.)                       // Multi pass on
        ? WORDTOCHAR("aa", "Xaaaa", "a")      // "Xa"