# text.match_groups · Rell standard library · Chromia Docs (concept)

> pure function match_ groups(regex: text ): list < text >? Match this text against the specified regular expression, returning all match groups in a list. A

Source: https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/root/text/match_groups/

FUNCTION

# text.match\_groups

```signature
pure function match_groups(regex: text): list<text>?
```

Match this text against the specified regular expression, returning all match groups in a list.

Attempts to match this entire text, as opposed to searching for a match.

Match groups in a regular expression are defined by any parentheses that the regular expression
contains, and the groups are ordered by the position of their opening parentheses. For example, the
regular expression `(X(Y))(Z)` contains 3 matching groups, which are:

* `(X(Y))`
* `(Y)`
* `(Z)`

The zeroth element in the returned list is the entire match, i.e. this exact text value, assuming
the regular expression matches this text. The subsequent list elements are the match subgroups.

Examples:

* `'johnsmith@chromaway.com'.match_groups('([a-z]+)@([a-z]+[.][a-z]+)')` returns
  `['johnsmith@chromaway.com', 'johnsmith', 'chromaway.com']`.
* `'XYZ'.match_groups('(X(Y))(Z)')` returns `['XYZ', 'XY', 'Y', 'Z']`.
* `'XYZ'.match_groups('((X(Y))(Z))')` returns `['XYZ', 'XYZ' ,'XY', 'Y', 'Z']`.
* `'X'.match_groups('(X)|(Y)')` returns `['X', 'X', '']` (the third group (`(Y)`) matches nothing,
  hence the empty string).

Matched non-capturing groups (notated `(?:X)`, where `X` is a regular expression) are supported, and
are not included in the returned list.

Named capturing groups (notated `(?<name>X)`, where `X` is a regular expression) can be used, but
the returned value provides no way to access named groups by their name (though they are present in
the returned list). To extract groups by name, use instead `text.match_named_groups()`.

**Parameters**

* **regex** — the regular expression to match against

**Returns**

a `list<text>` containing all match groups (the zeroth of which is the entire matched text),
or `null` if this text does not match the given regular expression

**Throws**

* `exception` — if `regex` is not a valid regular expression

**See Also**

1. [`java.util.regex.Pattern` - Groups and capturing (Java SE 21 & JDK 21)](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/regex/Pattern.html#cg)
2. [`text.match_named_groups` - Rell Standard Library](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/root/text/match_named_groups/)

Since 0.14.13

[View this page on docs.chromia.com](https://docs.chromia.com/pages/rell-stdlib/-rell%20-system%20-library/%5Broot%5D/text/match_groups.html)Generated API reference, mirrored from the live docs