RegExp.prototype[Symbol.replace]()

str

Ein String, der das Ziel des Ersatzes ist.

replacement

Kann ein String oder eine Funktion sein.

• Wenn es ein String ist, ersetzt er den durch den aktuellen RegExp übereinstimmenden Teilstring. Eine Reihe von speziellen Ersatzmustern wird unterstützt; siehe den Abschnitt Einen String als Ersatz angeben von String.prototype.replace.
• Wenn es eine Funktion ist, wird sie für jede Übereinstimmung aufgerufen und der Rückgabewert wird als Ersetzungstext verwendet. Die der Funktion übergebenen Argumente sind im Abschnitt Eine Funktion als Ersatz angeben von String.prototype.replace beschrieben.

Ein neuer String, bei dem ein, mehrere oder alle Übereinstimmungen des Musters durch den angegebenen Ersatz ersetzt wurden.

Diese Methode wird intern in String.prototype.replace() und String.prototype.replaceAll() aufgerufen, wenn das pattern-Argument ein RegExp-Objekt ist. Zum Beispiel geben die folgenden zwei Beispiele dasselbe Ergebnis zurück.

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

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

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

Da [Symbol.replace]() weiter exec() aufruft, bis es null zurückgibt, und exec() automatisch den lastIndex des Regex auf 0 zurücksetzt, wenn die letzte Übereinstimmung fehlschlägt, hat [Symbol.replace]() normalerweise keine Nebeneffekte, wenn es beendet wird. Wenn der Regex jedoch sticky ist, aber nicht global, wird lastIndex nicht zurückgesetzt. In diesem Fall kann jeder Aufruf von replace() ein unterschiedliches Ergebnis zurückgeben.

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, wird er weiterhin Sticky-Matches durchführen – d.h. er wird nicht in der Lage sein, Vorkommen über den lastIndex hinaus zu erkennen.

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

Wenn die aktuelle Übereinstimmung ein leerer String ist, wird lastIndex trotzdem weitergesetzt – wenn der Regex Unicode-bewusst ist, wird er um einen Unicode-Codepunkt weitergesetzt; andernfalls erfolgt die Weiterführung 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 auf fast die gleiche Weise wie String.prototype.replace() verwendet werden, abgesehen von dem 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 Methode [Symbol.replace]() ü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