From df844946f7d45fa39acf040eb8922ab658f9f5dd Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Wed, 4 Sep 2024 00:34:27 -0400
Subject: Add Text:matches() for convenience and performance

---
 docs/text.md | 41 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

(limited to 'docs/text.md')

diff --git a/docs/text.md b/docs/text.md
index adf12dd1..b585676b 100644
--- a/docs/text.md
+++ b/docs/text.md
@@ -274,9 +274,10 @@ functions that would normally be handled by a more extensive API:
 Text.has(pattern:Pattern)->Bool
 Text.find(pattern:Pattern, start=1, length=!&Int64?)->Int
 Text.find_all(pattern:Pattern)->[Text]
-Text.split(pattern:Pattern)->[Text]
+Text.matches(pattern:Pattern)->Bool
 Text.replace(pattern:Pattern, replacement:Text, placeholder:Pattern=$//)->[Text]
 Text.replace_all(replacements:{Pattern:Text}, placeholder:Pattern=$//)->[Text]
+Text.split(pattern:Pattern)->[Text]
 ```
 
 See [Text Functions](#Text-Functions) for the full API documentation.
@@ -708,13 +709,13 @@ has(text: Text, pattern: Text) -> Bool
 
 **Example:**  
 ```tomo
->> "hello world":has("wo")
+>> "hello world":has($/wo/)
 = yes
->> "hello world":has("{alpha}")
+>> "hello world":has($/{alpha}/)
 = yes
->> "hello world":has("{digit}")
+>> "hello world":has($/{digit}/)
 = no
->> "hello world":has("{start}he")
+>> "hello world":has($/{start}he/)
 = yes
 ```
 
@@ -805,6 +806,36 @@ The lowercase version of the text.
 
 ---
 
+## `matches`
+
+**Description:**  
+Checks if the `Text` matches target pattern (see: [Patterns](#Patterns)).
+
+**Usage:**  
+```tomo
+matches(text: Text, pattern: Text) -> Bool
+```
+
+**Parameters:**
+
+- `text`: The text to be searched.
+- `pattern`: The pattern to search for.
+
+**Returns:**  
+`yes` if the target pattern is found, `no` otherwise.
+
+**Example:**  
+```tomo
+>> "Hello":matches($/{id}/)
+= yes
+>> "Hello":matches($/{upper}/)
+= no
+>> "Hello":matches($/{lower}/)
+= no
+```
+
+---
+
 ## `quoted`
 
 **Description:**  
-- 
cgit v1.2.3