# regex.extract()

`regex.extract(haystack, pattern [, group])` extracts a substring matching a regex pattern from a string.

## Returns

* if `haystack` is a string and `pattern` matches, returns the matched substring (or the specified capture group if `group` is provided).
  * `group` 0 returns the entire match (default).
  * `group` 1 returns the first capture group `(...)`.
  * `group` 2 returns the second capture group, etc.
* if no match is found or inputs are invalid, returns `null`.

## Examples

```javascript
// extract the first IPv4 address from a message
regex.extract(message, /\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}/)

// extract domain from email
regex.extract(email, /@(.+)$/, 1)

// extract capture groups
| eval address = "123 Sesame Street",
  street_number = regex.extract(address, /^(\d+)\s+(.+)$/, 1), // 123
  street_name   = regex.extract(address, /^(\d+)\s+(.+)$/, 2)  // Sesame Street
```