Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Strings and Text

Regex.Replace()

Reference for Regex.Replace in C#: replacement patterns such as $1 and ${name}, MatchEvaluator callbacks, replacement counts and common pitfalls.

Regex.Replace finds every match of a pattern and substitutes it. The replacement can be a string with special tokens that refer to captured groups, or a MatchEvaluator delegate, a function that receives each Match and returns the text to insert. The original string is never modified: you get a new one.

Use a replacement string for fixed rewrites such as reordering a date, and a MatchEvaluator when the new text must be computed, for example doubling every number or looking a name up in a dictionary.

C#
string s = Regex.Replace("2024-05-17", @"(\d+)-(\d+)-(\d+)", "$3/$2/$1");
// 17/05/2024

Try it

C# Replacement tokens

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# MatchEvaluator and escaping literal text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public string Replace(string input, string replacement)
public string Replace(string input, string replacement, int count)
public string Replace(string input, MatchEvaluator evaluator)
public static string Replace(string input, string pattern, string replacement)
public static string Replace(string input, string pattern, MatchEvaluator evaluator)
public static string Replace(string input, string pattern, string replacement, RegexOptions options, TimeSpan matchTimeout)

public delegate string MatchEvaluator(Match match)
Token in replacement Inserts
$1, ${1} Text captured by group 1
${name} Text captured by the named group
$& or $0 The whole match
$` and $' The text before / after the match
$$ A literal $
$_ The entire input string
Parameter Description
count Maximum number of replacements (instance method only; -1 means all).
evaluator Called once per match; returns the replacement text, used literally.

Returns: the new string; the input itself if there was no match.

Errors / undefined behavior: ArgumentNullException for null input, pattern or replacement. RegexParseException for an invalid pattern. A token that names a group that does not exist is left as literal text, not an error.

Usage notes

  • $ in a replacement is special. A price like "$5" is read as group 5, which does not exist, so it stays literal here, but "$1" would be substituted. Use $$, or a MatchEvaluator, whose result is never interpreted.
  • Digits after a group reference. $10 means group 10 if it exists. Write ${1}0 for "group 1 then a zero".
  • All matches are replaced unless you use the count overload. There is no static version with a count.
  • Matching is on the original text. Replaced text is never searched again, so a replacement can safely contain the pattern.
  • Anchors and zero-width matches. A pattern like ^ or \b inserts text at positions without removing anything. Regex.Replace("ab", "", "-") gives -a-b-.
  • Plain text? Use string.Replace. It is faster and has no special characters. Reach for the regex version for patterns, classes, or case-insensitive matching with RegexOptions.IgnoreCase.
  • Escaping. When the replacement comes from users, either escape $ as $$ or use the evaluator overload.
  • Related tasks. Regex.Split cuts at matches; Regex.Matches lists them without changing the text.