head	1.8;
access;
symbols
	REL9_0_0:1.5.14.2
	REL9_1_ALPHA1:1.8
	REL9_0_RC1:1.5.14.2
	REL9_0_BETA4:1.5.14.1
	REL9_0_STABLE:1.5.0.14
	REL9_0_BETA3:1.5
	REL9_0_BETA2:1.5
	REL8_3_11:1.3
	REL8_4_4:1.5
	REL9_0_BETA1:1.5
	REL9_0_ALPHA5_BRANCH:1.5.0.12
	REL9_0_ALPHA5:1.5
	REL8_3_10:1.3
	REL8_4_3:1.5
	REL9_0_ALPHA4:1.5
	REL9_0_ALPHA4_BRANCH:1.5.0.10
	REL8_5_ALPHA3:1.5
	REL8_5_ALPHA3_BRANCH:1.5.0.8
	REL8_3_9:1.3
	REL8_4_2:1.5
	REL8_5_ALPHA2:1.5
	REL8_5_ALPHA2_BRANCH:1.5.0.6
	REL8_3_8:1.3
	REL8_4_1:1.5
	REL8_5_ALPHA1:1.5
	REL8_5_ALPHA1_BRANCH:1.5.0.4
	REL8_4_STABLE:1.5.0.2
	REL8_4_0:1.5
	REL8_4_RC2:1.5
	REL8_4_RC1:1.5
	REL8_4_BETA2:1.5
	REL8_4_BETA1:1.5
	REL8_3_7:1.3
	REL8_3_6:1.3
	REL8_3_5:1.3
	REL8_3_4:1.3
	REL8_3_3:1.3
	REL8_3_2:1.3
	REL8_3_1:1.3
	REL8_3_STABLE:1.3.0.2
	REL8_3_0:1.3
	REL8_3_RC2:1.3
	REL8_3_RC1:1.3
	REL8_3_BETA4:1.1
	REL8_3_BETA3:1.1;
locks; strict;
comment	@# @;


1.8
date	2010.08.17.04.37.20;	author petere;	state Exp;
branches;
next	1.7;

1.7
date	2010.08.02.23.20.23;	author rhaas;	state Exp;
branches;
next	1.6;

1.6
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.5;

1.5
date	2009.04.06.15.43.00;	author tgl;	state Exp;
branches
	1.5.14.1;
next	1.4;

1.4
date	2008.04.03.21.13.07;	author tgl;	state Exp;
branches;
next	1.3;

1.3
date	2007.12.06.04.12.10;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2007.12.03.23.49.50;	author tgl;	state Exp;
branches;
next	1.1;

1.1
date	2007.11.10.23.30.46;	author momjian;	state Exp;
branches;
next	;

1.5.14.1
date	2010.07.29.19.34.36;	author petere;	state Exp;
branches;
next	1.5.14.2;

1.5.14.2
date	2010.08.17.04.37.16;	author petere;	state Exp;
branches;
next	;


desc
@@


1.8
log
@Spell and markup checking
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/fuzzystrmatch.sgml,v 1.7 2010/08/02 23:20:23 rhaas Exp $ -->

<sect1 id="fuzzystrmatch">
 <title>fuzzystrmatch</title>

 <indexterm zone="fuzzystrmatch">
  <primary>fuzzystrmatch</primary>
 </indexterm>

 <para>
  The <filename>fuzzystrmatch</> module provides several
  functions to determine similarities and distance between strings.
 </para>

 <caution>
  <para>
   At present, the <function>soundex</>, <function>metaphone</>,
   <function>dmetaphone</>, and <function>dmetaphone_alt</> functions do
   not work well with multibyte encodings (such as UTF-8).
  </para>
 </caution>

 <sect2>
  <title>Soundex</title>

  <para>
   The Soundex system is a method of matching similar-sounding names
   by converting them to the same code.  It was initially used by the
   United States Census in 1880, 1900, and 1910.  Note that Soundex
   is not very useful for non-English names.
  </para>

  <para>
   The <filename>fuzzystrmatch</> module provides two functions
   for working with Soundex codes:
  </para>

