From 3513b94fc7505e48208814436a8d4bd6edcdd10c Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Wed, 4 Sep 2024 16:08:34 -0400
Subject: Unify parsing code to correctly handle parsing integers and numbers
 with a &success boolean. Check for overflow as well.

---
 docs/integers.md | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/integers.md b/docs/integers.md
index 653322fd..50ecd034 100644
--- a/docs/integers.md
+++ b/docs/integers.md
@@ -144,23 +144,39 @@ Converts a text representation of an integer into an integer.
 
 **Usage:**  
 ```tomo
-from_text(text: Text, the_rest: Text = "!&Text") -> Int
+from_text(text: Text, success: Bool = !&Bool?) -> Int
 ```
 
 **Parameters:**
 
-- `text`: The string containing the integer.
-- `the_rest`: If non-null, this pointer will be set to point to any unparseable text after the integer.
+- `text`: The text containing the integer.
+- `success`: If non-null, this pointer will be set to `yes` if the whole text
+  is a valid integer that fits within the representable range of the integer
+  type, otherwise `no`.
 
 **Returns:**  
-The integer represented by the string.
+The integer represented by the text. If the given text contains a value outside
+of the representable range, the number will be truncated to the minimum or
+maximum representable value. Other failures to parse the number will return
+zero.
 
 **Example:**  
 ```tomo
->> from_text("123")
+>> Int.from_text("123")
 = 123
->> from_text("0xFF")
+>> Int.from_text("0xFF")
 = 255
+
+success := no
+>> Int.from_text("asdf", &success)
+= 0
+>> success
+= no
+
+>> Int8.from_text("9999999", &success)
+= 127
+>> success
+= no
 ```
 
 ---
-- 
cgit v1.2.3