Improved parsing and prefix/suffix matching using a `remainder`

parameter

11 files changed, 268 insertions, 95 deletions

diff --git a/api/api.md b/api/api.md
index 9711ab44..09d24e73 100644
--- a/api/api.md
+++ b/api/api.md
@@ -186,7 +186,7 @@ sleep(1.5)
 ## Bool.parse
 
 ```tomo
-Bool.parse : func(text: Text -> Bool?)
+Bool.parse : func(text: Text, remainder: &Text? = none -> Bool?)
 ```
 
 Converts a text representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`.
@@ -194,6 +194,7 @@ Converts a text representation of a boolean value into a boolean. Acceptable boo
 Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The string containing the boolean value.  | -
+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:** `yes` if the string matches a recognized truthy boolean value; otherwise return `no`.
 
@@ -207,6 +208,14 @@ text | `Text` | The string containing the boolean value.  | -
 >> Bool.parse("???")
 = none : Bool?
 
+>> Bool.parse("yesJUNK")
+= none : Bool?
+remainder : Text
+>> Bool.parse("yesJUNK", &remainder)
+= yes : Bool?
+>> remainder
+= "JUNK"
+
 ```
 
 # Byte
@@ -293,7 +302,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.
@@ -301,6 +310,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`.
 
@@ -308,9 +318,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
@@ -614,7 +632,7 @@ stop if i == 10
 ## Int.parse
 
 ```tomo
-Int.parse : func(text: Text -> Int?)
+Int.parse : func(text: Text, remainder: &Text? = none -> Int?)
 ```
 
 Converts a text representation of an integer into an integer.
@@ -622,6 +640,7 @@ Converts a text representation of an integer into an integer.
 Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The text containing the integer.  | -
+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 integer represented by the text. If the given text contains a value outside of the representable range or if the entire text can't be parsed as an integer, `none` will be returned.
 
@@ -633,6 +652,14 @@ text | `Text` | The text containing the integer.  | -
 >> Int.parse("0xFF")
 = 255 : Int?
 
+>> Int.parse("123xyz")
+= none
+remainder : Text
+>> Int.parse("123xyz", &remainder)
+= 123 : Int?
+>> remainder
+= "xyz"
+
 # Can't parse:
 >> Int.parse("asdf")
 = none : Int?
@@ -2250,7 +2277,7 @@ y | `Num` | The direction towards which to find the next representable value.  |
 ## Num.parse
 
 ```tomo
-Num.parse : func(text: Text -> Num?)
+Num.parse : func(text: Text, remainder: &Text? = none -> Num?)
 ```
 
 Converts a text representation of a number into a floating-point number.
@@ -2258,6 +2285,7 @@ Converts a text representation of a number into a floating-point number.
 Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The text containing the number.  | -
+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 number represented by the text or `none` if the entire text can't be parsed as a number.
 
@@ -2265,9 +2293,17 @@ text | `Text` | The text containing the number.  | -
 **Example:**
 ```tomo
 >> Num.parse("3.14")
-= 3.14
+= 3.14 : Num?
 >> Num.parse("1e3")
-= 1000
+= 1000 : Num?
+
+>> Num.parse("1.5junk")
+= none : Num?
+remainder : Text
+>> Num.parse("1.5junk", &remainder)
+= 1.5 : Num?
+>> remainder
+= "junk"
 
 ```
 ## Num.percent
@@ -4218,7 +4254,7 @@ text | `Text` | The text from which to extract codepoint names.  | -
 ## Text.ends_with
 
 ```tomo
-Text.ends_with : func(text: Text, suffix: Text -> Bool)
+Text.ends_with : func(text: Text, suffix: Text, remainder: &Text? = none -> Bool)
 ```
 
 Checks if the `Text` ends with a literal suffix text.
@@ -4227,6 +4263,7 @@ Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The text to be searched.  | -
 suffix | `Text` | The literal suffix text to check for.  | -
+remainder | `&Text?` | If non-none, this value will be set to the rest of the text up to the trailing suffix. If the suffix is not found, this value will be set to the original text.  | `none`
 
 **Return:** `yes` if the text has the target, `no` otherwise.
 
@@ -4235,6 +4272,11 @@ suffix | `Text` | The literal suffix text to check for.  | -
 ```tomo
 >> "hello world".ends_with("world")
 = yes