<synopsis>
soundex(text) returns text
difference(text, text) returns int
</synopsis>

  <para>
   The <function>soundex</> function converts a string to its Soundex code.
   The <function>difference</> function converts two strings to their Soundex
   codes and then reports the number of matching code positions.  Since
   Soundex codes have four characters, the result ranges from zero to four,
   with zero being no match and four being an exact match.  (Thus, the
   function is misnamed &mdash; <function>similarity</> would have been
   a better name.)
  </para>

  <para>
   Here are some usage examples:
  </para>

<programlisting>
SELECT soundex('hello world!');

SELECT soundex('Anne'), soundex('Ann'), difference('Anne', 'Ann');
SELECT soundex('Anne'), soundex('Andrew'), difference('Anne', 'Andrew');
SELECT soundex('Anne'), soundex('Margaret'), difference('Anne', 'Margaret');

CREATE TABLE s (nm text);

INSERT INTO s VALUES ('john');
INSERT INTO s VALUES ('joan');
INSERT INTO s VALUES ('wobbly');
INSERT INTO s VALUES ('jack');

SELECT * FROM s WHERE soundex(nm) = soundex('john');

SELECT * FROM s WHERE difference(s.nm, 'john') &gt; 2;
</programlisting>
 </sect2>

 <sect2>
  <title>Levenshtein</title>

  <para>
   This function calculates the Levenshtein distance between two strings:
  </para>

<synopsis>
levenshtein(text source, text target, int ins_cost, int del_cost, int sub_cost) returns int
levenshtein(text source, text target) returns int
</synopsis>

  <para>
   Both <literal>source</literal> and <literal>target</literal> can be any
   non-null string, with a maximum of 255 bytes.  The cost parameters
   specify how much to charge for a character insertion, deletion, or
   substitution, respectively.  You can omit the cost parameters, as in
   the second version of the function; in that case they all default to 1.
  </para>

  <para>
   Examples:
  </para>

<screen>
test=# SELECT levenshtein('GUMBO', 'GAMBOL');
 levenshtein
-------------
           2
(1 row)

test=# SELECT levenshtein('GUMBO', 'GAMBOL', 2,1,1);
 levenshtein
-------------
           3
(1 row)
</screen>
 </sect2>

 <sect2>
  <title>Metaphone</title>

  <para>
   Metaphone, like Soundex, is based on the idea of constructing a
   representative code for an input string.  Two strings are then
   deemed similar if they have the same codes.
  </para>

  <para>
   This function calculates the metaphone code of an input string:
  </para>

<synopsis>
metaphone(text source, int max_output_length) returns text
</synopsis>

  <para>
   <literal>source</literal> has to be a non-null string with a maximum of
   255 characters.  <literal>max_output_length</literal> sets the maximum
   length of the output metaphone code; if longer, the output is truncated
   to this length.
  </para>

  <para>
   Example:
  </para>

<screen>
test=# SELECT metaphone('GUMBO', 4);
 metaphone
-----------
 KM
(1 row)
</screen>
 </sect2>

 <sect2>
  <title>Double Metaphone</title>

  <para>
   The Double Metaphone system computes two <quote>sounds like</> strings
   for a given input string &mdash; a <quote>primary</> and an
   <quote>alternate</>.  In most cases they are the same, but for non-English
   names especially they can be a bit different, depending on pronunciation.
   These functions compute the primary and alternate codes:
  </para>

<synopsis>
dmetaphone(text source) returns text
dmetaphone_alt(text source) returns text
</synopsis>

  <para>
   There is no length limit on the input strings.
  </para>

  <para>
   Example:
  </para>

<screen>
test=# select dmetaphone('gumbo');
 dmetaphone
------------
 KMP
(1 row)
</screen>
 </sect2>

</sect1>
@


1.7
log
@Teach levenshtein() about multi-byte characters.

