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

> pure function match_ named_ groups(regex: text ): map < text , text >? Match this text against the specified regular expression, returning a map whose keys

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

FUNCTION

# text.match\_named\_groups

```signature
pure function match_named_groups(regex: text): map<text, text>?
```

Match this text against the specified regular expression, returning a map whose keys are the names
of each named group in the regular expression, and values are the text that was matched to the
corresponding group.

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

Unnamed groups and their matching text are not included in the returned map (use instead
`text.match_groups()` to extract these).

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)`

Named groups are match groups in a regular expression for which a name is specified. The match
groups in the above example (`(X(Y))(Z)`) could be assigned names in the following manner:

Plain text

```
(?<x>X(?<y>Y))(?<z>Z)
```

This is an equivalent regular expression, but the text matched by each group can be referenced by
the group's name.

Examples:

* `'XYZ'.match_named_groups('(?<x>X(?<y>Y))(?<z>Z)')` returns `['x': 'XY', 'y': 'Y', 'z': 'Z']`.
* `'XYZ'.match_named_groups('(?<x>X(Y))(Z)')` returns `['x': 'XY']`.
* `'johnsmith@chromaway.com'.match_groups('(?<user>[a-z]+)@(?<domain>[a-z]+[.][a-z]+)')` returns
  `['user': 'johnsmith', 'domain': 'chromaway.com']`.
* `'X'.match_named_groups('(?<x>X)|(?<y>Y)')` returns `['x': 'X']`.
* `'X'.match_named_groups('(?<x>X)(?<y>Y?)')` returns `['x': 'X', 'y': '']`.

Matched non-capturing groups (notated `(?:X)`, where `X` is a regular expression) are supported, and
are not included in the returned map. Named groups that match the empty string with the `?` and `*`
quantifiers are included in the returned map, but named groups within unmatched alternatives are
not.

**Parameters**

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

**Returns**

a `map<text, text>` containing the match groups and their matching text obtained by matching
this text to the given regular expression; 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_groups` - Rell Standard Library](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/root/text/match_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_named_groups.html)Generated API reference, mirrored from the live docs