From cb9d3b1a2c2c59c368f6121a16a9ab928b0ff951 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sun, 23 Nov 2025 00:35:05 -0500
Subject: Added Text.find(text, target, start=1)

---
 api/api.md    | 25 +++++++++++++++++++++++++
 api/text.md   | 25 +++++++++++++++++++++++++
 api/text.yaml | 28 ++++++++++++++++++++++++++++
 3 files changed, 78 insertions(+)

(limited to 'api')

diff --git a/api/api.md b/api/api.md
index 3af79d37..02ad054e 100644
--- a/api/api.md
+++ b/api/api.md
@@ -3904,6 +3904,31 @@ remainder : Text
 assert "hello world".ends_with("world", &remainder) == yes
 assert remainder == "hello "
 
+```
+## Text.find
+
+```tomo
+Text.find : func(text: Text, target: Text, start: Int = 1 -> Int)
+```
+
+Find a substring within a text and return its index, if found.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+text | `Text` | The text to be searched.  | -
+target | `Text` | The target text to find.  | -
+start | `Int` | The index at which to begin searching.  | `1`
+
+**Return:** The index where the first occurrence of `target` appears, or `none` if it is not found.
+
+
+**Example:**
+```tomo
+assert "one two".find("one") == 1
+assert "one two".find("two") == 5
+assert "one two".find("three") == none
+assert "one two".find("o", start=2) == 7
+
 ```
 ## Text.from
 
diff --git a/api/text.md b/api/text.md
index 9bd99529..928cb6ec 100644
--- a/api/text.md
+++ b/api/text.md
@@ -204,6 +204,31 @@ remainder : Text
 assert "hello world".ends_with("world", &remainder) == yes
 assert remainder == "hello "
 
+```
+## Text.find
+
+```tomo
+Text.find : func(text: Text, target: Text, start: Int = 1 -> Int)
+```
+
+Find a substring within a text and return its index, if found.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+text | `Text` | The text to be searched.  | -
+target | `Text` | The target text to find.  | -
+start | `Int` | The index at which to begin searching.  | `1`
+
+**Return:** The index where the first occurrence of `target` appears, or `none` if it is not found.
+
+
+**Example:**
+```tomo
+assert "one two".find("one") == 1
+assert "one two".find("two") == 5
+assert "one two".find("three") == none
+assert "one two".find("o", start=2) == 7
+
 ```
 ## Text.from
 
diff --git a/api/text.yaml b/api/text.yaml
index 2c21fa30..6874bfc8 100644
--- a/api/text.yaml
+++ b/api/text.yaml
@@ -225,6 +225,34 @@ Text.ends_with:
     assert "hello world".ends_with("world", &remainder) == yes
     assert remainder == "hello "
 
+Text.find:
+  short: find a substring
+  description: >
+    Find a substring within a text and return its index, if found.
+  return:
+    type: 'Int'
+    description: >
+      The index where the first occurrence of `target` appears, or `none` if it is not found.
+  args:
+    text:
+      type: 'Text'
+      description: >
+        The text to be searched.
+    target:
+      type: 'Text'
+      description: >
+        The target text to find.
+    start:
+      type: 'Int'
+      default: '1'
+      description: >
+        The index at which to begin searching.
+  example: |
+    assert "one two".find("one") == 1
+    assert "one two".find("two") == 5
+    assert "one two".find("three") == none
+    assert "one two".find("o", start=2) == 7
+
 Text.from:
   short: slice from a starting index
   description: >
-- 
cgit v1.2.3