:sig
DValue regex_search(String pattern, String subject)
DValue 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 DValue describing the first match

:see
>regex
regex_match
regex_search_all
regex_replace
regex_split
0_DValue

:content
Searches `subject` for the first occurrence of `pattern` and returns structured match data.

Example:

```uce
DValue 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.