+remainder : Text
+>> "hello world".ends_with("world", &remainder)
+= yes
+>> remainder
+= "hello "
 
 ```
 ## Text.from
@@ -4712,7 +4754,7 @@ delimiters | `Text` | A text containing delimiters to use for splitting the text
 ## Text.starts_with
 
 ```tomo
-Text.starts_with : func(text: Text, prefix: Text -> Bool)
+Text.starts_with : func(text: Text, prefix: Text, remainder: &Text? = none -> Bool)
 ```
 
 Checks if the `Text` starts with a literal prefix text.
@@ -4721,6 +4763,7 @@ Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The text to be searched.  | -
 prefix | `Text` | The literal prefix text to check for.  | -
+remainder | `&Text?` | If non-none, this value will be set to the rest of the text after the prefix. If the prefix is not found, this value will be set to the original text.  | `none`
 
 **Return:** `yes` if the text has the given prefix, `no` otherwise.
 
@@ -4729,6 +4772,11 @@ prefix | `Text` | The literal prefix text to check for.  | -
 ```tomo
 >> "hello world".starts_with("hello")
 = yes
+remainder : Text
+>> "hello world".starts_with("hello", &remainder)
+= yes
+>> remainder
+= " world"
 
 ```
 ## Text.title
diff --git a/api/booleans.md b/api/booleans.md
index d45be505..ab08909d 100644
--- a/api/booleans.md
+++ b/api/booleans.md
@@ -6,7 +6,7 @@
 ## Bool.parse
 
 ```tomo
-Bool.parse : func(text: Text -> Bool?)
+Bool.parse : func(text: Text, remainder: &Text? = none -> Bool?)
 ```
 
 Converts a text representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`.
@@ -14,6 +14,7 @@ Converts a text representation of a boolean value into a boolean. Acceptable boo
 Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The string containing the boolean value.  | -
+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:** `yes` if the string matches a recognized truthy boolean value; otherwise return `no`.
 
@@ -27,4 +28,12 @@ text | `Text` | The string containing the boolean value.  | -
 >> Bool.parse("???")
 = none : Bool?
 
+>> Bool.parse("yesJUNK")
+= none : Bool?
+remainder : Text
+>> Bool.parse("yesJUNK", &remainder)
+= yes : Bool?
+>> remainder
+= "JUNK"
+
 ```
diff --git a/api/booleans.yaml b/api/booleans.yaml
index 0831ac18..1d9d68fd 100644
--- a/api/booleans.yaml
+++ b/api/booleans.yaml
@@ -13,6 +13,12 @@ Bool.parse:
       type: 'Text'
       description: >
         The string containing the boolean value.
+    remainder:
+      type: '&Text?'
+      default: 'none'
+      description: >
+        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.
   example: |
     >> Bool.parse("yes")
     = yes : Bool?
@@ -20,4 +26,11 @@ Bool.parse:
     = no : Bool?
     >> Bool.parse("???")
     = none : Bool?
-    
+
+    >> Bool.parse("yesJUNK")
+    = none : Bool?
+    remainder : Text
+    >> Bool.parse("yesJUNK", &remainder)
+    = yes : Bool?
+    >> remainder
+    = "JUNK"
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
diff --git a/api/bytes.yaml b/api/bytes.yaml
index 2785513d..f7b8cb5d 100644
--- a/api/bytes.yaml
+++ b/api/bytes.yaml
@@ -54,7 +54,7 @@ Byte.hex:
   example: |
     >> Byte(18).hex()
     = "0x12"
-    
+
 Byte.is_between:
   short: test if inside a range
   description: >
@@ -83,7 +83,7 @@ Byte.is_between:
     = no
     >> Byte(7).is_between(1, 7)
     = yes
-    
+
 Byte.parse:
   short: convert text to a byte
   description: >
@@ -97,12 +97,26 @@ Byte.parse:
       type: 'Text'
       description: >
         The text to parse.
+    remainder:
+      type: '&Text?'
+      default: 'none'
+      description: >
+        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.
   example: |
     >> 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:
   short: iterate over a range of bytes
   description: >
@@ -132,7 +146,7 @@ Byte.to:
     = [Byte(2), Byte(3), Byte(4), Byte(5)]
     >> [x for x in Byte(5).to(2)]
     = [Byte(5), Byte(4), Byte(3), Byte(2)]
-    
+
     >> [x for x in Byte(2).to(5, step=2)]
     = [Byte(2), Byte(4)]
-    
+
diff --git a/api/integers.md b/api/integers.md
index efb891bf..6468589e 100644
--- a/api/integers.md
+++ b/api/integers.md
@@ -272,7 +272,7 @@ stop if i == 10
 ## Int.parse
 
 ```tomo
