RegExp.prototype[Symbol.match]()

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("(\\d+)-(\\d+)-(\\d+)")));
// Expected output: "VALID"

Syntax

regexp[Symbol.match](str)

Parameter

str

Ein String, in dem nach Übereinstimmungen gesucht wird.

Rückgabewert

Ein Array, dessen Inhalt davon abhängt, ob das globale Flag (g) vorhanden ist, oder null, wenn keine Übereinstimmungen gefunden werden.

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

Beschreibung

Diese Methode dient dazu, das Verhalten bei der Suche nach Übereinstimmungen in RegExp-Unterklassen anzupassen. Sie wird intern von String.prototype.match() aufgerufen. Beispielsweise liefern die folgenden beiden Ausdrücke dasselbe Ergebnis.

"abc".match(/a/);

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

Wenn der reguläre Ausdruck global ist (also das Flag g besitzt), wird sein lastIndex zunächst auf 0 gesetzt. Dadurch beginnt die Suche nach Übereinstimmungen immer am Anfang der Zeichenfolge. Anschließend wird die Methode exec() des regulären Ausdrucks wiederholt aufgerufen, bis exec() null zurückgibt. Wenn die aktuelle Übereinstimmung eine leere Zeichenfolge ist, wird lastIndex trotzdem erhöht: Ist der reguläre Ausdruck Unicode-fähig, erfolgt die Erhöhung um einen Unicode-Codepunkt, andernfalls um eine UTF-16-Codeeinheit.

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

Wenn der reguläre Ausdruck nicht global ist, wird exec() nur einmal aufgerufen. Sein Ergebnis ist dann der Rückgabewert von [Symbol.match]().

Die Methode exec() setzt lastIndex automatisch auf 0 zurück, wenn die letzte Suche nach einer Übereinstimmung fehlschlägt. Daher hat [Symbol.match]() bei globalen regulären Ausdrücken, deren lastIndex anfangs 0 ist, im Allgemeinen keine Nebenwirkungen. Wenn der reguläre Ausdruck jedoch sticky, aber nicht global ist, wird exec() nur einmal aufgerufen und setzt lastIndex nach einer erfolgreichen Übereinstimmung daher nicht zurück. 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 sowohl sticky als auch global ist, sucht er weiterhin nur an der durch lastIndex vorgegebenen Position nach Übereinstimmungen. Eine Suche nach weiteren Vorkommen jenseits von lastIndex findet also nicht statt.

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

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

Beispiele

Direkter Aufruf

Diese Methode kann fast genauso verwendet werden wie String.prototype.match(). Allerdings unterscheiden sich this und die Reihenfolge der Argumente.

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

[Symbol.match]() in Unterklassen verwenden

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("(\\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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Polyfill für 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