RegExp.prototype[Symbol.search]() — Methode · JavaScript-Referenz

Signatur

RegExp.prototype[Symbol.search](str)

Beschreibung

RegExp.prototype[Symbol.search]() ist die Methode, an die String.prototype.search() die Arbeit abgibt. Ein Aufruf wie "text".search(re) wird intern zu re[Symbol.search]("text"). Die Methode liefert die Position des ersten Treffers im String oder -1, wenn kein Treffer gefunden wurde.

Intern läuft das so ab: Der aktuelle Wert von lastIndex wird gesichert, lastIndex auf 0 gesetzt, dann wird exec() aufgerufen und danach der alte lastIndex wiederhergestellt. Deshalb spielt das Flag g für search() keine Rolle, und der Zustand des RegExp-Objekts bleibt erhalten. Das Flag y (sticky) wird dagegen beachtet: Ein Treffer zählt dann nur, wenn er genau bei Index 0 beginnt.

Direkt aufrufen muss man die Methode praktisch nie. Nützlich wird sie vor allem, wenn man Unterklassen von RegExp schreibt, die das Suchverhalten anpassen sollen, zum Beispiel für Protokollierung, Statistik oder eine andere Art, den Index zu berechnen. Auch ein beliebiges Objekt mit einer Methode [Symbol.search] lässt sich an String.prototype.search() übergeben.

Parameter

Name	Typ	Default	Beschreibung
$str Pflicht	string		Der String, der durchsucht wird. Andere Werte werden vorher in einen String umgewandelt (zum Beispiel `undefined` → `"undefined"`).

Rückgabewert

Typ

number

Beschreibung

Der Index, an dem der erste Treffer beginnt, oder -1, wenn es keinen Treffer gibt.

Beispiele

Direkter Aufruf und Vergleich mit String.prototype.search()

const re = /-/;
const datum = "2016-01-02";

// Beide Aufrufe sind gleichwertig
console.log(re[Symbol.search](datum));
console.log(datum.search(re));

// Kein Treffer
console.log(/x/[Symbol.search](datum));

4 4 -1

lastIndex bleibt erhalten, das Flag g wird ignoriert

const re = /a/g;
re.lastIndex = 5;

console.log("banana".search(re)); // sucht trotzdem ab Index 0
console.log(re.lastIndex);        // wurde wiederhergestellt

// Sticky-Flag: Treffer nur an Position 0
console.log("abc".search(/b/y));
console.log("abc".search(/a/y));

1 5 -1 0

Unterklasse mit Protokollierung der Suche

class LoggingRegExp extends RegExp {
  [Symbol.search](str) {
    const result = super[Symbol.search](str);
    console.log(`Suche nach ${this} in "${str}": ${result}`);
    return result;
  }
}

const re = new LoggingRegExp("Welt");
const index = "Hallo Welt".search(re);
console.log(index);

Suche nach /Welt/ in "Hallo Welt": 6 6

Eigenes Suchobjekt ohne RegExp

// Jedes Objekt mit [Symbol.search] kann an search() übergeben werden
const letzteZiffer = {
  [Symbol.search](str) {
    for (let i = str.length - 1; i >= 0; i--) {
      if (str[i] >= "0" && str[i] <= "9") return i;
    }
    return -1;
  }
};

console.log("Bestellung A12-B7x".search(letzteZiffer));

16

// Wichtig · Fallstricke

Nur der erste Treffer: search() liefert ausschließlich den Index des ersten Treffers. Für alle Treffer oder für Gruppen verwendet man matchAll() oder exec(). Wer nur wissen will, ob es einen Treffer gibt, nimmt besser test().
Kein Einfluss durch g, aber durch y: Weil lastIndex vorübergehend auf 0 gesetzt wird, ändert das Flag g nichts am Ergebnis. Mit dem Flag y gibt es dagegen nur einen Treffer, wenn das Muster genau bei Index 0 passt.
Unterklassen: Die Methode ruft intern this.exec() auf. Wenn eine Unterklasse exec() überschreibt, ändert sich damit auch das Verhalten von search().
String-Argumente: Bekommt String.prototype.search() einen String statt eines RegExp-Objekts, wird daraus mit new RegExp(wert) ein regulärer Ausdruck gebaut. Sonderzeichen wie . oder ? gelten dann als Regex-Metazeichen.
Kompatibilität: Wird seit ES2015 in allen modernen Browsern und in Node.js unterstützt, nicht aber im Internet Explorer.

Siehe auch

String.prototype.search() Symbol.search RegExp.prototype.exec() RegExp.prototype.test() RegExp.prototype.lastIndex