RegExp.prototype[Symbol.match]()

str

Ein String, der das Ziel des Abgleichs ist.

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 zurückgegeben, die dem vollständigen regulären Ausdruck entsprechen, aber erfasste Gruppen sind nicht enthalten.
• Wenn das g-Flag nicht verwendet wird, wird nur die erste vollständige Übereinstimmung und die zugehörigen erfassten Gruppen zurückgegeben. In diesem Fall gibt match() dasselbe Ergebnis wie RegExp.prototype.exec() zurück (ein Array mit einigen zusätzlichen Eigenschaften).

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

Zum Beispiel liefern die folgenden zwei Beispiele dasselbe Ergebnis.

"abc".match(/a/);

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

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

Da [Symbol.match]() weiterhin exec() aufrufen würde, bis es null zurückgibt, und exec() automatisch den lastIndex des regulären Ausdrucks auf 0 zurücksetzt, wenn die letzte Übereinstimmung fehlschlägt, hätte [Symbol.match]() typischerweise keine Nebeneffekte, wenn es beendet wird. Wenn der reguläre Ausdruck jedoch sticky aber nicht global ist, wird lastIndex nicht zurückgesetzt. In diesem Fall könnte jeder Aufruf von match() ein anderes Ergebnis liefern.

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, führt er immer noch sticky Matches durch – das heißt, er würde fehlschlagen, um Vorkommen über lastIndex hinaus zu finden.

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

Wenn die aktuelle Übereinstimmung ein leerer String ist, würde lastIndex trotzdem erhöht – wenn der reguläre Ausdruck Unicode-aware ist, wird um einen Unicode-Codepunkt erhöht; andernfalls erhöht es sich um eine UTF-16 Codeeinheit.

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

Diese Methode existiert, um das Match-Verhalten innerhalb von RegExp-Unterklassen zu gestalten.

Zusätzlich wird die [Symbol.match] Eigenschaft verwendet, um zu überprüfen, ob ein Objekt ein regulärer Ausdruck ist.

Diese Methode kann auf fast die gleiche Weise wie String.prototype.match() verwendet werden, mit Ausnahme des unterschiedlichen this und der unterschiedlichen Argumentreihenfolge.

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

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

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("(\\d+)-(\\d+)-(\\d+)");
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

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