Based on a patch by, and further ideas from, Alexander Korotkov.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/fuzzystrmatch.sgml,v 1.6 2010/07/29 19:34:40 petere Exp $ -->
d19 1
a19 1
   not work well with multi-byte encodings (such as UTF-8).
@


1.6
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/fuzzystrmatch.sgml,v 1.5 2009/04/06 15:43:00 tgl Exp $ -->
d17 3
a19 2
   At present, <filename>fuzzystrmatch</> does not work well with
   multi-byte encodings (such as UTF-8).
@


1.5
log
@Document the fact that fuzzystrmatch doesn't work in multibyte encodings.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/fuzzystrmatch.sgml,v 1.4 2008/04/03 21:13:07 tgl Exp $ -->
d37 4
a40 4
  <programlisting>
   soundex(text) returns text
   difference(text, text) returns int
  </programlisting>
d56 1
a56 1
  <programlisting>
d73 1
a73 1
  </programlisting>
d83 4
a86 4
  <programlisting>
   levenshtein(text source, text target, int ins_cost, int del_cost, int sub_cost) returns int
   levenshtein(text source, text target) returns int
  </programlisting>
d100 1
a100 1
  <programlisting>
d112 1
a112 1
  </programlisting>
d128 3
a130 3
  <programlisting>
   metaphone(text source, int max_output_length) returns text
  </programlisting>
d143 1
a143 1
  <programlisting>
d149 1
a149 1
  </programlisting>
d163 4
a166 4
  <programlisting>
   dmetaphone(text source) returns text
   dmetaphone_alt(text source) returns text
  </programlisting>
d176 1
a176 1
  <programlisting>
d182 1
a182 1
  </programlisting>
@


1.5.14.1
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/fuzzystrmatch.sgml,v 1.5 2009/04/06 15:43:00 tgl Exp $ -->
d37 4
a40 4
<synopsis>
soundex(text) returns text
difference(text, text) returns int
</synopsis>
d56 1
a56 1
<programlisting>
d73 1
a73 1
</programlisting>
d83 4
a86 4
<synopsis>
levenshtein(text source, text target, int ins_cost, int del_cost, int sub_cost) returns int
levenshtein(text source, text target) returns int
</synopsis>
d100 1
a100 1
<screen>
d112 1
a112 1
</screen>
d128 3
a130 3
<synopsis>
metaphone(text source, int max_output_length) returns text
</synopsis>
d143 1
a143 1
<screen>
d149 1
a149 1
</screen>
d163 4
a166 4
<synopsis>
dmetaphone(text source) returns text
dmetaphone_alt(text source) returns text
</synopsis>
d176 1
a176 1
<screen>
d182 1
a182 1
</screen>
@


1.5.14.2
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/fuzzystrmatch.sgml,v 1.5.14.1 2010/07/29 19:34:36 petere Exp $ -->
d18 1
a18 1
   multibyte encodings (such as UTF-8).
@


1.4
log
@Add a variant of the Levenshtein string-distance function that lets the user
specify the cost values to use, instead of always using 1's.
Volkan Yazici

In passing, remove fuzzystrmatch.h, which contained a bunch of stuff that had
no business being in a .h file; fold it into its only user, fuzzystrmatch.c.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/fuzzystrmatch.sgml,v 1.3 2007/12/06 04:12:10 tgl Exp $ -->
d15 7
@


1.3
log
@Make an editorial pass over the newly SGML-ified contrib documentation.
Fix lots of bad markup, bad English, bad explanations.

This commit covers only about half the contrib modules, but I grow weary...
@
text
@d1 1
a1 1
<!-- $PostgreSQL$ -->
d77 1
d83 4
a86 1
   non-null string, with a maximum of 255 characters.
d90 1
a90 1
   Example:
d99 6
@


1.2
log
@Entity-ify a passel of & < > characters.  Per gripe from Devrim.
@
text
@d1 1
d5 5
a9 1
 
d11 1
a11 1
  This section describes the fuzzystrmatch module which provides different
