working on documentation and more API functions

2026-04-29 12:09:37 +00:00
parent cd445f3c9b
commit 9f7625c7fd
94 changed files with 1896 additions and 458 deletions
@@ -0,0 +1,59 @@
+:sig
+DTree regex_search(String pattern, String subject)
+DTree regex_search(String pattern, String subject, String flags)
+
+:params
+pattern : PCRE2 regular expression pattern
+subject : string to search
+flags : optional regex flags
+return value : a DTree describing the first match
+
+:see
+>regex
+regex_match
+regex_search_all
+regex_replace
+regex_split
+0_DTree
+
+:content
+Searches `subject` for the first occurrence of `pattern` and returns structured match data.
+
+Example:
+
+```uce
+DTree match = regex_search(
+	"(?<user>[A-Za-z0-9._%+-]+)@(?<host>[A-Za-z0-9.-]+)",
+	"Contact ops@example.test"
+);
+
+if(match["matched"].to_bool())
+{
+	print(match["match"].to_string());
+	print(match["named"]["user"].to_string());
+	print(match["named"]["host"].to_string());
+}
+```
+
+Return shape:
+
+- `matched` is a boolean.
+- `pattern` stores the original pattern.
+- `flags` stores the supplied flags, or `default`.
+- `match` is the full matched text when a match exists.
+- `start` and `end` are byte offsets into the original string.
+- `captures` is a list of capture objects, with capture `0` representing the full match.
+- `named` maps named capture groups to their captured text.
+- `named_offsets` maps named capture groups to `index`, `start`, and `end` metadata.
+
+Capture entries contain:
+
+```text
+capture["index"]
+capture["matched"]
+capture["start"]
+capture["end"]
+capture["text"]
+```
+
+If no match is found, `matched` is `false` and match-specific fields are omitted.