.. index:: single: string_distance(Representation)
.. _string_distance/1:

.. rst-class:: right

**object**

``string_distance(Representation)``
===================================

* ``Representation`` - String representation. Valid values are ``atom``, ``codes``, and ``chars``.


String distance predicates.

| **Availability:** 
|    ``logtalk_load(string_distance(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-02-05

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Uses:**
|    :ref:`integer <integer/0>`
|    :ref:`list <list/0>`
|    :ref:`set <set/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: levenshtein/3
.. _string_distance/1::levenshtein/3:

``levenshtein/3``
^^^^^^^^^^^^^^^^^

Computes the Levenshtein distance between two strings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``levenshtein(String1,String2,Distance)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
|        ``Distance`` - Minimum number of single-character edits (insertions, deletions, substitutions) to transform ``String1`` into ``String2``.
| **Mode and number of proofs:**
|    ``levenshtein(+text,+text,-integer)`` - ``one``


------------

.. index:: damerau_levenshtein/3
.. _string_distance/1::damerau_levenshtein/3:

``damerau_levenshtein/3``
^^^^^^^^^^^^^^^^^^^^^^^^^

Computes the Damerau-Levenshtein distance between two strings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``damerau_levenshtein(String1,String2,Distance)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
|        ``Distance`` - Minimum number of edits (insertions, deletions, substitutions, and adjacent transpositions) to transform ``String1`` into ``String2``.
| **Mode and number of proofs:**
|    ``damerau_levenshtein(+text,+text,-integer)`` - ``one``


------------

.. index:: hamming/3
.. _string_distance/1::hamming/3:

``hamming/3``
^^^^^^^^^^^^^

Computes the Hamming distance between two strings of equal length. Fails if the strings differ in length.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``hamming(String1,String2,Distance)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string (must have the same length as ``String1``).
|        ``Distance`` - Number of positions at which the corresponding characters differ.
| **Mode and number of proofs:**
|    ``hamming(+text,+text,-integer)`` - ``zero_or_one``


------------

.. index:: jaro/3
.. _string_distance/1::jaro/3:

``jaro/3``
^^^^^^^^^^

Computes the Jaro similarity score between two strings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``jaro(String1,String2,Similarity)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
|        ``Similarity`` - A value between 0.0 (completely different) and 1.0 (identical), based on matching characters and transpositions.
| **Mode and number of proofs:**
|    ``jaro(+text,+text,-float)`` - ``one``


------------

.. index:: jaro_winkler/3
.. _string_distance/1::jaro_winkler/3:

``jaro_winkler/3``
^^^^^^^^^^^^^^^^^^

Computes the Jaro-Winkler similarity score between two strings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``jaro_winkler(String1,String2,Similarity)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
|        ``Similarity`` - A value between 0.0 and 1.0. Extends Jaro similarity with a prefix bonus: strings sharing a common prefix are scored higher.
| **Mode and number of proofs:**
|    ``jaro_winkler(+text,+text,-float)`` - ``one``


------------

.. index:: edit_similarity/3
.. _string_distance/1::edit_similarity/3:

``edit_similarity/3``
^^^^^^^^^^^^^^^^^^^^^

Computes the edit similarity score between two strings using Levenshtein distance.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``edit_similarity(String1,String2,Similarity)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
|        ``Similarity`` - A value between 0.0 and 1.0 computed as 1 - (edit distance / max length of the two strings).
| **Mode and number of proofs:**
|    ``edit_similarity(+text,+text,-float)`` - ``one``


------------

.. index:: edit_similarity/4
.. _string_distance/1::edit_similarity/4:

``edit_similarity/4``
^^^^^^^^^^^^^^^^^^^^^

Computes the edit similarity score between two strings using the given algorithm.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``edit_similarity(Algorithm,String1,String2,Similarity)``
|        ``Algorithm`` - Edit distance algorithm. Valid values are ``levenshtein``, ``damerau_levenshtein``, ``hamming``, and ``longest_common_subsequence``.
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
|        ``Similarity`` - A value between 0.0 and 1.0 computed as 1 - (edit distance / max length of the two strings).
| **Mode and number of proofs:**
|    ``edit_similarity(+atom,+text,+text,-float)`` - ``one``


------------

.. index:: longest_common_subsequence_length/3
.. _string_distance/1::longest_common_subsequence_length/3:

``longest_common_subsequence_length/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes the length of the Longest Common Subsequence between two strings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``longest_common_subsequence_length(String1,String2,Length)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
|        ``Length`` - Length of the longest subsequence common to both strings (characters need not be contiguous).
| **Mode and number of proofs:**
|    ``longest_common_subsequence_length(+text,+text,-integer)`` - ``one``


------------

.. index:: longest_common_subsequence/3
.. _string_distance/1::longest_common_subsequence/3:

``longest_common_subsequence/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes the Longest Common Subsequence itself between two strings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``longest_common_subsequence(String1,String2,Subsequence)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
|        ``Subsequence`` - The longest subsequence common to both strings (characters need not be contiguous). If multiple exist, one is returned nondeterministically.
| **Mode and number of proofs:**
|    ``longest_common_subsequence(+text,+text,-atom)`` - ``one``


------------

.. index:: longest_common_substring/3
.. _string_distance/1::longest_common_substring/3:

``longest_common_substring/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Computes the longest contiguous common substring between two strings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``longest_common_substring(String1,String2,Substring)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
|        ``Substring`` - The longest contiguous substring shared by both strings. If multiple exist, one is returned nondeterministically.
| **Mode and number of proofs:**
|    ``longest_common_substring(+text,+text,-atom)`` - ``one``


------------

.. index:: cosine_similarity/3
.. _string_distance/1::cosine_similarity/3:

``cosine_similarity/3``
^^^^^^^^^^^^^^^^^^^^^^^

Computes the cosine similarity between two token lists.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``cosine_similarity(Tokens1,Tokens2,Similarity)``
|        ``Tokens1`` - First token list (e.g., list of words or character n-grams).
|        ``Tokens2`` - Second token list.
|        ``Similarity`` - A value between 0.0 and 1.0 representing the cosine of the angle between the two token vectors.
| **Mode and number of proofs:**
|    ``cosine_similarity(+list(text),+list(text),-float)`` - ``one``


------------

.. index:: jaccard_index/3
.. _string_distance/1::jaccard_index/3:

``jaccard_index/3``
^^^^^^^^^^^^^^^^^^^

Computes the Jaccard index (similarity) between two token lists.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``jaccard_index(Tokens1,Tokens2,Index)``
|        ``Tokens1`` - First token list (e.g., list of words or character n-grams).
|        ``Tokens2`` - Second token list.
|        ``Index`` - A value between 0.0 (no overlap) and 1.0 (identical sets), computed as ``|intersection| / |union|``.
| **Mode and number of proofs:**
|    ``jaccard_index(+list(text),+list(text),-float)`` - ``one``


------------

.. index:: soundex/2
.. _string_distance/1::soundex/2:

``soundex/2``
^^^^^^^^^^^^^

Computes the Soundex phonetic encoding for a string.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``soundex(String,Encoding)``
|        ``String`` - Input string (typically a name).
|        ``Encoding`` - A four-character Soundex code representing the phonetic encoding.
| **Mode and number of proofs:**
|    ``soundex(+text,-atom)`` - ``one``


------------

.. index:: soundex_match/2
.. _string_distance/1::soundex_match/2:

``soundex_match/2``
^^^^^^^^^^^^^^^^^^^

Succeeds if two strings share the same Soundex code.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``soundex_match(String1,String2)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
| **Mode and number of proofs:**
|    ``soundex_match(+text,+text)`` - ``one``


------------

.. index:: metaphone/2
.. _string_distance/1::metaphone/2:

``metaphone/2``
^^^^^^^^^^^^^^^

Computes the Metaphone phonetic key for a string.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``metaphone(String,Encoding)``
|        ``String`` - Input string (typically a name).
|        ``Encoding`` - The Metaphone phonetic encoding, a more accurate phonetic encoding than Soundex.
| **Mode and number of proofs:**
|    ``metaphone(+text,-atom)`` - ``one``


------------

.. index:: metaphone_match/2
.. _string_distance/1::metaphone_match/2:

``metaphone_match/2``
^^^^^^^^^^^^^^^^^^^^^

Succeeds if two strings share the same Metaphone key.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``metaphone_match(String1,String2)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
| **Mode and number of proofs:**
|    ``metaphone_match(+text,+text)`` - ``one``


------------

.. index:: double_metaphone/3
.. _string_distance/1::double_metaphone/3:

``double_metaphone/3``
^^^^^^^^^^^^^^^^^^^^^^

Computes the Double Metaphone encoding of a text, returning both primary and alternative encodings.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``double_metaphone(Text,Primary,Alternative)``
|        ``Text`` - Input string (typically a name).
|        ``Primary`` - Primary Double Metaphone encoding.
|        ``Alternative`` - Alternative Double Metaphone encoding.
| **Mode and number of proofs:**
|    ``double_metaphone(+text,-atom,-atom)`` - ``one``


------------

.. index:: double_metaphone_match/2
.. _string_distance/1::double_metaphone_match/2:

``double_metaphone_match/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Succeeds if the Double Metaphone encodings of two texts match (either primary or alternative encodings).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``double_metaphone_match(String1,String2)``
|        ``String1`` - First input string.
|        ``String2`` - Second input string.
| **Mode and number of proofs:**
|    ``double_metaphone_match(+text,+text)`` - ``zero_or_one``


------------

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)