-Int.parse : func(text: Text -> Int?)
+Int.parse : func(text: Text, remainder: &Text? = none -> Int?)
 ```
 
 Converts a text representation of an integer into an integer.
@@ -280,6 +280,7 @@ Converts a text representation of an integer into an integer.
 Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The text containing the integer.  | -
+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 integer represented by the text. If the given text contains a value outside of the representable range or if the entire text can't be parsed as an integer, `none` will be returned.
 
@@ -291,6 +292,14 @@ text | `Text` | The text containing the integer.  | -
 >> Int.parse("0xFF")
 = 255 : Int?
 
+>> Int.parse("123xyz")
+= none
+remainder : Text
+>> Int.parse("123xyz", &remainder)
+= 123 : Int?
+>> remainder
+= "xyz"
+
 # Can't parse:
 >> Int.parse("asdf")
 = none : Int?
diff --git a/api/integers.yaml b/api/integers.yaml
index a91a21ce..4d7e423f 100644
--- a/api/integers.yaml
+++ b/api/integers.yaml
@@ -14,7 +14,7 @@ Int.abs:
   example: |
     >> (-10).abs()
     = 10
-    
+
 Int.choose:
   short: binomial coefficient
   description: >
@@ -38,7 +38,7 @@ Int.choose:
   example: |
     >> (4).choose(2)
     = 6
-    
+
 Int.clamped:
   short: clamp an integer
   description: >
@@ -64,7 +64,7 @@ Int.clamped:
   example: |
     >> (2).clamped(5, 10)
     = 5
-    
+
 Int.factorial:
   short: factorial
   description: >
@@ -147,7 +147,7 @@ Int.hex:
   example: |
     >> (255).hex(digits=4, uppercase=yes, prefix=yes)
     = "0x00FF"
-    
+
 Int.is_between:
   short: test if an int is in a range
   description: >
@@ -176,7 +176,7 @@ Int.is_between:
     = no
     >> (7).is_between(1, 7)
     = yes
-    
+
 Int.is_prime:
   short: check if an integer is prime
   description: >
@@ -205,7 +205,7 @@ Int.is_prime:
     = yes
     >> (6).is_prime()
     = no
-    
+
 Int.next_prime:
   short: get the next prime
   description: >
@@ -227,7 +227,7 @@ Int.next_prime:
   example: |
     >> (11).next_prime()
     = 13
-    
+
 Int.octal:
   short: convert to octal
   description: >
@@ -254,7 +254,7 @@ Int.octal:
   example: |
     >> (64).octal(digits=4, prefix=yes)
     = "0o0100"
-    
+
 Int.onward:
   short: iterate from a number onward
   description: >
@@ -281,7 +281,7 @@ Int.onward:
     stop if i == 10
     >> nums[]
     = [5, 6, 7, 8, 9, 10]
-    
+
 Int.parse:
   short: convert text to integer
   description: >
@@ -297,20 +297,34 @@ Int.parse:
       type: 'Text'
       description: >
         The text containing the integer.
+    remainder:
+      type: '&Text?'
+      default: 'none'
+      description: >
+        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.
   example: |
     >> Int.parse("123")
     = 123 : Int?
     >> Int.parse("0xFF")
     = 255 : Int?
-    
+
+    >> Int.parse("123xyz")
+    = none
+    remainder : Text
+    >> Int.parse("123xyz", &remainder)
+    = 123 : Int?
+    >> remainder
+    = "xyz"
+
     # Can't parse:
     >> Int.parse("asdf")
     = none : Int?
-    
+
     # Outside valid range:
     >> Int8.parse("9999999")
     = none : Int8?
-    
+
 Int.prev_prime:
   short: get the previous prime
   description: >
@@ -334,7 +348,7 @@ Int.prev_prime:
   example: |
     >> (11).prev_prime()
     = 7
-    
+
 Int.sqrt:
   short: square root
   description: >
@@ -353,7 +367,7 @@ Int.sqrt:
     = 4
     >> (17).sqrt()
     = 4
-    
+
 Int.to:
   short: iterate a range of integers
   description: >
@@ -383,7 +397,7 @@ Int.to:
     = [2, 3, 4, 5]
     >> [x for x in (5).to(2)]
     = [5, 4, 3, 2]
-    
+
     >> [x for x in (2).to(5, step=2)]
     = [2, 4]
-    
+
diff --git a/api/nums.md b/api/nums.md
index 471a7739..ef771171 100644
--- a/api/nums.md
+++ b/api/nums.md
@@ -885,7 +885,7 @@ y | `Num` | The direction towards which to find the next representable value.  |
 ## Num.parse
 
 ```tomo
