RegExp : mthode statique escape()

Syntaxe

RegExp.escape(string)

Paramtres

string

La chane de caractres chapper.

Valeur de retour

Une nouvelle chane de caractres qui peut tre utilise en toute scurit comme motif littral pour le constructeur RegExp(). Autrement dit, les lments suivants dans la chane de caractres en entre sont remplacs :

• Le premier caractre de la chane de caractres, s'il s'agit d'un chiffre dcimal (0-9) ou d'une lettre ASCII (a-z, A-Z), est chapp l'aide de la syntaxe d'chappement de caractre \x. Par exemple, RegExp.escape("toto") retourne "\\x66oo" (ici et ci-aprs, les deux barres obliques inverses d'un littral de chane de caractres reprsentent un seul caractre de barre oblique inverse). Cette tape garantit que si cette chane de caractres chappe est intgre dans un motif plus grand immdiatement prcd de \1, \x0, \u000, etc., le caractre initial n'est pas interprt comme faisant partie de la squence d'chappement.
• Les caractres de syntaxe des expressions rationnelles, notamment ^, $, \, ., *, +, ?, (, ), [, ], {, }, et |, ainsi que le dlimiteur /, sont chapps en insrant un caractre \ devant eux. Par exemple, RegExp.escape("toto.truc") retourne "\\x66oo\\.truc", et RegExp.escape("(toto)") retourne "\\(toto\\)".
• Les autres signes de ponctuation, notamment ,, -, =, <, >, #, &, !, %, :, ;, @, ~, ', `, et ", sont chapps l'aide de la syntaxe \x. Par exemple, RegExp.escape("toto-truc") retourne "\\x66oo\\x2dtruc". Ces caractres ne peuvent pas tre chapps en les prfixant avec \ car, par exemple, /toto\-truc/u est une erreur de syntaxe.
• Les caractres qui possdent leurs propres squences d'chappement de caractre : \f (U+000C saut de page), \n (U+000A saut de ligne), \r (U+000D retour chariot), \t (U+0009 tabulation horizontale), et \v (U+000B tabulation verticale), sont remplacs par leurs squences d'chappement. Par exemple, RegExp.escape("toto\ntruc") retourne "\\x66oo\\ntruc".
• Le caractre espace est chapp sous la forme "\\x20".
• Les autres caractres non ASCII de saut de ligne et d'espacement sont remplacs par une ou deux squences d'chappement \uXXXX reprsentant leurs units de code UTF-16. Par exemple, RegExp.escape("toto\u2028truc") retourne "\\x66oo\\u2028truc".
• Les substituts isols sont remplacs par leurs squences d'chappement \uXXXX. Par exemple, RegExp.escape("toto\uD800truc") retourne "\\x66oo\\ud800truc".

Exceptions

TypeError

Leve si string n'est pas une chane de caractres.

Exemples

Utiliser RegExp.escape()

Les exemples suivants illustrent diffrentes entres et sorties de la mthode RegExp.escape().

RegExp.escape("Achetez-le. Utilisez-le. Cassez-le. Rparez-le.");
// "\\x41chetez\\x2dle\\.\\x20Utilisez\\x2dle\\.\\x20Cassez\\x2dle\\.\\x20Rparez\\x2dle\\."
RegExp.escape("toto.truc"); // "\\x66oo\\.truc"
RegExp.escape("toto-truc"); // "\\x66oo\\x2dtruc"
RegExp.escape("toto\ntruc"); // "\\x66oo\\ntruc"
RegExp.escape("toto\uD800truc"); // "\\x66oo\\ud800truc"
RegExp.escape("toto\u2028truc"); // "\\x66oo\\u2028truc"

Utiliser RegExp.escape() avec le constructeur RegExp

Le principal cas d'utilisation de RegExp.escape() consiste intgrer une chane de caractres dans un motif d'expression rationnelle plus grand et garantir que cette chane de caractres est traite comme un motif littral, et non comme une syntaxe d'expression rationnelle. Considrez l'exemple naf suivant, qui remplace des URL :

function supprimerDomaine(texte, domaine) {
  return texte.replace(new RegExp(`https?://${domaine}(?=/)`, "g"), "");
}

const entree =
  "Considrez utiliser [RegExp.escape()](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/RegExp/escape) pour chapper les caractres spciaux dans une chane de caractres.";
const domaine = "developer.mozilla.org";
console.log(supprimerDomaine(entree, domaine));
// Considrez utiliser [RegExp.escape()](/fr/docs/Web/JavaScript/Reference/Global_Objects/RegExp/escape) pour chapper les caractres spciaux dans une chane de caractres.

L'insertion de domaine ci-dessus produit le littral d'expression rationnelle https?://developer.mozilla.org(?=/), o le caractre  .  est un caractre joker d'expression rationnelle. Le motif correspond toute chane de caractres contenant n'importe quel caractre la place du  . , comme developer-mozilla-org. Le remplacement modifie donc aussi, tort, le texte suivant :

const entree =
  "Ce n'est pas un lien MDN : https://developer-mozilla.org/, faites attention !";
const domaine = "developer.mozilla.org";
console.log(supprimerDomaine(entree, domaine));
// Ce n'est pas un lien MDN : /, faites attention !

Pour corriger cela, nous pouvons utiliser RegExp.escape() afin de garantir que toute entre de l'utilisateurice est traite comme un motif littral :

function supprimerDomaine(texte, domaine) {
  return texte.replace(
    new RegExp(`https?://${RegExp.escape(domaine)}(?=/)`, "g"),
    "",
  );
}

Cette fonction fait dsormais exactement ce que nous voulons et ne transforme pas les URL developer-mozilla.org.

Spcifications

Compatibilit des navigateurs

Voir aussi

• La prothse d'mulation de RegExp.escape dans core-js (angl.)
• La prothse d'mulation de es-shims de RegExp.escape (angl.)
• L'objet natif RegExp