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 ou les correspondances seront remplacées 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 :

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 :

(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___

[
  { on: true, length: 1 },
  { on: false, length: 1 },
  { on: true, length: 2 }
  ...
]

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);

Spécifications

Compatibilité des navigateurs

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

• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()