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

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

Zum Beispiel liefern die folgenden zwei Beispiele dasselbe Ergebnis.

"abc".match(/a/);

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

Wenn das Regex 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 dessen Ergebnis wird der Rückgabewert von [Symbol.match]().

Da [Symbol.match]() exec() aufruft, bis es null zurückgibt, und exec() automatisch den lastIndex des Regex auf 0 zurücksetzt, wenn der letzte Abgleich fehlschlägt, hätte [Symbol.match]() typischerweise keine Nebenwirkungen beim Beenden. Wenn der Regex jedoch sticky aber nicht global ist, wird der 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 Regex sticky und global ist, führt er weiterhin Sticky-Abgleiche durch — d.h. es wird keine Übereinstimmungen jenseits des lastIndex geben.

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

Wenn die aktuelle Übereinstimmung ein leerer String ist, wird der lastIndex trotzdem weitergeschaltet — wenn der Regex Unicode-fähig ist, wird 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-Unterklassen anzupassen.

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

Diese Methode kann fast auf die gleiche Weise wie String.prototype.match() verwendet werden, abgesehen von dem unterschiedlichen this und der unterschiedlichen Reihenfolge der Argumente.

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