RegExp.prototype[Symbol.replace]()

str

Ein String, der Ziel der Ersetzung ist.

replacement

Kann ein String oder eine Funktion sein.

• Wenn es ein String ist, wird er den durch den aktuellen RegExp übereinstimmenden Unterstring ersetzen. Eine Reihe spezieller Ersetzungsmuster wird unterstützt; siehe den Abschnitt Angeben eines Strings als Ersetzung von String.prototype.replace.
• Wenn es eine Funktion ist, wird sie für jedes Match aufgerufen und der Rückgabewert wird als Ersetzungstext verwendet. Die Argumente, die dieser Funktion übergeben werden, sind im Abschnitt Angeben einer Funktion als Ersetzung von String.prototype.replace beschrieben.

Ein neuer String, bei dem einer, einige oder alle Vorkommen des Musters durch die angegebene Ersetzung ersetzt werden.

Diese Methode wird intern in String.prototype.replace() und String.prototype.replaceAll() aufgerufen, wenn das pattern-Argument ein RegExp-Objekt ist. Beispielsweise liefern die folgenden zwei Beispiele dasselbe Ergebnis.

"abc".replace(/a/, "A");

/a/[Symbol.replace]("abc", "A");

Wenn der Regex global (mit dem g-Flag) ist, wird die exec()-Methode des Regexes wiederholt aufgerufen, bis exec() null zurückgibt. Andernfalls würde exec() nur einmal aufgerufen. Für jedes exec()-Ergebnis wird die Ersetzung basierend auf der Beschreibung in String.prototype.replace() vorbereitet.

Da [Symbol.replace]() exec() so lange aufruft, bis es null zurückgibt und exec() automatisch den lastIndex des Regexes auf 0 zurücksetzt, wenn das letzte Match fehlschlägt, hat [Symbol.replace]() typischerweise keine Nebeneffekte, wenn es beendet wird. Ist der Regex jedoch sticky aber nicht global, wird lastIndex nicht zurückgesetzt. In diesem Fall kann jeder Aufruf von replace() ein anderes Ergebnis liefern.

const re = /a/y;

for (let i = 0; i < 5; i++) {
  console.log("aaa".replace(re, "b"), re.lastIndex);
}

// baa 1
// aba 2
// aab 3
// aaa 0
// baa 1

Wenn der Regex sticky und global ist, würde er trotzdem Sticky-Matches durchführen — d.h. er würde nicht jedem Vorkommen jenseits von lastIndex entsprechen.

console.log("aa-a".replace(/a/gy, "b")); // "bb-a"

Wenn das aktuelle Match ein Leerstring ist, würde lastIndex trotzdem weitergeschaltet werden — wenn der Regex Unicode-aware ist, um einen Unicode-Codepunkt; andernfalls um eine UTF-16-Codeeinheit.

console.log("😄".replace(/(?:)/g, " ")); // " \ud83d \ude04 "
console.log("😄".replace(/(?:)/gu, " ")); // " 😄 "

Diese Methode existiert zur Anpassung des Ersetzungsverhaltens in RegExp-Unterklassen.

Diese Methode kann fast genauso wie String.prototype.replace() verwendet werden, abgesehen vom unterschiedlichen this und der unterschiedlichen Reihenfolge der Argumente.

const re = /-/g;
const str = "2016-01-01";
const newStr = re[Symbol.replace](str, ".");
console.log(newStr); // 2016.01.01

Unterklassen von RegExp können die [Symbol.replace]()-Methode überschreiben, um das Standardverhalten zu ändern.

class MyRegExp extends RegExp {
  constructor(pattern, flags, count) {
    super(pattern, flags);
    this.count = count;
  }
  [Symbol.replace](str, replacement) {
    // Perform [Symbol.replace]() `count` times.
    let result = str;
    for (let i = 0; i < this.count; i++) {
      result = RegExp.prototype[Symbol.replace].call(this, result, replacement);
    }
    return result;
  }
}

const re = new MyRegExp("\\d", "", 3);
const str = "01234567";
const newStr = str.replace(re, "#"); // String.prototype.replace calls re[Symbol.replace]().
console.log(newStr); // ###34567

• Polyfill von RegExp.prototype[Symbol.replace] in core-js
• String.prototype.replace()
• String.prototype.replaceAll()
• RegExp.prototype[Symbol.match]()
• RegExp.prototype[Symbol.matchAll]()
• RegExp.prototype[Symbol.search]()
• RegExp.prototype[Symbol.split]()
• RegExp.prototype.exec()
• RegExp.prototype.test()
• Symbol.replace