String.prototype.replace()

Syntax

str.replace(regexp|substr, newSubStr|function);

Parameter

regexp

Ein RegExp-Objekt. Die Übereinstimmung wird durch den Rückgabewert aus Parameter #2 ersetzt.

substr

Eine Zeichenkette, welche durch newSubStr ersetzt werden soll. Nur das erste Vorkommen wird ersetzt.

newSubStr

Die Zeichenkette, welche den Substring aus Parameter #1 ersetzt. Eine Anzahl spezieller Ersetzungsmuster wird unterstützt, siehe den "Eine Zeichenkette als Parameter angeben"-Abschnitt weiter unten.

function

Eine Funktion, welche aufgerufen wird, um den neuen Substring zu erzeugen, der an Stelle des gefundenen Substrings aus Parameter #1 stehen soll. Die Argumente für diese Funktion werden im "Eine Funktion als Parameter angeben"-Abschnitt unten erläutert.

Rückgabe

Eine neue Zeichenkette, in der einige oder alle Übereinstummungen mit einem Muster durch einen Ersatz ausgetauscht wurden.

Beschreibung

Diese Methode ändert nicht das String-Objekt, auf welchem sie aufgerufen wird. Sie gibt lediglich einen neuen String zurück.

Um ein globales Suchen und Ersetzen durchzuführen, setzen Sie den g-Umschalter im Regulären ausdruck.

Eine Zeichenkette als Parameter angeben

Die Ersatzzeichenkette kann folgende spezielle Ersetzungsmuster beinhalten:

Eine Funktion als Parameter angeben

Sie können eine Funktion als zweiten Parameter angeben. In diesem Fall wird diese Funktion aufgerufen, nachdem die Suche ausgeführt wurde. Der Rückgabewert der Funktion wird als Ersatz eingesetzt. (Anmerkung: Die oben genannten speziellen Ersetzungsmuster werden in diesem Fall nicht beachtet.) Bedenken Sie, dass die Funktion für jede Übereinstimmung erneut aufgerufen wird, wenn der reguläre Ausdruck im ersten Parameter den global-Flag gesetzt hat.

Die Argumente dieser Funktion lauten wie folgt:

(Die genaue Anzahl der Argumente hängt davon ab, ob das erste Argument eine RegExp war und wieviele eingeklammerte Submatches in diesem Fall angegeben wurden.)

Das folgende Beispiel wird newString auf "abc - 12345 - #$*%" setzen:

function replacer(match, p1, p2, p3, offset, string){
  // p1 is nondigits, p2 digits, and p3 non-alphanumerics
  return [p1, p2, p3].join(' - ');
}
newString = "abc12345#$*%".replace(/([^\d]*)(\d*)([^\w]*)/, replacer);

Beispiele

Beispiel: Definieren des regulären Ausdrucks in replace

Globales Ersetzen kann nur mit einem regulären Ausfruck durchgeführt werden. Im folgenden Beispiel wird der reguläre Ausdruck in replace definiert und beinhaltet den Schalter ignore case.

var str = "Twas the night before Xmas...";
var newstr = str.replace(/xmas/i, "Christmas");
print(newstr);

Dies erzeugt die Ausgabe "Twas the night before Christmas..."

Beispiel: Nutzung von global und ignore mit replace

Das nachfolgende Beispiel enthält einen regulären Ausdruck, der sowohl das global als auch das ignore Flag gesetzt hat. Dadurch wird von replace jedes Vorkommnis von 'apples' in der Zeichenkette durch 'oranges' ersetzt.

var re = /apples/gi;
var str = "Apples are round, and apples are juicy.";
var newstr = str.replace(re, "oranges");
print(newstr);

Dies erzeugt die Ausgabe "Smith, John"

Beispiel: Vertausche Wörter in Strings

Im Folgenden Skript werden die Wörter in dem String getauscht. Für dei Vertauschung im Text, nutzt das Sktipt die Ersetzungspatterns $1 und $2.

var re = /(\w+)\s(\w+)/;
var str = "John Smith";
var newstr = str.replace(re, "$2, $1");
print(newstr);

Die Ausgabe ist: "Smith, John".

Beispiel: Nutzung von Inline-Funktionen, die die erkannten Zeichen modifizieren

In diesem Beispiel werden alle Großbuchstaben durch einen Bindestrich und den entsprechenden kleinbuchstaben ersetzt. Der wichtige Punkt in dem Beispiel ist, dass der Additions-Operator (Konkatination) vor dem zurückgeben der neuen Zeichenkette erfolgen muss.

