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

# s

/// (substitution)

## Synopsis

```perl
$str =~ s/pattern/replacement/;
$str =~ s/pattern/replacement/g;     # global
$str =~ s/pattern/replacement/gi;    # global, case-insensitive
($copy = $orig) =~ s/old/new/g;      # compound assign+subst
s/pattern/replacement/;               # operates on $_
```

## Description

Searches a string for a pattern and replaces matched text.

Compiles the pattern from `OpData::Pm`, finds matches in the
target string, performs the substitution, and updates the source
variable **in place**.  Pushes the number of successful
substitutions to the stack (0 if no match, which is false in
boolean context).

The target string is resolved from:
- A PadSv op (lexical variable `$str =~ s/.../.../`)
- A GvSv op (package variable)
- A Sassign op (compound `(my $x = $y) =~ s/.../.../`)

Supports replacement templates with backreferences (`$1`, `$&`,
etc.) and replacement ops for the `/e` flag (evaluate replacement
as Perl code).

**Flags**: /g (global), /i (case-insensitive), /m (multiline),
/s (single-line), /e (eval replacement), /r (non-destructive,
returns modified copy).

## See also

m//, tr///, perlre, perlop