-Num.parse : func(text: Text -> Num?)
+Num.parse : func(text: Text, remainder: &Text? = none -> Num?)
 ```
 
 Converts a text representation of a number into a floating-point number.
@@ -893,6 +893,7 @@ Converts a text representation of a number into a floating-point number.
 Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The text containing the number.  | -
+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 number represented by the text or `none` if the entire text can't be parsed as a number.
 
@@ -900,9 +901,17 @@ text | `Text` | The text containing the number.  | -
 **Example:**
 ```tomo
 >> Num.parse("3.14")
-= 3.14
+= 3.14 : Num?
 >> Num.parse("1e3")
-= 1000
+= 1000 : Num?
+
+>> Num.parse("1.5junk")
+= none : Num?
+remainder : Text
+>> Num.parse("1.5junk", &remainder)
+= 1.5 : Num?
+>> remainder
+= "junk"
 
 ```
 ## Num.percent
diff --git a/api/nums.yaml b/api/nums.yaml
index e666a0d6..2c18fac5 100644
--- a/api/nums.yaml
+++ b/api/nums.yaml
@@ -686,11 +686,25 @@ Num.parse:
       type: 'Text'
       description: >
         The text containing the number.
+    remainder:
+      type: '&Text?'
+      default: 'none'
+      description: >
+        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.
   example: |
     >> Num.parse("3.14")
-    = 3.14
+    = 3.14 : Num?
     >> Num.parse("1e3")
-    = 1000
+    = 1000 : Num?
+
+    >> Num.parse("1.5junk")
+    = none : Num?
+    remainder : Text
+    >> Num.parse("1.5junk", &remainder)
+    = 1.5 : Num?
+    >> remainder
+    = "junk"
     
 Num.percent:
   short: format as a percentage
diff --git a/api/text.md b/api/text.md
index e500e7bf..bdff6841 100644
--- a/api/text.md
+++ b/api/text.md
@@ -202,7 +202,7 @@ text | `Text` | The text from which to extract codepoint names.  | -
 ## Text.ends_with
 
 ```tomo
