<!-- GENERATED by docs/sphinx/bin/02-reference from re.rs (xs_regname). Do not edit. -->

```{index} single: regname; re function
```
```{index} single: re::regname; Perl function
```

# regname

Return the contents of a named capture group from the most recent successful match.

With one argument, returns the first defined value captured by
the named group. With a truthy second argument, returns an array
reference holding every value the group captured — useful when
the same name appears in a repeated subpattern or in multiple
alternation branches.

## Synopsis

```perl
use re 'regname';
"foobar" =~ /(?<word>\w+)/;
my $first = regname('word');        # 'foobar'
my $all   = regname('word', 1);     # arrayref of all captures
```

## What you get back

- Without `$all` (or with a false `$all`) — the first defined
  captured string, or `undef` if the name didn't match anything
  or didn't exist in the pattern.
- With a truthy `$all` — an array reference containing every
  captured value for that name, in order.
- If there was no prior successful match — `undef`.

## Examples

```perl
"2025-04-22" =~ /(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})/;
print regname('y');                        # '2025'

"abc123" =~ /(?<n>\d+)|(?<n>\w+)/;
print regname('n');                        # first defined capture
print join(',', @{ regname('n', 1) });     # every capture for 'n'

my $missing = regname('nope');             # undef — no such name
```

## Edge cases

- Called with zero arguments — croaks with
  `Usage: re::regname(name [, all])`.
- No successful match yet in the current scope — returns `undef`.
- Name was declared but did not participate in the match —
  returns `undef` (single form) or an arrayref of `undef`s
  (`$all` form).