@node Text/Soundex, Text/Tabs, Text/ParseWords, Module List
@unnumbered Implementation of the Soundex Algorithm as Described by Knuth


@unnumberedsec NAME

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

@unnumberedsec SYNOPSIS

@example
use Text::Soundex;
@end example

@example
$code = soundex $string;            # get soundex code for a string
@@codes = soundex @@list;             # get list of codes for list of strings
@end example

@example
# set value to be returned for strings without soundex code
@end example

@example
$soundex_nocode = @'Z000@';
@end example

@unnumberedsec DESCRIPTION

This module implements the soundex algorithm as described by Donald Knuth
in Volume 3 of @strong{The Art of Computer Programming}.  The algorithm is
intended to hash words (in particular surnames) into a small space using a
simple model which approximates the sound of the word when spoken by an English
speaker.  Each word is reduced to a four character string, the first
character being an upper case letter and the remaining three being digits.

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

In scalar context @code{soundex} returns the soundex code of its first
argument, and in array context a list is returned in which each element is the 
soundex code for the corresponding argument passed to @code{soundex} e.g.

@example
@@codes = soundex qw(Mike Stok);
@end example

leaves @code{@@codes} containing @code{(@'M200@', @'S320@')}.

@unnumberedsec EXAMPLES

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

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

so:

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

@unnumberedsec LIMITATIONS

As the soundex algorithm was originally used a @strong{long} time ago in 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 @code{Hilbert} and @code{Heilbronn} end up with a soundex code
of @code{H416}.

@unnumberedsec AUTHOR

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