-Text.ends_with : func(text: Text, suffix: Text -> Bool)
+Text.ends_with : func(text: Text, suffix: Text, remainder: &Text? = none -> Bool)
 ```
 
 Checks if the `Text` ends with a literal suffix text.
@@ -211,6 +211,7 @@ Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The text to be searched.  | -
 suffix | `Text` | The literal suffix text to check for.  | -
+remainder | `&Text?` | If non-none, this value will be set to the rest of the text up to the trailing suffix. If the suffix is not found, this value will be set to the original text.  | `none`
 
 **Return:** `yes` if the text has the target, `no` otherwise.
 
@@ -219,6 +220,11 @@ suffix | `Text` | The literal suffix text to check for.  | -
 ```tomo
 >> "hello world".ends_with("world")
 = yes
+remainder : Text
+>> "hello world".ends_with("world", &remainder)
+= yes
+>> remainder
+= "hello "
 
 ```
 ## Text.from
@@ -696,7 +702,7 @@ delimiters | `Text` | A text containing delimiters to use for splitting the text
 ## Text.starts_with
 
 ```tomo
-Text.starts_with : func(text: Text, prefix: Text -> Bool)
+Text.starts_with : func(text: Text, prefix: Text, remainder: &Text? = none -> Bool)
 ```
 
 Checks if the `Text` starts with a literal prefix text.
@@ -705,6 +711,7 @@ Argument | Type | Description | Default
 ---------|------|-------------|---------
 text | `Text` | The text to be searched.  | -
 prefix | `Text` | The literal prefix text to check for.  | -
+remainder | `&Text?` | If non-none, this value will be set to the rest of the text after the prefix. If the prefix is not found, this value will be set to the original text.  | `none`
 
 **Return:** `yes` if the text has the given prefix, `no` otherwise.
 
@@ -713,6 +720,11 @@ prefix | `Text` | The literal prefix text to check for.  | -
 ```tomo
 >> "hello world".starts_with("hello")
 = yes
