RegExp.prototype[Symbol.match]()

str

Ein String, der 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, die dem kompletten regulären Ausdruck entsprechen, zurückgegeben, aber Erfassungsgruppen sind nicht enthalten.
• Wenn das g Flag nicht verwendet wird, wird nur die erste vollständige Übereinstimmung und ihre zugehörigen Erfassungsgruppen zurückgegeben. In diesem Fall liefert match() das gleiche Ergebnis wie RegExp.prototype.exec() (ein Array mit einigen zusätzlichen Eigenschaften).

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

Zum Beispiel geben die folgenden zwei Beispiele das gleiche Ergebnis zurück.

"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 dessen Ergebnis würde 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, würde [Symbol.match]() typischerweise keine Nebeneffekte haben, wenn es beendet wird. Wenn der reguläre Ausdruck jedoch sticky aber nicht global ist, würde lastIndex nicht zurückgesetzt. In diesem Fall kann 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, würde er weiterhin sticky Übereinstimmungen durchführen — d.h. er würde keine Vorkommen jenseits des lastIndex finden.

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

Wenn die aktuelle Übereinstimmung ein leerer String ist, würde der lastIndex trotzdem weitergeschoben — wenn der reguläre Ausdruck Unicode-bewusst ist, würde er um einen Unicode-Codepunkt weitergeschoben; andernfalls wird er um eine UTF-16-Codeeinheit weitergeschoben.

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

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

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, außer dem 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