RegExp : mthode exec()

Exemple interactif

const regex = /fo+/g;
const str = "table football, foosball";
let array;

while ((array = regex.exec(str)) !== null) {
  console.log(
    `Trouv ${array[0]}. Prochaine recherche  partir de ${regex.lastIndex}.`,
  );
  // Rsultat attendu : "Trouv foo. Prochaine recherche  partir de 9."
  // Rsultat attendu : "Trouv foo. Prochaine recherche  partir de 19."
}

Syntaxe

exec(str)

Paramtres

str

La chane de caractres contre laquelle faire correspondre l'expression rationnelle. Toutes les valeurs sont converties en chanes de caractres, donc l'omission de ce paramtre ou le passage de undefined entrane la recherche de la chane de caractres "undefined" par exec(), ce qui est rarement souhait.

Valeur de retour

Si la correspondance choue, la mthode exec() retourne null, et met la proprit lastIndex de l'expression rationnelle 0.

Si la correspondance russit, la mthode exec() retourne un tableau et met jour la proprit lastIndex de l'objet expression rationnelle. Le tableau retourn a le texte correspondant comme premier lment, puis un lment pour chaque groupe capturant du texte correspondant. Le tableau a galement les proprits supplmentaires suivantes :

index

L'index bas sur 0 de la correspondance dans la chane de caractres.

input

La chane de caractres originale contre laquelle la correspondance a t effectue.

groups

Un objet dont le prototype est null contenant les groupes nomms capturant, avec leurs noms comme cls et les groupes capturant comme valeurs, ou undefined si aucun groupe capturant nomm n'est dfini. Consultez les groupes capturant pour plus d'informations.

indices Facultatif

Cette proprit est prsente uniquement lorsque l'indicateur d est dfini. Il s'agit d'un tableau o chaque entre reprsente les limites d'une correspondance de sous-chane de caractres. L'indice de chaque lment de ce tableau correspond l'indice de la sous-chane de caractres correspondante dans le tableau retourn par exec(). Autrement dit, la premire entre de indices reprsente la correspondance entire, la deuxime reprsente le premier groupe capturant, etc. Chaque entre est elle-mme un tableau de deux lments, dont le premier nombre reprsente l'indice de dbut de la correspondance et le second, son indice de fin.

Le tableau indices possde galement une proprit groups, qui contient un objet dont le prototype est null regroupant tous les groupes nomms capturant. Les cls sont les noms des groupes capturant et chaque valeur est un tableau de deux lments, dont le premier nombre correspond l'indice de dbut et le second l'indice de fin du groupe capturant. Si l'expression rationnelle ne contient aucun groupe capturant nomm, groups vaut undefined.

Description

Les objets JavaScript RegExp conservent un tat lorsque l'indicateur global ou l'indicateur d'adhrence est dfini (par exemple, /foo/g ou /foo/y). Ils stockent dans lastIndex la position de la correspondance prcdente. Ce mcanisme interne permet exec() d'itrer sur plusieurs correspondances dans une chane de caractres (avec des groupes capturant), au lieu de rcuprer uniquement les chanes de caractres correspondantes avec String.prototype.match().

Lorsque vous utilisez exec(), l'indicateur global n'a aucun effet si l'indicateur d'adhrence est dfini la correspondance est toujours adhrente.

exec() est la mthode primitive des expressions rationnelles. De nombreuses autres mthodes d'expression rationnelle appellent exec() en interne y compris celles appeles par les mthodes de chanes de caractres, comme [Symbol.replace](). Bien que exec() soit puissant (et soit la mthode la plus efficace), il n'exprime souvent pas l'intention avec le plus de clart.

• Si vous voulez uniquement savoir si l'expression rationnelle correspond une chane de caractres, sans vous soucier du texte correspondant, utilisez RegExp.prototype.test() la place.
• Si vous recherchez toutes les occurrences d'une expression rationnelle globale et que les informations comme les groupes capturant ne vous intressent pas, utilisez String.prototype.match() la place. De plus, String.prototype.matchAll() facilite la recherche de plusieurs parties d'une chane de caractres (avec des groupes capturant) en vous permettant d'itrer sur les correspondances.
• Si vous effectuez une recherche pour trouver l'indice de la correspondance dans la chane de caractres, utilisez plutt la mthode String.prototype.search().

exec() est utile pour les oprations complexes qui ne peuvent pas tre facilement ralises au moyen des mthodes ci-dessus, souvent lorsque vous devez ajuster manuellement lastIndex. (String.prototype.matchAll() copie l'expression rationnelle, donc modifier lastIndex pendant l'itration sur matchAll n'a aucun effet sur l'itration.) Pour un exemple de ce type, voir le recul de lastIndex.

Exemples

Utiliser exec()

Considrons l'exemple suivant :

// Correspond  "quick brown" suivi de "jumps", en ignorant les caractres intermdiaires
// Se souvient de "brown" et "jumps"
// Ignore la casse
const re = /quick\s(?<color>brown).+?(jumps)/dgi;
const resultat = re.exec("The Quick Brown Fox Jumps Over The Lazy Dog");

Le tableau suivant montre l'tat de resultat aprs l'excution de ce script :

De plus, re.lastIndex est dfini sur 25, car cette expression rationnelle est globale.

Trouver les correspondances successives

Si votre expression rationnelle utilise l'indicateur g, vous pouvez utiliser plusieurs fois la mthode exec() pour trouver des correspondances successives dans la mme chane de caractres. Dans ce cas, la recherche commence dans la sous-chane de caractres de chaine dfinie par la proprit lastIndex de l'expression rationnelle (test() fait galement avancer la proprit lastIndex). Notez que la proprit lastIndex n'est pas rinitialise lorsque vous recherchez une chane de caractres diffrente, et que la recherche commence sa valeur actuelle lastIndex.

Par exemple, supposons que vous ayez le script suivant :

const monRe = /ab*/g;
const chaine = "abbcdefabh";
let monTableau;
while ((monTableau = monRe.exec(chaine)) !== null) {
  let msg = `Trouv ${monTableau[0]}. `;
  msg += `Le prochain rsultat commence  ${monRe.lastIndex}`;
  console.log(msg);
}

Ce script affiche le texte suivant :

Trouv abb. Le prochain rsultat commence  3
Trouv ab. Le prochain rsultat commence  9

Vous pouvez gnralement remplacer ce type de code par String.prototype.matchAll() pour rduire le risque d'erreur.

Utiliser exec() avec des littraux d'expression rationnelle

Vous pouvez galement utiliser exec() sans crer explicitement un objet RegExp :

const correspondances = /(bonjour \S+)/.exec("Ceci est un bonjour monde !");
console.log(correspondances[1]);

Cela affiche un message contenant 'bonjour monde !'.

Spcifications

Compatibilit des navigateurs

Voir aussi

• Le guide des expressions rationnelles
• L'objet natif RegExp