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

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

Zum Beispiel geben die folgenden zwei Beispiele dasselbe 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 sein Ergebnis wird der Rückgabewert von [Symbol.match]().

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

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 dennoch sticky-Matches durchführen — d.h. er würde keine Vorkommen über den lastIndex hinaus finden.

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

Wenn die aktuelle Übereinstimmung eine leere Zeichenfolge ist, würde der lastIndex dennoch erhöht werden — wenn der reguläre Ausdruck Unicode-fähig ist, würde er um einen Unicode Codepunkt erhöht; andernfalls wird er um eine UTF-16 Codeeinheit erhöht.

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

Diese Methode existiert, um das Abgleichsverhalten innerhalb von RegExp Subklassen anzupassen.

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

Diese Methode kann in fast derselben Weise wie String.prototype.match() verwendet werden, außer der unterschiedlichen this und der unterschiedlichen Argumentenreihenfolge.

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

Unterklassen von RegExp können die Methode [Symbol.match]() ü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("([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

• 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