Added Text.distance(a,b) for text similarity comparisons.

3 files changed, 87 insertions, 0 deletions

diff --git a/api/api.md b/api/api.md
index 9e7c553e..0a2213cb 100644
--- a/api/api.md
+++ b/api/api.md
@@ -3966,6 +3966,33 @@ assert "Amélie".codepoint_names() == [
 ]
 
 ```
+## Text.distance
+
+```tomo
+Text.distance : func(a: Text, b: Text, language: Text = "C" -> Num)
+```
+
+Get an approximate distance between two texts, such that when the distance is small, the texts are similar and when the distance is large, the texts are dissimilar.
+
+The exact distance algorithm is not specified and may be subject to change over time.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+a | `Text` | The first text to compare.  | -
+b | `Text` | The second text to compare.  | -
+language | `Text` | The ISO 639 language code for which character width to use.  | `"C"`
+
+**Return:** The distance between the two texts (larger means more dissimilar).
+
+
+**Example:**
+```tomo
+assert "hello".distance("hello") == 0
+texts := &["goodbye", "hello", "hallo"]
+texts.sort(func(a,b:&Text) a.distance("hello") <> b.distance("hello"))
+assert texts == ["hello", "hallo", "goodbye"]
+
+```
 ## Text.ends_with
 
 ```tomo
diff --git a/api/text.md b/api/text.md
index 928cb6ec..2536ff21 100644
--- a/api/text.md
+++ b/api/text.md
@@ -180,6 +180,33 @@ assert "Amélie".codepoint_names() == [
 ]
 
 ```
+## Text.distance
+
+```tomo
+Text.distance : func(a: Text, b: Text, language: Text = "C" -> Num)
+```
+
+Get an approximate distance between two texts, such that when the distance is small, the texts are similar and when the distance is large, the texts are dissimilar.
+
+The exact distance algorithm is not specified and may be subject to change over time.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+a | `Text` | The first text to compare.  | -
+b | `Text` | The second text to compare.  | -
+language | `Text` | The ISO 639 language code for which character width to use.  | `"C"`
+
+**Return:** The distance between the two texts (larger means more dissimilar).
+
+
+**Example:**
+```tomo
+assert "hello".distance("hello") == 0
+texts := &["goodbye", "hello", "hallo"]
+texts.sort(func(a,b:&Text) a.distance("hello") <> b.distance("hello"))
+assert texts == ["hello", "hallo", "goodbye"]
+
+```
 ## Text.ends_with
 
 ```tomo
diff --git a/api/text.yaml b/api/text.yaml
index 6874bfc8..2af7cae4 100644
--- a/api/text.yaml
+++ b/api/text.yaml
@@ -225,6 +225,39 @@ Text.ends_with:
     assert "hello world".ends_with("world", &remainder) == yes
     assert remainder == "hello "
 
+Text.distance:
+  short: distance between two texts
+  description: >
+    Get an approximate distance between two texts, such that when the distance
+    is small, the texts are similar and when the distance is large, the texts
+    are dissimilar.
+  note: >
+    The exact distance algorithm is not specified and may be subject to change
+    over time.
+  return:
+    type: 'Num'
+    description: >
+      The distance between the two texts (larger means more dissimilar).
+  args:
+    a:
+      type: 'Text'
+      description: >
+        The first text to compare.
+    b:
+      type: 'Text'
+      description: >
+        The second text to compare.
+    language:
+      type: 'Text'
+      default: '"C"'
+      description: >
+        The ISO 639 language code for which character width to use.
+  example: |
+    assert "hello".distance("hello") == 0
+    texts := &["goodbye", "hello", "hallo"]
+    texts.sort(func(a,b:&Text) a.distance("hello") <> b.distance("hello"))
+    assert texts == ["hello", "hallo", "goodbye"]
+
 Text.find:
   short: find a substring
   description: >