NAME

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

SYNOPSIS

  use Text::Soundex;

  $code = soundex($name);    # Get the soundex code for a name.
  @codes = soundex(@names);  # Get the list of codes for a list of names.

  # This is how you define what you want to be returned if your
  # input string has no indentifiable codes within it.

  # Make the change permanent.
  $Text::Soundex::nocode = 'Z000';

  # Make the change temporary.
  {
      local $Text::Soundex::nocode = 'Z000';   # Temporary change.
      $code = soundex($name);
  }

DESCRIPTION

This module implements the soundex algorithm as described by Donald Knuth in Volume 3 of 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.

The value returned for strings which have no soundex encoding is set in the scalar $Text::Soundex::nocode. This is initially set to undef, but many people seem to prefer an unlikely value like Z000 (how unlikely this is depends on the data set being dealt with.) Any value can be assigned to $Text::Soundex::nocode.

For backward compatibility with older versions of this module the $Text::Soundex::nocode is exported into the caller's namespace as $soundex_nocode.

In scalar context 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 soundex e.g.

  @codes = soundex qw(Mike Stok);

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

If you wish to use Text::Soundex for searching for your name in one of the US Censuses made publicly available, you must instruct the module of your intentions by doing one of the following:

    # First method:
    use Text::Soundex qw(:NARA-Ruleset);
    $code = soundex($name);

    # Second method:
    use Text::Soundex qw(soundex_nara);
    $code = soundex_nara($name);

This is necessary, as the algorithm used by the US Censuses is slightly different than that defined by Knuth and others. The descrepancy can be shown using the name "Ashcraft":

    print soundex("Ashcraft"), "\n";       # prints: A226
    print soundex_nara("Ashcraft"), "\n";  # prints: A261

Their is also a speed hit involved when using the NARA ruleset. (The encoding is slightly more complicated)

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'

UNDERNEATH THE COVERS (a word from Mark)

To ease use for the user, the XS version is transparently accessible via soundex() when it exists for the current platform. Basically what this means is that if you are on a platform with XS code compiled, the call to soundex() will complete about 7X faster. If for whatever reason you care, and you want to choose which code to use, I have provided access to the individual calls.

     # The following calls are split up by functionality.

     # Always uses the 100% perl version.
     ... = Text::Soundex::soundex_noxs(...);   

     # Always uses the XS version. (7X faster)
     ... = Text::Soundex::soundex_xs(...);

     # Use the XS version if possible, otherwise
     # it will revert to the 100% perl version.
     ... = Text::Soundex::soundex(...);
   

LIMITATIONS

As the soundex algorithm was originally used a 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 Hilbert and Heilbronn end up with a soundex code of H416.

AUTHOR

This code was originally implemented by Mike Stok (mike@stok.co.uk) as an example of unreadable perl 4 code and refined into a library. The code is now maintained by Mark Mielke <markm@nortelnetworks.com> who recast the code and made it speedy in 1997. Mark has since added the XS code to accomplish the encoding at a speed upwards of 7X faster. Please report any bugs or other to Mark Mielke <markm@nortelnetworks.com>.

Ian Phillips (ian@pipex.net) and Rich Pinder (rpinder@hsc.usc.edu) supplied ideas and spotted mistakes for v1.x.

Dave Carlson (dcarlsen@csranet.com) made the request for the NARA ruleset to be included. The ruleset is named "NARA", as the descrepancy was discovered due to the fact that it was the NARA soundex machine that was producing "invalid" codes in certain cases. The NARA soundex page can be viewed at: http://www.nara.gov/genealogy/soundex/soundex.html

cpanm Text::Soundex

perl -MCPAN -e shell
install Text::Soundex