String.prototype.replace()

La méthode replace() renvoie une nouvelle chaîne de caractères dans laquelle certaines correspondances ou toutes les correspondances par rapport à un motif sont remplacées par un texte de remplacement. Le motif utilisé peut être une RegExp et le paramètre de remplacement peut être une chaîne ou une fonction à appeler sur chaque correspondance.

Syntaxe

str.replace(regexp|substr, newSubStr|function)

Paramètres

regexp
Un objet RegExp ou un littéral d'expression rationnelle. La correspondance sera remplacée par la valeur de retour du second paramètre.
substr
Un objet String qui sera remplacé par newSubStr.
newSubStr
L'objet String qui remplace la chaîne de caractères correspondant au premier paramètre. Il existe plusieurs paramètres de remplacement spéciaux, pour ceux-ci, voir le tableau ci-après.
function
La fonction qui sera appelée pour créer la nouvelle chaîne de caractères. Les arguments passés à cette fonction sont décrits plus bas, voir le paragraphe Utiliser une fonction comme paramètre.

Valeur de retour

Une nouvelle chaîne de caractères pour laquelle toutes ou certaines des correspondances ont été remplacées par une chaîne de remplacement.

Description

Cette méthode ne transforme pas l'objet String sur lequel elle est appliquée. Elle retourne simplement une nouvelle chaîne de caractères. L'objet de départ reste inchangé.

Pour réaliser une recherche/remplacement de toutes les occurrences sur la chaîne de caractères, on utilisera le marqueur (flag) g avec l'expression rationnelle.

Utiliser une chaîne de caractère comme paramètre

La chaîne de caractère de substitution peut comporter les motifs (patterns) spécifiques suivants :

