1Soundex(3) User Contributed Perl Documentation Soundex(3)
2
6 Text::Soundex - Implementation of the soundex algorithm.
7
9 use Text::Soundex;
10 # Original algorithm.
12 $code = soundex($name); # Get the soundex code for a name.
13 @codes = soundex(@names); # Get the list of codes for a list of names.
14 # American Soundex variant (NARA) - Used for US census data.
16 $code = soundex_nara($name); # Get the soundex code for a name.
17 @codes = soundex_nara(@names); # Get the list of codes for a list of names.
18 # Redefine the value that soundex() will return if the input string
20 # contains no identifiable sounds within it.
21 $Text::Soundex::nocode = 'Z000';
22
24 Soundex is a phonetic algorithm for indexing names by sound, as
25 pronounced in English. The goal is for names with the same
26 pronunciation to be encoded to the same representation so that they can
27 be matched despite minor differences in spelling. Soundex is the most
28 widely known of all phonetic algorithms and is often used (incorrectly)
29 as a synonym for "phonetic algorithm". Improvements to Soundex are the
30 basis for many modern phonetic algorithms. (Wikipedia, 2007)
31 This module implements the original soundex algorithm developed by
33 Robert Russell and Margaret Odell, patented in 1918 and 1922, as well
34 as a variation called "American Soundex" used for US census data, and
35 current maintained by the National Archives and Records Administration
36 (NARA).
37 The soundex algorithm may be recognized from Donald Knuth's The Art of
39 Computer Programming. The algorithm described by Knuth is the NARA
40 algorithm.
41 The value returned for strings which have no soundex encoding is
43 defined using $Text::Soundex::nocode. The default value is "undef",
44 however values such as 'Z000' are commonly used alternatives.
45 For backward compatibility with older versions of this module the
47 $Text::Soundex::nocode is exported into the caller's namespace as
48 $soundex_nocode.
49 In scalar context, soundex() returns the soundex code of its first
51 argument. In list context, a list is returned in which each element is
52 the soundex code for the corresponding argument passed to soundex().
53 For example, the following code assigns @codes the value "('M200',
54 'S320')":
55 @codes = soundex qw(Mike Stok);
57 To use "Text::Soundex" to generate codes that can be used to search one
59 of the publically available US Censuses, a variant of the soundex
60 algorithm must be used:
61 use Text::Soundex;
63 $code = soundex_nara($name);
64 An example of where these algorithm differ follows:
66 use Text::Soundex;
68 print soundex("Ashcraft"), "\n"; # prints: A226
69 print soundex_nara("Ashcraft"), "\n"; # prints: A261
70
72 Donald Knuth's examples of names and the soundex codes they map to are
73 listed below:
74 Euler, Ellery -> E460
76 Gauss, Ghosh -> G200
77 Hilbert, Heilbronn -> H416
78 Knuth, Kant -> K530
79 Lloyd, Ladd -> L300
80 Lukasiewicz, Lissajous -> L222
81 so:
83 $code = soundex 'Knuth'; # $code contains 'K530'
85 @list = soundex qw(Lloyd Gauss); # @list contains 'L300', 'G200'
86
88 As the soundex algorithm was originally used a long time ago in the US
89 it considers only the English alphabet and pronunciation. In
90 particular, non-ASCII characters will be ignored. The recommended
91 method of dealing with characters that have accents, or other unicode
92 characters, is to use the Text::Unidecode module available from CPAN.
93 Either use the module explicitly:
94 use Text::Soundex;
96 use Text::Unidecode;
97 print soundex(unidecode("Fran\xE7ais")), "\n"; # Prints "F652\n"
99 Or use the convenient wrapper routine:
101 use Text::Soundex 'soundex_unicode';
103 print soundex_unicode("Fran\xE7ais"), "\n"; # Prints "F652\n"
105 Since the soundex algorithm maps a large space (strings of arbitrary
107 length) onto a small space (single letter plus 3 digits) no inference
108 can be made about the similarity of two strings which end up with the
109 same soundex code. For example, both "Hilbert" and "Heilbronn" end up
110 with a soundex code of "H416".
111
113 This software is copyright (c) 1998-2003 by Mark Mielke.
114 This is free software; you can redistribute it and/or modify it under
116 the same terms as the Perl 5 programming language system itself.
117
119 This module is currently maintain by Mark Mielke ("mark@mielke.cc").
120
122 Version 3 is a significant update to provide support for versions of
123 Perl later than Perl 5.004. Specifically, the XS version of the
124 soundex() subroutine understands strings that are encoded using UTF-8
125 (unicode strings).
126 Version 2 of this module was a re-write by Mark Mielke
128 ("mark@mielke.cc") to improve the speed of the subroutines. The XS
129 version of the soundex() subroutine was introduced in 2.00.
130 Version 1 of this module was written by Mike Stok ("mike@stok.co.uk")
132 and was included into the Perl core library set.
133 Dave Carlsen ("dcarlsen@csranet.com") made the request for the NARA
135 algorithm to be included. The NARA soundex page can be viewed at:
136 "http://www.archives.gov/research/census/soundex.html"
137 Ian Phillips ("ian@pipex.net") and Rich Pinder ("rpinder@hsc.usc.edu")
139 supplied ideas and spotted mistakes for v1.x.
140perl v5.36.0 2023-01-20 Soundex(3)