SOUNDEX(<expC>)
 Searches for similar sounding names that are spelled differently.
 Returns <expC> soundex code as a four-character string in the format "A999".

 Our SOUNDEX() function is used in Summer '87 only.
 In Clipper 5.0, use Clipper's own SOUNDEX() function.

 Useful for indexing large name and address databases where
 the user may misspell names to search for.

 Based on the soundex algorithm on page 392 in The Art of Computer
 Programming, Volume 3, Sorting and Searching, by Donald E. Knuth.

 The first character in <expC> becomes the first character in the
 soundex code.  The remaining 3 characters in the soundex code
 will be digits assigned according to the remaining characters in <expC>.

 Assigns a number code for letters until the soundex code reaches 4
 characters.  Pads with zeros if <expC> ends before the soundex code
 reaches 4 characters.

 Ignores all characters not listed below, those listed when their code
 repeats, and everything after the soundex code reaches 4 characters.

 Alpha character(s)        Soundex digit
 ══════════════════════    ═════════════
 B, F, P, V                1
 C, G, J, K, Q, S, X, Z    2
 D, T                      3
 L                         4
 M, N                      5
 R                         6

 SOUNDEX("Smith")  returns S530
 SOUNDEX("Smythe") returns S530

 SOUNDEX("Rettig")  returns R320
 SOUNDEX("Reddick") returns R322

 SOUNDEX("Silver") returns S416
 SOUNDEX("Slevor") returns S416

 * Both examples assume an open database file

 * Create soundex index for the first time
 INDEX ON SOUNDEX( Last_name ) TO Lname

 * Search for user entry in indexed file
 m_lastname = SPACE(25)
 @...SAY "Enter last name: " GET m_lastname
 READ
 SEEK SOUNDEX( m_lastname )
 IF FOUND()
    @...SAY "Is this the right record? (Y/N)"
    @...SAY "Press Escape to return to the menu"
    DO WHILE SOUNDEX(m_lastname) ==;
             SOUNDEX(Last_name);
             .AND. (.NOT. EOF())
       <display fields from record>
       choice = INKEY(5000)
       DO CASE
          CASE CHR(choice) $ "yY"   && right one
             @...SAY    && clear the user prompt
             <do appropriate routine>
          CASE choice = 27 .OR. choice = 0
             RETURN
          OTHERWISE
             SKIP  && next record with same code
       ENDCASE
    ENDDO
    * Looked at all; none were chosen by user
 ENDIF

 If the first character in <expC> passed to SOUNDEX() is not an
 alpha character, an empty 4-byte string is returned.  This causes
 the record to be placed at the top of the index.

 Hazard
    Fails in some cases such as Rogers and Rodgers having
    different codes but, in most cases, the soundex code greatly
    increases the chance of finding a name in one of its disguises.


             Placed in the Public Domain by Tom Rettig Assoc.