Motif
(Pattern)
Insère
$$ Insère un "$".
$& Insère la chaine de caractère recherchée.
$` Insère la partie de la chaîne de caractère qui précède l'élément recherché.
$' Insère la partie de la chaîne de caractère qui suit l'élément recherché.
$n

Où n est un entier positif inférieur à 100, insère la n ième sous-chaîne entre parenthèses, à condition que la recherche soit effectuée grâce à un objet RegExp.

Utiliser une fonction comme paramètre

Il est possible d'utiliser une fonction comme second paramètre. Dans ce cas, cette fonction sera appelée après que la recherche aie été effectuée. Le résultat de la fonction sera, quant à lui, utilisé comme terme de remplacement. (Note : le motif de remplacement mentionné dans la section ci-avant ne s'applique pas dans ce cas). On remarquera que cette fonction sera appelée plusieurs fois (une pour chaque occurence trouvée) si la recherche comporte le drapeau g.

Les arguments de cette fonction seront les suivants :

Nom Valeur fournie
match La chaîne de caractère recherchée. (Correspondant au $& défini ci-avant.)
p1, p2, ...

les n-ièmes sous-chaînes recherchées, à condition que le premier argument (replace) soit un objet RegExp. (Correspond aux $1, $2, etc. présentés plus haut.). Par example, si /(\a+)(\b+)/, a été donné comme argument, p1 correspond à \a+, et p2 à  \b+.

offset Le décalage entre la sous-chaîne correspondante et la chaîne totale. (Par exemple, si la chaîne de départ est "abcd", et que le chaîne correspondante est "bc", cet argument vaudra 1.)
string La chaîne initiale, entière, qui est examinée.

(Le nombre exact d'arguments dépend du fait que le premier paramètre est ou non un objet  RegExp : si c'est le cas du nombre de parenthèses groupantes correspondant aux différentes recherches.)

L'exemple suivant va affecter comme valeur à la variable  nouvelleChaîne "abc - 12345 - #$*%".

function remplaceur(match, p1, p2, p3, offset, string){
  // p1 représente le groupe non numérique
  // p2 représente le groupe avec les chiffre
  // et p3 le groupe non-alphanumérique
  return [p1, p2, p3].join(' - ');
}
var nouvelleChaîne = "abc12345#$*%".replace(/([^\d]*)(\d*)([^\w]*)/, remplaceur);

Exemples

Utiliser global et ignore avec replace()

Dans l'exemple suivant, l'expression rationnelle intègre les flags global et ignore, ce qui permet à replace de remplacer chaque occurrence du mot 'pommes' dans la chaine de caractères par le mot 'oranges'. Un remplacement global ne peut être effectué qu'avec une expression rationnelle.

var re = /pommes/gi;
var str = "Les pommes sont rondes. Les pommes sont juteuses.";
var nouvelleStr = str.replace(re, "oranges");
console.log(nouvelleStr); 
// Les oranges sont rondes. Les oranges sont juteuses.

Utiliser une expression rationnelle avec replace()

Dans l'exemple suivant, l'argument est une expression rationnelle :

var str = "the night before Xmas...";
var nouvelleStr = str.replace(/xmas/i, "Christmas");
console.log(nouvelleStr); // the night before Christmas

Inverser des mots d' une chaîne de caractères

Le script suivant script intervertit les mots de la chaîne de caractères initiale. Le script utilise les motifs $1 et $2 :

var re = /(\w+)\s(\w+)/;
var str = "Jean Biche";
var nouvelleStr = str.replace(re, "$2, $1");
console.log(nouvelleStr); // Biche, Jean

Utiliser une fonction qui transforme les caractères correspondants

Dans cet exemple, toutes les occurrences des lettres majuscules sont converties en minuscules, et un tiret  est inséré juste avant l'endroit où elles ont étés trouvées. Il est important de voir qu'une opération suppémentaire est nécessaire (d'où la fonction upperToHyphenLower qui est appelée à l'intérieur de la fonction styleHyphenFormat).

La fonction de remplacement utilise la correspondance comme paramètre (chacune des majuscules trouvée) et les utilise pour les transformer en minuscules et les concaténer au tiret avant de les renvoyer.

function styleHyphenFormat(propertyName) {
  function upperToHyphenLower(match) {
    return '-' + match.toLowerCase();
  }
  return propertyName.replace(/[A-Z]/g, upperToHyphenLower);
}

De fait,  styleHyphenFormat('borderTop') renvoie : 'border-top'.

La méthode .toLowerCase() est exécutée à partir des valeurs que .upperToHyphenLower() reçoit de la méthode .replace() qui l'appelle (mécanisme de callback ). Si nous avions essayé de faire celà directement, celà n'aurait pas fonctionné.

var nouvelleStr = propertyName.replace(/[A-Z]/g, '-' + '$&'.toLowerCase());  
// ne fonctionne pas

La raison est que .toLowerCase() aurait évalué '$&' comme une chaîne de caractères littérale (identique à '$&') avant de transmettre cette valeur à .replace(). La méthode .replace() aurait alors évalué cette expression '$&' et aurait remplacé la lettre majuscule trouvée par elle-même.

Remplacer un degré Fahrenheit par un degré Celsius

L'exemple suivant remplace un degré Fahrenheit par son équivalent en Celsius. Le degré Fahrenheit doit être un nombre se terminant par F. La fonction renvoie le nombre en Celsius (se terminant par C). Par exemple, si le nombre de départ est 212F, la fonction renvoie 100C. Si le nombre de départ est 0F, la fonction renvoie -17.77777777777778C.

L'expression régulière test vérifie tous les nombres qui se terminent par F. La valeur en nombre du degré Fahrenheitest accessible pour la fonction .convert() grâce à son second argument, p1. Cette fonction retourne alors la valeur convertie en une chaîne de caractères à la fonction f2c()

function f2c(x) {
  function convert(str, p1, offset, s) {
    return ((p1-32) * 5/9) + "C";
  }
  var s = String(x);
  var test = /(-?\d+(?:\.\d*)?)F\b/g;
  return s.replace(test, convert);
}

Utiliser une fonction avec une expression rationnelle pour éviter des boucles

L'exemple suivant convertit une chaîne de caractères obéissant à un certain motif et la convertit en un tableau d'objets.

Entrée :
Une chaîne de caractères composée des caractères x, - et _

x-x_
x---x---x---x---
x-xxx-xx-x-
x_x_x___x___x___
Sortie :
on', un  '-' (tiret) symbolise le 'off' et un  '_' (underscore) symbolise la longueur d'un état 'on'.
[
  { on: true, length: 1 },
  { on: false, length: 1 },
  { on: true, length: 2 }
  ...
]
Fragment de code :
var str = 'x-x_';
var retArr = [];
str.replace(/(x_*)|(-)/g, function(match, $1, $2){
  if($1) retArr.push({ on: true, length: $1.length });
  if($2) retArr.push({ on: false, length: 1 });
});

console.log(retArr);
Ce « snippet » génère un tableau de 3 objets sans utiliser de boucle.
 

Spécifications

Spécification État Commentaires
ECMAScript 3rd Edition (ECMA-262) Standard Définition initiale. Implémentée avec 1.2
ECMAScript 5.1 (ECMA-262)
La définition de 'String.prototype.replace' dans cette spécification.
Standard  
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'String.prototype.replace' dans cette spécification.
Standard  
ECMAScript 2017 Draft (ECMA-262)
La définition de 'String.prototype.replace' dans cette spécification.
Projet  

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
Support simple (Oui) (Oui) (Oui) (Oui) (Oui)
Fonctionnalité Android Chrome pour Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Support simple (Oui) (Oui) (Oui) (Oui) (Oui) (Oui)

Notes spécifiques à Firefox

  • À partir de Gecko 27 (Firefox 27 / Thunderbird 27 / SeaMonkey 2.24), cette méthode a été modifiée pour être conforme à la spécification ECMAScript. Lorsque replace() est appelée avec une expression rationnelle globale, la propriété RegExp.lastIndex, si elle est définie, sera réinitialisée à 0 (bug 501739).
  • À partir de Gecko 39 (Firefox 39 / Thunderbird 39 / SeaMonkey 2.36), les arguments pour les drapeaux (flags) sont dépréciés et déclenchent des avertissements dans la console (bug 1142351).
  • À partir de Gecko 47 (Firefox 47 / Thunderbird 47 / SeaMonkey 2.44), l'argument non-standard flags n'est plus supporté dans les versions hors release et sera bientôt retiré définitivement (bug 1245801).
  • À partir de Gecko 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46), l'argument non-standard flags n'est plus pris en charge (bug 1108382).

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : SphinxKnight, lbesson, davidbourguignon, Grahack, tregagnon, virg, teoli, XenonDeele
 Dernière mise à jour par : SphinxKnight,