From c72b0406a32ffc3f04324f7b6c321486762fca41 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sat, 16 Aug 2025 17:21:01 -0400
Subject: Improved parsing and prefix/suffix matching using a `remainder`
 parameter

---
 api/bytes.md | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

(limited to 'api/bytes.md')

diff --git a/api/bytes.md b/api/bytes.md
index 908d78e2..fe8dddb1 100644
--- a/api/bytes.md
+++ b/api/bytes.md
@@ -86,7 +86,7 @@ high | `Byte` | The upper bound to check (inclusive).  | -
 ## Byte.parse
 
 ```tomo
-Byte.parse : func(text: Text -> Byte?)
+Byte.parse : func(text: Text, remainder: &Text? = none -> Byte?)
 ```
 
 Parse a byte literal from text.
@@ -94,6 +94,7 @@ Parse a byte literal from text.
 Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The text to parse.  | -
+remainder | `&Text?` | If non-none, this argument will be set to the remainder of the text after the matching part. If none, parsing will only succeed if the entire text matches.  | `none`
 
 **Return:** The byte parsed from the text, if successful, otherwise `none`.
 
@@ -101,9 +102,17 @@ text | `Text` | The text to parse.  | -
 **Example:**
 ```tomo
 >> Byte.parse("5")
-= Byte(5)?
+= Byte(5) : Byte?
 >> Byte.parse("asdf")
-= none
+= none : Byte?
+
+>> Byte.parse("123xyz")
+= none : Byte?
+remainder : Text
+>> Byte.parse("123xyz", &remainder)
+= Byte(123) : Byte?
+>> remainder
+= "xyz"
 
 ```
 ## Byte.to
-- 
cgit v1.2.3