RegExp.prototype[@@match]()

Baseline Large disponibilité

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis septembre 2016.

La méthode [@@match]() permet de récupérer les correspondances obtenues lorsqu'on teste une chaîne de caractères par rapport à une expression rationnelle (regexp).

Dans cet article

Exemple interactif

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("([0-9]+)-([0-9]+)-([0-9]+)")));
// Expected output: "VALID"

Syntaxe

regexp[Symbol.match](str);

Paramètres

str

La chaîne de caractères (String) sur laquelle on veut chercher des correspondances.

Valeur de retour

Un tableau (Array) qui contient les résultats des correspondances et les groupes capturés grâce aux parenthèse. S'il n'y a aucune correspondance, ce sera null.

Description

Cette méthode est appelée de façon interne lorsqu'on utilise String.prototype.match(). Ainsi, les deux exemples qui suivent sont équivalents et le second est la version interne du premier :

js
"abc".match(/a/);

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

Cette méthode existe afin de permettre d'adapter le comportement de la recherche des correspondances pour les sous-classes de RegExp.

Exemples

Appel direct

Cette méthode peut être utilisée comme String.prototype.match() mais avec un objet this différent et un ordre des paramètres également différent.

js
var re = /[0-9]+/g;
var str = "2016-01-02";
var résultat = re[Symbol.match](str);
console.log(résultat); // ["2016", "01", "02"]

Utilisation de @@match avec une sous-classe

Les sous-classes de RegExp peuvent surcharger la méthode [@@match]() afin de modifier le comportement.

js
class MaRegExp extends RegExp {
  [Symbol.match](str) {
    var résultat = RegExp.prototype[Symbol.match].call(this, str);
    if (!résultat) return null;
    return {
      group(n) {
        return résultat[n];
      },
    };
  }
}

var re = new MaRegExp("([0-9]+)-([0-9]+)-([0-9]+)");
var str = "2016-01-02";
var résultat = str.match(re); // String.prototype.match appelle re[@@match].
console.log(résultat.group(1)); // 2016
console.log(résultat.group(2)); // 01
console.log(résultat.group(3)); // 02

Aider à améliorer MDN

Cette page vous a-t-elle été utile ?

Oui Non

Apprendre à contribuer

Cette page a été modifiée le 17 févr. 2025 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu

Objets natifs standards
RegExp
Constructeur
1. Constructeur RegExp()
Méthodes statiques
1. escape()
Propriétés statiques
Méthodes d'instance
Propriétés d'instance
Héritage
Object/Function
Méthodes statiques
Propriétés statiques
Méthodes d'instance
Propriétés d'instance
1. Object.prototype.__proto__
2. Object.prototype.constructor