Die Ersetzungsfunktion bekommt das erkannte Muster als Parameter übergeben und benutzt diesen, um den Buchstaben zu transformieren und ihn mit dem Bindestrich zu verbinden. Zum Schluss wird das Ergebnis zum Ersetzen zurückgegeben.

function styleHyphenFormat(propertyName) {
  function upperToHyphenLower(match) {
    return '-' + match.toLowerCase();
  }
  return propertyName.replace(/[A-Z]/g, upperToHyphenLower);
}

Gegeben styleHyphenFormat('borderTop'), gibt 'border-top' zurück.

Weil das Ergebnis transformiert werden soll, bevor die finale Ersetzung durchgeführt wird, muss eine Funktion eingesetzt werden. Dieses erzwingt die Ausführung von toLowerCase(). Wenn man das gleiche versucht ohne eine Funktion zu benutzen, wird die toLowerCase() Methode ohne Wirkung sein.

var newString = propertyName.replace(/[A-Z]/g, '-' + '$&'.toLowerCase());  // won't work

Dieses ist weil '$&'.toLowerCase() ausgeführt wird, bevor der String als Pattern genutzt wird.

Beispiel: Grad Fahrenheit in Celsius-Grad umwandeln

Das folgende Beispiel ersetzt einen Wert in Grad Fahrenheit durch den entsprechenden Celsius-Wert. Der Fahrenheitwert sollte eine Nummer sein, die mit einem F endet. Die Funktion gibt eine Celsius-Temperatur mit der Endung C aus. Ist zum Beispiel der Eingabewert 212F, so gibt die Funktion 100C zurück. Ist die Nummer 0F, so wird -17,77777777777778C zurück gegeben.

Der reguläre Ausdruck test prüft jede Nummer, die mit F endet. Die Nimmer in Grad Fahrenheit ist durch den zweiten Funktionsparameter, p1, ansprechbar. Die Funktion setzt den Celsiuswert basierend auf dem Fahrenheitwert in einer Zeichenkette in der f2c-Funktion. f2c gibt dann den Celsiuswert zurück. Diese Funktion ähnelt Perl's s///e-Flag.

function f2c(x) {
  function convert(str, p1, offset, s) {
    return ((p1-32) * 5/9) + "C";
  }
  var s = String(x);
  var test = /(\d+(?:\.\d*)?)F\b/g;
  return s.replace(test, convert);
}

Beispiel: Verwenden einer inline-Funktion mit einem regulärem Ausdruck um Schleifen zu vermeiden

Das folgende Beispiel nimmt eine Zeichenkettenmuster und konvertiert es in ein Array von Objekten.

Eingabe:
Eine Zeichenkette, die aus den Zeichen x, - und _ besteht

x-x_
x---x---x---x---
x-xxx-xx-x-
x_x_x___x___x___

[
  { on: true, length: 1 },
  { on: false, length: 1 },
  { on: true, length: 2 }
  ...
]

var str = 'x-x_';
var retArr = [];
str.replace(/(x_*)|(-)/g, function(match, p1, p2){
  if(p1) retArr.push({ on: true, length: p1.length });
  if(p2) retArr.push({ on: false, length: 1 });
});

console.log(retArr);

Spezifikationen

Browserkompatibilität

Firefox-spezifische Bemerkungen

• Mit dem Start von Gecko 27 (Firefox 27 / Thunderbird 27 / SeaMonkey 2.24), wurde diese Methode an die ECMAScript Spezifikation angepasst. Wenn replace() mit einem globalen regulären Ausdruck aufgerufen wird, wird die RegExp.lastIndex Eigenschaft (wenn sie Spezifiziert wurde) auf 0 zurückgesetzt (Bug 501739).
• Mit dem Start von Gecko 39 (Firefox 39 / Thunderbird 39 / SeaMonkey 2.36) wurden das nicht standatdisierten flags Argument als deprecated markiert und wirft eine Warnung in der Konsole (Bug 1142351).
• Mit dem Start von Gecko 47 (Firefox 47 / Thunderbird 47 / SeaMonkey 2.44) wurden das nicht standatdisierten flags Argument  nicht länger in Nicht-Release-Builds unterstützt und wird bald vollständig entfernt (Bug 1245801).
• Mit dem Start von Gecko 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46) wurden das nicht standatdisierten flags Argument nicht mehr unterstützt (Bug 1108382).

Siehe auch

• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()