Make Text:find() return an optional int

docs/text.md

@@ -273,15 +273,15 @@ Patterns are used in a small, but very powerful API that handles many text
 functions that would normally be handled by a more extensive API:
 
 ```
-Text.has(pattern:Pattern)->Bool
-Text.find(pattern:Pattern, start=1)->Int
-Text.find_all(pattern:Pattern)->[Text]
-Text.matches(pattern:Pattern)->[Text]?
-Text.map(pattern:Pattern, fn:func(t:Text)->Text)->Text
-Text.replace(pattern:Pattern, replacement:Text, placeholder:Pattern=$//)->[Text]
-Text.replace_all(replacements:{Pattern:Text}, placeholder:Pattern=$//)->[Text]
-Text.split(pattern:Pattern)->[Text]
-Text.trim(pattern=$/{whitespace}/, trim_left=yes, trim_right=yes)->[Text]
+Text.has(pattern:Pattern -> Bool)
+Text.find(pattern:Pattern, start=1 -> Int?)
+Text.find_all(pattern:Pattern -> [Text])
+Text.matches(pattern:Pattern -> [Text]?)
+Text.map(pattern:Pattern, fn:func(t:Text -> Text) -> Text)
+Text.replace(pattern:Pattern, replacement:Text, placeholder:Pattern=$// -> [Text])
+Text.replace_all(replacements:{Pattern:Text}, placeholder:Pattern=$// -> [Text])
+Text.split(pattern:Pattern -> [Text])
+Text.trim(pattern=$/{whitespace}/, trim_left=yes, trim_right=yes -> [Text])
 ```
 
 See [Text Functions](#Text-Functions) for the full API documentation.
@@ -642,7 +642,7 @@ See: [Patterns](#Patterns) for more information on patterns.
 
 **Signature:**  
 ```tomo
-func find(text: Text, pattern: Pattern, start: Int = 1)
+func find(text: Text, pattern: Pattern, start: Int = 1 -> Int?)
 ```
 
 **Parameters:**
@@ -652,19 +652,19 @@ func find(text: Text, pattern: Pattern, start: Int = 1)
 - `start`: The index to start the search.
 
 **Returns:**  
-`0` if the target pattern is not found, otherwise the index where the match was
-found.
+`!Int` if the target pattern is not found, otherwise the index where the match
+was found.
 
 **Example:**  
 ```tomo
 >> " one   two  three   ":find("{id}", start=-999)
-= 0
+= !Int
 >> " one   two  three   ":find("{id}", start=999)
-= 0
+= !Int
 >> " one   two  three   ":find("{id}")
-= 2
+= 2?
 >> " one   two  three   ":find("{id}", start=5)
-= 8
+= 8?
 ```
 
 ---

environment.c

@@ -345,7 +345,7 @@ env_t *new_compilation_unit(CORD libname)
             {"as_c_string", "Text$as_c_string", "func(text:Text -> CString)"},
             {"codepoint_names", "Text$codepoint_names", "func(text:Text -> [Text])"},
             {"ends_with", "Text$ends_with", "func(text,suffix:Text -> Bool)"},
-            {"find", "Text$find", "func(text:Text, pattern:Pattern, start=1 -> Int)"},
+            {"find", "Text$find", "func(text:Text, pattern:Pattern, start=1 -> Int?)"},
             {"find_all", "Text$find_all", "func(text:Text, pattern:Pattern -> [Text])"},
             {"from_bytes", "Text$from_bytes", "func(bytes:[Byte] -> Text)"},
             {"from_c_string", "Text$from_str", "func(str:CString -> Text)"},

stdlib/patterns.c

@@ -796,15 +796,15 @@ static int64_t _find(Text_t text, Pattern_t pattern, int64_t first, int64_t last
     return -1;
 }
 
-public Int_t Text$find(Text_t text, Pattern_t pattern, Int_t from_index)
+public OptionalInt_t Text$find(Text_t text, Pattern_t pattern, Int_t from_index)
 {
     int64_t first = Int_to_Int64(from_index, false);
     if (first == 0) fail("Invalid index: 0");
     if (first < 0) first = text.length + first + 1;
     if (first > text.length || first < 1)
-        return I(0);
+        return NULL_INT;
     int64_t found = _find(text, pattern, first-1, text.length-1, NULL);
-    return I(found+1);
+    return found == -1 ? NULL_INT : I(found+1);
 }
 
 PUREFUNC public bool Text$has(Text_t text, Pattern_t pattern)

stdlib/patterns.h

@@ -18,7 +18,7 @@ Pattern_t Pattern$escape_text(Text_t text);
 Text_t Text$replace_all(Text_t text, Table_t replacements, Pattern_t backref_pat, bool recursive);
 Array_t Text$split(Text_t text, Pattern_t pattern);
 Text_t Text$trim(Text_t text, Pattern_t pattern, bool trim_left, bool trim_right);
-Int_t Text$find(Text_t text, Pattern_t pattern, Int_t i);
+OptionalInt_t Text$find(Text_t text, Pattern_t pattern, Int_t i);
 Array_t Text$find_all(Text_t text, Pattern_t pattern);
 PUREFUNC bool Text$has(Text_t text, Pattern_t pattern);
 Array_t Text$matches(Text_t text, Pattern_t pattern);

test/text.tm

@@ -187,13 +187,13 @@ func main():
 
 	!! Test text:find()
 	>> " one   two  three   ":find($/{id}/, start=-999)
-	= 0
+	= !Int
 	>> " one   two  three   ":find($/{id}/, start=999)
-	= 0
+	= !Int
 	>> " one   two  three   ":find($/{id}/)
-	= 2
+	= 2?
 	>> " one   two  three   ":find($/{id}/, start=5)
-	= 8
+	= 8?
 
 	!! Test text slicing:
 	>> "abcdef":slice()