d17 1
d19 4
a22 5
   The Soundex system is a method of matching similar sounding names
   (or any words) to the same code.  It was initially used by the
   United States Census in 1880, 1900, and 1910, but it has little use
   beyond English names (or the English pronunciation of names), and
   it is not a linguistic tool.
d24 1
d26 2
a27 4
   When comparing two soundex values to determine similarity, the
   difference function reports how close the match is on a scale
   from zero to four, with zero being no match and four being an
   exact match.
d29 16
d46 1
a46 1
   The following are some usage examples:
d48 1
d65 3
a67 1
SELECT a.nm, b.nm FROM s a, s b WHERE soundex(a.nm) = soundex(b.nm) AND a.oid &lt;&gt; b.oid;
d69 2
a70 3
CREATE FUNCTION text_sx_eq(text, text) RETURNS boolean AS
'select soundex($1) = soundex($2)'
LANGUAGE SQL;
d72 3
a74 3
CREATE FUNCTION text_sx_lt(text, text) RETURNS boolean AS
'select soundex($1) &lt; soundex($2)'
LANGUAGE SQL;
d76 3
a78 3
CREATE FUNCTION text_sx_gt(text, text) RETURNS boolean AS
'select soundex($1) &gt; soundex($2)'
LANGUAGE SQL;
d80 4
a83 3
CREATE FUNCTION text_sx_le(text, text) RETURNS boolean AS
'select soundex($1) &lt;= soundex($2)'
LANGUAGE SQL;
d85 3
a87 3
CREATE FUNCTION text_sx_ge(text, text) RETURNS boolean AS
'select soundex($1) &gt;= soundex($2)'
LANGUAGE SQL;
d89 6
a94 13
CREATE FUNCTION text_sx_ne(text, text) RETURNS boolean AS
'select soundex($1) &lt;&gt; soundex($2)'
LANGUAGE SQL;

DROP OPERATOR #= (text, text);

CREATE OPERATOR #= (leftarg=text, rightarg=text, procedure=text_sx_eq, commutator = #=);

SELECT * FROM s WHERE text_sx_eq(nm, 'john');

SELECT * FROM s WHERE s.nm #= 'john';

SELECT * FROM s WHERE difference(s.nm, 'john') &gt; 2;
d99 8
a106 1
  <title>levenshtein</title>
d108 1
a108 1
   This function calculates the levenshtein distance between two strings:
d110 1
d112 1
a112 1
   int levenshtein(text source, text target)
d114 1
d116 4
a119 2
   Both <literal>source</literal> and <literal>target</literal> can be any
   NOT NULL string with a maximum of 255 characters.
d121 1
d125 1
d127 5
a131 1
   SELECT levenshtein('GUMBO','GAMBOL');
d136 2
a137 1
  <title>metaphone</title>
d139 5
a143 1
   This function calculates and returns the metaphone code of an input string:
d145 1
d147 2
a148 1
   text metahpone(text source, int max_output_length)
d150 1
d152 5
a156 4
   <literal>source</literal> has to be a NOT NULL string with a maximum of
   255 characters. <literal>max_output_length</literal> fixes the maximum
   length of the output metaphone code; if longer, the output is truncated 
   to this length.
d158 1
a158 1
  <para>Example</para>
d160 5
a164 1
   SELECT metaphone('GUMBO',4);
@


1.1
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@d44 1
a44 1
SELECT a.nm, b.nm FROM s a, s b WHERE soundex(a.nm) = soundex(b.nm) AND a.oid <> b.oid;
d51 1
a51 1
'select soundex($1) < soundex($2)'
d55 1
a55 1
'select soundex($1) > soundex($2)'
d59 1
a59 1
'select soundex($1) <= soundex($2)'
d63 1
a63 1
'select soundex($1) >= soundex($2)'
d67 1
a67 1
'select soundex($1) <> soundex($2)'
d78 1
a78 1
SELECT * FROM s WHERE difference(s.nm, 'john') > 2;
@

