---
name: m
status: documented
runtime: pp
source: src/runtime/pp/regex/match_op.rs
---
```{index} single: m; Perl built-in (pp runtime)
```

# m

// (pattern match)

## Synopsis

```perl
if ($str =~ /pattern/)       { ... }
if ($str =~ /pattern/flags)  { ... }
my @captures = ($str =~ /(\w+)/g);
/bare pattern/;                        # matches against $_
```

## Description

Tests a string against a regular expression pattern.

Matches the target string against the compiled regex pattern.
The target is determined by context:
- If `targ > 0`: reads from the pad slot (lexical `$str =~ /pat/`)
- If STACKED flag is set: pops from the stack (expression `=~ /pat/`)
- Otherwise: matches against `$_` (bare `/pat/`)

In **scalar context**, returns true (1) or false ("") indicating
whether the pattern matched.  Sets `$1`, `$2`, etc. for capture
groups and updates `pos()` for `/g` matches.

In **list context without /g**, returns the list of captured
substrings (`$1`, `$2`, ...), or `(1)` if there are no captures.

In **list context with /g**, returns all matches: if the pattern
has captures, returns all captured groups from all matches;
otherwise returns all matched substrings.

Patterns are cached per-op for static regexes; dynamic patterns
(from `regcomp`) use a HashMap-based cache.

## See also

s///, split, qr//, perlre, perlop