+remainder : Text
+>> "hello world".starts_with("hello", &remainder)
+= yes
+>> remainder
+= " world"
 
 ```
 ## Text.title
diff --git a/api/text.yaml b/api/text.yaml
index eb9dc286..c8d70f0b 100644
--- a/api/text.yaml
+++ b/api/text.yaml
@@ -14,7 +14,7 @@ Text.as_c_string:
   example: |
     >> "Hello".as_c_string()
     = CString("Hello")
-    
+
 Text.at:
   short: get a letter
   description: >
@@ -39,7 +39,7 @@ Text.at:
   example: |
     >> "Amélie".at(3)
     = "é"
-    
+
 Text.by_line:
   short: iterate by line
   description: >
@@ -66,7 +66,7 @@ Text.by_line:
     for line in text.by_line()
     # Prints: "line one" then "line two":
     say(line)
-    
+
 Text.by_split:
   short: iterate by a spliting text
   description: >
@@ -97,7 +97,7 @@ Text.by_split:
     for chunk in text.by_split(",")
     # Prints: "one" then "two" then "three":
     say(chunk)
-    
+
 Text.by_split_any:
   short: iterate by one of many splitting characters
   description: >
@@ -128,7 +128,7 @@ Text.by_split_any:
     for chunk in text.by_split_any(",;")
     # Prints: "one" then "two" then "three":
     say(chunk)
-    
+
 Text.bytes:
   short: get UTF8 bytes
   description: >
@@ -146,7 +146,7 @@ Text.bytes:
   example: |
     >> "Amélie".bytes()
     = [65, 109, 195, 169, 108, 105, 101]
-    
+
 Text.caseless_equals:
   short: case-insensitive comparison
   description: >
@@ -173,11 +173,11 @@ Text.caseless_equals:
   example: |
     >> "A".caseless_equals("a")
     = yes
-    
+
     # Turkish lowercase "I" is "ı" (dotless I), not "i"
     >> "I".caseless_equals("i", language="tr_TR")
     = no
-    
+
 Text.codepoint_names:
   short: get unicode codepoint names
   description: >
@@ -194,7 +194,7 @@ Text.codepoint_names:
   example: |
     >> "Amélie".codepoint_names()
     = ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E WITH ACUTE", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"]
-    
+
 Text.ends_with:
   short: check suffix
   description: >
@@ -212,10 +212,21 @@ Text.ends_with:
       type: 'Text'
       description: >
         The literal suffix text to check for.
+    remainder:
+      type: '&Text?'
+      default: 'none'
+      description: >
+        If non-none, this value will be set to the rest of the text up to the trailing suffix.
+        If the suffix is not found, this value will be set to the original text.
   example: |
     >> "hello world".ends_with("world")
     = yes
-    
+    remainder : Text
+    >> "hello world".ends_with("world", &remainder)
+    = yes
+    >> remainder
+    = "hello "
+
 Text.from:
   short: slice from a starting index
   description: >
@@ -240,10 +251,10 @@ Text.from:
   example: |
     >> "hello".from(2)
     = "ello"
-    
+
     >> "hello".from(-2)
     = "lo"
-    
+
 Text.from_bytes:
   short: convert UTF8 byte list to text
   description: >
@@ -263,7 +274,7 @@ Text.from_bytes:
   example: |
     >> Text.from_bytes([195, 133, 107, 101])
     = "Åke"
-    
+
 Text.from_c_string:
   short: convert C-style string to text
   description: >
@@ -280,7 +291,7 @@ Text.from_c_string:
   example: |
     >> Text.from_c_string(CString("Hello"))
     = "Hello"
-    
+
 Text.from_codepoint_names:
   short: convert list of unicode codepoint names to text
   description: >
@@ -306,7 +317,7 @@ Text.from_codepoint_names:
     "LATIN SMALL LETTER E",
     ]
     = "Åke"
-    
+
 Text.from_codepoints:
   short: convert UTF32 codepoints to text
   description: >
@@ -326,7 +337,7 @@ Text.from_codepoints:
   example: |
     >> Text.from_codepoints([197, 107, 101])
     = "Åke"
-    
+
 Text.has:
   short: check for substring
   description: >
@@ -349,7 +360,7 @@ Text.has:
     = yes
     >> "hello world".has("xxx")
     = no
-    
+
 Text.join:
   short: concatenate with separator
   description: >
@@ -370,7 +381,7 @@ Text.join:
   example: |
     >> ", ".join(["one", "two", "three"])
     = "one, two, three"
-    
+
 Text.middle_pad:
   short: pad text, centered
   description: >
@@ -405,7 +416,7 @@ Text.middle_pad:
     = "  x   "
     >> "x".middle_pad(10, "ABC")
     = "ABCAxABCAB"
-    
+
 Text.left_pad:
   short: left-pad text
   description: >
@@ -440,7 +451,7 @@ Text.left_pad:
     = "    x"
     >> "x".left_pad(5, "ABC")
     = "ABCAx"
-    
+
 Text.lines:
   short: get list of lines
   description: >
@@ -466,7 +477,7 @@ Text.lines:
     = ["one", "two", "three"]
     >> "".lines()
     = []
-    
+
 Text.lower:
   short: convert to lowercase
   description: >
@@ -488,10 +499,10 @@ Text.lower:
   example: |
     >> "AMÉLIE".lower()
     = "amélie"
-    
+
     >> "I".lower(language="tr_TR")
     >> "ı"
-    
+
 Text.quoted:
   short: add quotation marks and escapes
   description: >
@@ -518,7 +529,7 @@ Text.quoted:
   example: |
     >> "one\ntwo".quoted()
     = "\"one\\ntwo\""
-    
+
 Text.repeat:
   short: repeat text
   description: >
@@ -539,7 +550,7 @@ Text.repeat:
   example: |
     >> "Abc".repeat(3)
     = "AbcAbcAbc"
-    
+
 Text.replace:
   short: replace a substring
   description: >
@@ -564,7 +575,7 @@ Text.replace:
   example: |
     >> "Hello world".replace("world", "there")
     = "Hello there"
-    
+
 Text.reversed:
   short: get a reversed copy
   description: >
@@ -581,7 +592,7 @@ Text.reversed:
   example: |
     >> "Abc".reversed()
     = "cbA"
-    
+
 Text.right_pad:
   short: right-pad text
   description: >
@@ -616,7 +627,7 @@ Text.right_pad:
     = "x    "
     >> "x".right_pad(5, "ABC")
     = "xABCA"
-    
+
 Text.slice:
   short: get a slice of a text
   description: >
@@ -647,13 +658,13 @@ Text.slice:
   example: |
     >> "hello".slice(2, 3)
     = "el"
-    
+
     >> "hello".slice(to=-2)
     = "hell"
-    
+
     >> "hello".slice(from=2)
     = "ello"
-    
+
 Text.split:
   short: split a text by a delimiter
   description: >
@@ -681,10 +692,10 @@ Text.split:
   example: |
     >> "one,two,,three".split(",")
     = ["one", "two", "", "three"]
-    
+
     >> "abc".split()
     = ["a", "b", "c"]
-    
+
 Text.split_any:
   short: split a text by multiple delimiters
   description: >
@@ -712,7 +723,7 @@ Text.split_any:
   example: |
     >> "one, two,,three".split_any(", ")
     = ["one", "two", "three"]
-    
+
 Text.starts_with:
   short: check prefix
   description: >
@@ -730,10 +741,21 @@ Text.starts_with:
       type: 'Text'
       description: >
         The literal prefix text to check for.
+    remainder:
+      type: '&Text?'
+      default: 'none'
+      description: >
+        If non-none, this value will be set to the rest of the text after the prefix.
+        If the prefix is not found, this value will be set to the original text.
   example: |
     >> "hello world".starts_with("hello")
     = yes
-    
+    remainder : Text
+    >> "hello world".starts_with("hello", &remainder)
+    = yes
+    >> remainder
+    = " world"
+
 Text.title:
   short: titlecase
   description: >
@@ -755,11 +777,11 @@ Text.title:
   example: |
     >> "amélie".title()
     = "Amélie"
-    
+
     # In Turkish, uppercase "i" is "İ"
     >> "i".title(language="tr_TR")
     = "İ"
-    
+
 Text.to:
   short: slice to an end index
   description: >
@@ -784,10 +806,10 @@ Text.to:
   example: |
     >> "goodbye".to(3)
     = "goo"
-    
+
     >> "goodbye".to(-2)
     = "goodby"
-    
+
 Text.translate:
   short: perform multiple replacements
   description: >
@@ -819,7 +841,7 @@ Text.translate:
         "'" = "'",
     })
     = "A <tag> & an ampersand"
-    
+
 Text.trim:
   short: trim characters
   description: >
@@ -851,13 +873,13 @@ Text.trim:
   example: |
     >> "   x y z    \n".trim()
     = "x y z"
-    
+
     >> "one,".trim(",")
     = "one"
-    
+
     >> "   xyz   ".trim(right=no)
     = "xyz   "
-    
+
 Text.upper:
   short: uppercase
   description: >
@@ -879,11 +901,11 @@ Text.upper:
   example: |
     >> "amélie".upper()
     = "AMÉLIE"
-    
+
     # In Turkish, uppercase "i" is "İ"
     >> "i".upper(language="tr_TR")
     = "İ"
-    
+
 Text.utf32_codepoints:
   short: get UTF32 codepoints
   description: >
@@ -900,7 +922,7 @@ Text.utf32_codepoints:
   example: |
     >> "Amélie".utf32_codepoints()
     = [65, 109, 233, 108, 105, 101]
-    
+
 Text.width:
   short: get display width
   description: >
@@ -924,7 +946,7 @@ Text.width:
     = 6
     >> "🤠".width()
     = 2
-    
+
 Text.without_prefix:
   short: remove prefix
   description: >
@@ -948,7 +970,7 @@ Text.without_prefix:
     = "baz"
     >> "qux".without_prefix("foo:")
     = "qux"
-    
+
 Text.without_suffix:
   short: remove suffix
   description: >
@@ -972,4 +994,4 @@ Text.without_suffix:
     = "baz"
     >> "qux".without_suffix(".foo")
     = "qux"
-    
+