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

parameter

6 files changed, 64 insertions, 16 deletions

diff --git a/man/man3/tomo-Bool.parse.3 b/man/man3/tomo-Bool.parse.3
index 81830fb3..e1d5f3b7 100644
--- a/man/man3/tomo-Bool.parse.3
+++ b/man/man3/tomo-Bool.parse.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Bool.parse 3 2025-04-30 "Tomo man-pages"
+.TH Bool.parse 3 2025-08-16 "Tomo man-pages"
 .SH NAME
 Bool.parse \- parse into boolean
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Bool.parse\ :\ func(text:\ Text\ ->\ Bool?)
+.BI Bool.parse\ :\ func(text:\ Text,\ remainder:\ &Text?\ =\ none\ ->\ Bool?)
 .fi
 .SH DESCRIPTION
 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`.
@@ -23,6 +23,7 @@ lb lb lbx lb
 l l l l.
 Name	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
 .TE
 .SH RETURN
 `yes` if the string matches a recognized truthy boolean value; otherwise return `no`.
@@ -35,4 +36,12 @@ text	Text	The string containing the boolean value. 	-
 = no : Bool?
 >> Bool.parse("???")
 = none : Bool?
+
+>> Bool.parse("yesJUNK")
+= none : Bool?
+remainder : Text
+>> Bool.parse("yesJUNK", &remainder)
+= yes : Bool?
+>> remainder
+= "JUNK"
 .EE
diff --git a/man/man3/tomo-Byte.parse.3 b/man/man3/tomo-Byte.parse.3
index 6e4d3bb6..1beeb3a4 100644
--- a/man/man3/tomo-Byte.parse.3
+++ b/man/man3/tomo-Byte.parse.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Byte.parse 3 2025-04-30 "Tomo man-pages"
+.TH Byte.parse 3 2025-08-16 "Tomo man-pages"
 .SH NAME
 Byte.parse \- convert text to a byte
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Byte.parse\ :\ func(text:\ Text\ ->\ Byte?)
+.BI Byte.parse\ :\ func(text:\ Text,\ remainder:\ &Text?\ =\ none\ ->\ Byte?)
 .fi
 .SH DESCRIPTION
 Parse a byte literal from text.
@@ -23,6 +23,7 @@ lb lb lbx lb
 l l l l.
 Name	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
 .TE
 .SH RETURN
 The byte parsed from the text, if successful, otherwise `none`.
@@ -30,7 +31,15 @@ The byte parsed from the text, if successful, otherwise `none`.
 .SH EXAMPLES
 .EX
 >> 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"
 .EE
diff --git a/man/man3/tomo-Int.parse.3 b/man/man3/tomo-Int.parse.3
index 8facec2a..07a00e85 100644
--- a/man/man3/tomo-Int.parse.3
+++ b/man/man3/tomo-Int.parse.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Int.parse 3 2025-04-30 "Tomo man-pages"
+.TH Int.parse 3 2025-08-16 "Tomo man-pages"
 .SH NAME
 Int.parse \- convert text to integer
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Int.parse\ :\ func(text:\ Text\ ->\ Int?)
+.BI Int.parse\ :\ func(text:\ Text,\ remainder:\ &Text?\ =\ none\ ->\ Int?)
 .fi
 .SH DESCRIPTION
 Converts a text representation of an integer into an integer.
@@ -23,6 +23,7 @@ lb lb lbx lb
 l l l l.
 Name	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
 .TE
 .SH 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.
@@ -34,6 +35,14 @@ The integer represented by the text. If the given text contains a value outside
 >> 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/man/man3/tomo-Num.parse.3 b/man/man3/tomo-Num.parse.3
index 48ab90c8..63165e59 100644
--- a/man/man3/tomo-Num.parse.3
+++ b/man/man3/tomo-Num.parse.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Num.parse 3 2025-04-30 "Tomo man-pages"
+.TH Num.parse 3 2025-08-16 "Tomo man-pages"
 .SH NAME
 Num.parse \- convert text to number
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Num.parse\ :\ func(text:\ Text\ ->\ Num?)
+.BI Num.parse\ :\ func(text:\ Text,\ remainder:\ &Text?\ =\ none\ ->\ Num?)
 .fi
 .SH DESCRIPTION
 Converts a text representation of a number into a floating-point number.
@@ -23,6 +23,7 @@ lb lb lbx lb
 l l l l.
 Name	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
 .TE
 .SH RETURN
 The number represented by the text or `none` if the entire text can't be parsed as a number.
@@ -30,7 +31,15 @@ The number represented by the text or `none` if the entire text can't be parsed
 .SH EXAMPLES
 .EX
 >> 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"
 .EE
diff --git a/man/man3/tomo-Text.ends_with.3 b/man/man3/tomo-Text.ends_with.3
index 7d19109b..38fa4c0b 100644
--- a/man/man3/tomo-Text.ends_with.3
+++ b/man/man3/tomo-Text.ends_with.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Text.ends_with 3 2025-04-30 "Tomo man-pages"
+.TH Text.ends_with 3 2025-08-16 "Tomo man-pages"
 .SH NAME
 Text.ends_with \- check suffix
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Text.ends_with\ :\ func(text:\ Text,\ suffix:\ Text\ ->\ Bool)
+.BI Text.ends_with\ :\ func(text:\ Text,\ suffix:\ Text,\ remainder:\ &Text?\ =\ none\ ->\ Bool)
 .fi
 .SH DESCRIPTION
 Checks if the `Text` ends with a literal suffix text.
@@ -24,6 +24,7 @@ l l l l.
 Name	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
 .TE
 .SH RETURN
 `yes` if the text has the target, `no` otherwise.
@@ -32,4 +33,9 @@ suffix	Text	The literal suffix text to check for. 	-
 .EX
 >> "hello world".ends_with("world")
 = yes
+remainder : Text
+>> "hello world".ends_with("world", &remainder)
+= yes
+>> remainder
+= "hello "
 .EE
diff --git a/man/man3/tomo-Text.starts_with.3 b/man/man3/tomo-Text.starts_with.3
index 0894ec74..fafa2a55 100644
--- a/man/man3/tomo-Text.starts_with.3
+++ b/man/man3/tomo-Text.starts_with.3
@@ -2,14 +2,14 @@
 .\" Copyright (c) 2025 Bruce Hill
 .\" All rights reserved.
 .\"
-.TH Text.starts_with 3 2025-04-30 "Tomo man-pages"
+.TH Text.starts_with 3 2025-08-16 "Tomo man-pages"
 .SH NAME
 Text.starts_with \- check prefix
 .SH LIBRARY
 Tomo Standard Library
 .SH SYNOPSIS
 .nf
-.BI Text.starts_with\ :\ func(text:\ Text,\ prefix:\ Text\ ->\ Bool)
+.BI Text.starts_with\ :\ func(text:\ Text,\ prefix:\ Text,\ remainder:\ &Text?\ =\ none\ ->\ Bool)
 .fi
 .SH DESCRIPTION
 Checks if the `Text` starts with a literal prefix text.
@@ -24,6 +24,7 @@ l l l l.
 Name	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
 .TE
 .SH RETURN
 `yes` if the text has the given prefix, `no` otherwise.
@@ -32,4 +33,9 @@ prefix	Text	The literal prefix text to check for. 	-
 .EX
 >> "hello world".starts_with("hello")
 = yes
+remainder : Text
+>> "hello world".starts_with("hello", &remainder)
+= yes
+>> remainder
+= " world"
 .EE