RegExp.prototype[Symbol.match]()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die [Symbol.match]()-Methode von RegExp-Instanzen legt fest, wie String.prototype.match() funktionieren soll. Darüber hinaus kann ihre Anwesenheit (oder Abwesenheit) beeinflussen, ob ein Objekt als regulärer Ausdruck betrachtet wird.

Probieren Sie es aus

class RegExp1 extends RegExp {
  [Symbol.match](str) {
    const result = RegExp.prototype[Symbol.match].call(this, str);
    if (result) {
      return "VALID";
    }
    return "INVALID";
  }
}

console.log("2012-07-02".match(new RegExp1("([0-9]+)-([0-9]+)-([0-9]+)")));
// Expected output: "VALID"

Syntax

js
regexp[Symbol.match](str)

Parameter

str

Ein String, der das Ziel des Abgleichs ist.

Rückgabewert

Ein Array, dessen Inhalt von der Anwesenheit oder Abwesenheit des globalen (g)-Flags abhängt, oder null, wenn keine Übereinstimmungen gefunden werden.

  • Wenn das g-Flag verwendet wird, werden alle Ergebnisse, die dem vollständigen regulären Ausdruck entsprechen, zurückgegeben, jedoch ohne eingeschlossene Gruppen.
  • Wenn das g-Flag nicht verwendet wird, wird nur die erste vollständige Übereinstimmung und die zugehörigen eingeschlossenen Gruppen zurückgegeben. In diesem Fall gibt match() das gleiche Ergebnis wie RegExp.prototype.exec() zurück (ein Array mit einigen zusätzlichen Eigenschaften).

Beschreibung

Diese Methode wird intern in String.prototype.match() aufgerufen.

Zum Beispiel liefern die folgenden beiden Beispiele das gleiche Ergebnis.

js
"abc".match(/a/);

/a/[Symbol.match]("abc");

Wenn der reguläre Ausdruck global ist (mit dem g-Flag), wird die Methode exec() des regulären Ausdrucks wiederholt aufgerufen, bis exec() null zurückgibt. Andernfalls würde exec() nur einmal aufgerufen und das Ergebnis wäre der Rückgabewert von [Symbol.match]().

Da [Symbol.match]() exec() so lange aufruft, bis es null zurückgibt, und exec() den lastIndex des regulären Ausdrucks automatisch auf 0 zurücksetzt, wenn die letzte Übereinstimmung fehlschlägt, hat [Symbol.match]() typischerweise keine Nebenwirkungen, wenn es beendet wird. Wenn der reguläre Ausdruck jedoch sticky, aber nicht global ist, wird lastIndex nicht zurückgesetzt. In diesem Fall kann jeder Aufruf von match() ein anderes Ergebnis liefern.

js
const re = /[abc]/y;
for (let i = 0; i < 5; i++) {
  console.log("abc".match(re), re.lastIndex);
}
// [ 'a' ] 1
// [ 'b' ] 2
// [ 'c' ] 3
// null 0
// [ 'a' ] 1

Wenn der reguläre Ausdruck sticky und global ist, werden weiterhin sticky-Abgleiche durchgeführt — d. h., es werden keine Vorkommen über den lastIndex hinaus gefunden.

js
console.log("ab-c".match(/[abc]/gy)); // [ 'a', 'b' ]

Wenn die aktuelle Übereinstimmung eine leere Zeichenfolge ist, wird der lastIndex trotzdem erhöht — wenn der reguläre Ausdruck Unicode-bewusst ist, wird er um einen Unicode-Codepunkt erhöht; andernfalls um eine UTF-16-Code-Einheit.

js
console.log("😄".match(/(?:)/g)); // [ '', '', '' ]
console.log("😄".match(/(?:)/gu)); // [ '', '' ]

Diese Methode existiert, um das Abgleichverhalten innerhalb von RegExp-Unterklassen anzupassen.

Darüber hinaus wird die [Symbol.match]-Eigenschaft verwendet, um zu überprüfen, ob ein Objekt ein regulärer Ausdruck ist.

Beispiele

Direkter Aufruf

Diese Methode kann fast genauso verwendet werden wie String.prototype.match(), abgesehen von der anderen this-Bindung und der anderen Reihenfolge der Argumente.

js
const re = /[0-9]+/g;
const str = "2016-01-02";
const result = re[Symbol.match](str);
console.log(result); // ["2016", "01", "02"]

Verwendung von [Symbol.match]() in Unterklassen

Unterklassen von RegExp können die Methode [Symbol.match]() überschreiben, um das Standardverhalten anzupassen.

js
class MyRegExp extends RegExp {
  [Symbol.match](str) {
    const result = RegExp.prototype[Symbol.match].call(this, str);
    if (!result) return null;
    return {
      group(n) {
        return result[n];
      },
    };
  }
}

const re = new MyRegExp("([0-9]+)-([0-9]+)-([0-9]+)");
const str = "2016-01-02";
const result = str.match(re); // String.prototype.match calls re[Symbol.match]().
console.log(result.group(1)); // 2016
console.log(result.group(2)); // 01
console.log(result.group(3)); // 02

Spezifikationen

Specification
ECMAScript® 2025 Language Specification
# sec-regexp.prototype-%symbol.match%

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
[Symbol.match]

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

Siehe auch