---
title: regsub
summary: null
url: https://www.fastly.com/documentation/reference/vcl/functions/strings/regsub
---

```
STRING regsub(STRING input, REGEX pattern, STRING replacement)
```

**Available in:** all subroutines

Replaces the first occurrence of `pattern` (a Perl-compatible regular expression) in `input` with `replacement`.
If no match is found, no replacement is made.
Calls to `regsub` do not set `re.group.{N}`.

Captured groups captured in `pattern` can be inserted into the replacement string using `\0` through `\9`,
which correspond to their `re.group.{N}` counterparts.
Subsequent numeric literals are treated as literal characters.
For example, `\100` means `re.group.1` followed by a literal "00".

Captured groups can also be inserted using `\{0}` through `\{19}`, which allows you to specify group numbers higher than 9.
Use non-capturing groups with `(?:)` if the sub-pattern is not used in a backreference.
See our recommendations on [best practices for regular expressions in VCL](https://www.fastly.com/documentation/reference/vcl/regex/#best-practices-and-common-mistakes) for more.

> **HINT:** To extract a value from a string (e.g. extract the `.html` from `index.html`), rather than replace a value in a string, consider using `if` instead. [Learn more in VCL best practices](https://www.fastly.com/documentation/guides/vcl/best-practices/#dont-use-regsub-for-data-extraction).

This function is not prefixed with the `std.` namespace.

## Interpolation

The same syntax for [interpolating](https://en.wiktionary.org/wiki/interpolate#:~:text=in%20that%20data%2C-,to%20fetch%20data%20from%20a%20different%20source%20and%20process%20it%20in%2Dline%20along%20with%20the%20original%20data,-.%20quotations%C2%A0%E2%96%BC)
captured values is also used by `reginterpolate`,
except that `regsub` and `regsuball` treat unrecognised escape sequences as literals.
For example, `\x` means a literal `"x"`,
and an unterminated `\{..` sequence (without a closing brace) means a literal "{..".

See `reginterpolate` for documentation on the interpolation syntax used in the replacement string.

Named captures (that is, `re.group.{NAME}`) are not supported by `regsub` and `regsuball`.
These are also treated as unsupported escape sequences.
For example, `\{xyz}` means a literal "{xyz}".
This differs for `reginterpolate`, which also does not support named captures,
but does error for unrecognised escape sequences.

As with `re.group.0`, `\0` and `\{0}` evaluate to the entire matched string,
even when no capture groups have been supplied.
Substituting the original string back into itself gives no change.
The usefulness of `\0` comes when the replacement string contains it along with other characters,
such as `"x\0x"`, or contains `\0` multiple times.

For example, `regsub(req.http.x, "l", "\0\0")` on the string "hello"
matches only the first "l" and substitutes that matched substring
for both instances of `\0` in the replacement string,
giving "helllo" (three "l" characters) as the result.
The third "l" is passed through unchanged from the input string.
In contrast, `regsuball` matches and substitute both "l" characters,
giving "hellllo" as the result.

## Errors

This function may fail to make a replacement if the regular expression recurses too heavily. Such a situation may occur with lookahead and lookbehind assertions, or other recursing non-regular expressions. In this case, `fastly.error` is set to `EREGRECUR`.

## Examples

The following example deletes the query string portion of the request URL (equivalent to `req.url.path`):

```vcl
set req.url = regsub(req.url, "\?.*$", "");
```

This replaces the last two digits of an HTTP status code to 00 for grouping purposes. Note that the 00 remains as a literal "00" in the substitution:

```vcl
set var.response_code_type = regsub(beresp.status, "^([1-5])..", "\100"); # capture group \1 followed by literal 00
```

This will reverse the first 15 characters of a header:

```vcl
set var.reversed = regsub(req.http.longheader, "(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)", "\{15}\{14}\{13}\{12}\{11}\{10}\9\8\7\6\5\4\3\2\1");
```
