From 2b7e96835e75e0d153e7f993d1c4fc2add452ddd Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sun, 8 Feb 2026 22:47:02 -0500
Subject: Added Text.distance(a,b) for text similarity comparisons.

---
 api/api.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

(limited to 'api/api.md')

diff --git a/api/api.md b/api/api.md
index 9e7c553e..0a2213cb 100644
--- a/api/api.md
+++ b/api/api.md
@@ -3965,6 +3965,33 @@ assert "Amélie".codepoint_names() == [
     "LATIN SMALL LETTER E",
 ]
 
+```
+## 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
 
-- 
cgit v1.2.3