Seth Woolley's Man Viewer

Text::Soundex(3)       Perl Programmers Reference Guide       Text::Soundex(3)



NAME
       Text::Soundex - Implementation of the Soundex Algorithm as Described by
       Knuth

SYNOPSIS
         use Text::Soundex;

         $code = soundex $string(3,n);            # get soundex code for a string(3,n)
         @codes = soundex @list;             # get list of codes for list of strings

         # set(7,n,1 builtins) value to be returned for strings without soundex code

         $soundex_nocode = 'Z000';

DESCRIPTION
       This module implements the soundex algorithm as described by Donald
       Knuth in(1,8) Volume 3 of The Art of Computer Programming.  The algorithm is
       intended to hash words (in(1,8) particular surnames) into a small space
       using a simple model which approximates the sound of the word when spo-
       ken by an English speaker.  Each word is reduced to a four character
       string(3,n), the first character being an upper case letter and the remain-
       ing three being digits.

       If there is no soundex code representation for a string(3,n) then the value
       of $soundex_nocode is returned.  This is initially set(7,n,1 builtins) to "undef", but
       many people seem to prefer an unlikely value like "Z000" (how unlikely
       this is depends on the data set(7,n,1 builtins) being dealt with.)  Any value can be
       assigned to $soundex_nocode.

       In scalar context "soundex" returns the soundex code of its first argu-
       ment, and in(1,8) list context a list is returned in(1,8) which each element is
       the soundex code for the corresponding argument passed to "soundex"
       e.g.

         @codes = soundex qw(Mike Stok);

       leaves @codes containing "('M200', 'S320')".

EXAMPLES
       Knuth's examples of various names and the soundex codes they map to are
       listed below:

         Euler, Ellery -> E460
         Gauss, Ghosh -> G200
         Hilbert, Heilbronn -> H416
         Knuth, Kant -> K530
         Lloyd, Ladd -> L300
         Lukasiewicz, Lissajous -> L222

       so:

         $code = soundex 'Knuth';              # $code contains 'K530'
         @list = soundex qw(Lloyd Gauss);      # @list contains 'L300', 'G200'

LIMITATIONS
       As the soundex algorithm was originally used a long time(1,2,n) ago in(1,8) the US
       it considers only the English alphabet and pronunciation.

       As it is mapping a large space (arbitrary length strings) onto a small
       space (single letter plus 3 digits) no inference can be made about the
       similarity of two strings which end up with the same soundex code.  For
       example, both "Hilbert" and "Heilbronn" end up with a soundex code of
       "H416".

AUTHOR
       This code was implemented by Mike Stok ("stok@cybercom.net") from the
       description given by Knuth.  Ian Phillipps ("ian@pipex.net") and Rich
       Pinder ("rpinder@hsc.usc.edu") supplied ideas and spotted mistakes.



perl v5.8.5                       2001-09-21                  Text::Soundex(3)