String.prototype.replace()

Prubalo

const paragraph = "I think Ruth's dog is cuter than your dog!";

console.log(paragraph.replace("Ruth's", "my"));
// Expected output: "I think my dog is cuter than your dog!"

const regex = /Dog/i;
console.log(paragraph.replace(regex, "ferret"));
// Expected output: "I think Ruth's ferret is cuter than your dog!"

Sintaxis

replace(patrn, reemplazo)

Parmetros

patrn

Puede ser una cadena o un objeto con un mtodo Symbol.replace el ejemplo tpico es una expresin regular. Cualquier valor que no tenga el mtodo Symbol.replace ser convertido a una cadena.

reemplazo

Puede ser una cadena o una funcin.

• Si es una cadena, reemplazar la subcadena que coincida con patrn. Un nmero de patrones de reemplazo especiales son soportados; consulta la seccin Especificando una cadena como el reemplazo.
• Si es una funcin, ser invocada para cada coincidencia y su valor de retorno ser usado como el texto de reemplazo. Los parmetros proporcionados a esta funcin son descritos en la seccin Especificando una funcin como el reemplazo.

Valor de retorno

Una nueva cadena, con una, algunas, o todas las coincidencias de un patrn reemplazadas por el reemplazo especificado.

Descripcin

Este mtodo no cambia el valor de la cadena sobre la que se realiza la llamada. Devuelve una nueva cadena.

Un patrn de cadena solo ser reemplazado una vez. Para realizar una bsqueda y reemplazo global, se debe usar una expresin regular con el parmetro g, o usar replaceAll() en su lugar.

Si patrn es un objeto con un mtodo Symbol.replace (incluyendo objetos de tipo RegExp), ese mtodo es llamado con la cadena objetivo y reemplazo como parmetros. Su valor de retorno se convierte en el valor de retorno de replace(). En este caso el comportamiento de replace() es completamente codificado por el mtodo @@replace por ejemplo, cualquier mencin de "grupos de captura" en la descripcin de abajo es funcionalidad proporcionada por RegExp.prototype[@@replace].

Si el patrn es una cadena vaca, el reemplazo ser aadido al inicio de la cadena.

"xxx".replace("", "_"); // "_xxx"

Una regexp con el parmetro g es el nico caso donde replace() reemplaza ms de una vez. Para ms informacin acerca de cmo interactan las propiedades de una regex (especialmente el paramtro sticky), vase RegExp.prototype[@@replace]().

Especificando una cadena como el reemplazo

La cadena de reemplazo puede incluir los siguientes patrones de reemplazo especiales:

$n y $<Name> solo estn disponibles si el parmetro patrn es un objeto RegExp. Si el patrn es una cadena, o si el correspondiente grupo de captura no est presente en la regex, entonces el patrn ser reemplazado como un literal. Si el grupo est presente pero no tiene ninguna coincidencia (porque es parte de una disyuncin), ser reemplazado con una cadena vaca.

"foo".replace(/(f)/, "$2");
// "$2oo"; la expresin regular no tiene el segundo grupo

"foo".replace("f", "$1");
// "$1oo"; el patrn es una cadena, por lo que no tiene ningn grupo

"foo".replace(/(f)|(g)/, "$2");
// "oo"; el segundo grupo existe pero no tiene coincidencia

Especificando una funcin como el reemplazo

Se puede especificar un funcin como el segundo parmetro. En este caso, la funcin ser invocada despus de haber buscado las coincidencias. El resultado de la funcin (valor de retorno) ser usado como la cadena de reemplazo.

La funcin tiene la siguiente firma:

function replacer(match, p1, p2, /* , */ pN, offset, string, groups) {
  return replacement;
}

Los parmetros para la funcin son los siguientes:

match

La cadena encontrada. (Corresponde a $& de la tabla de arriba).

p1, p2, , pN

La n-sima cadena encontrada por un grupo de captura (incluyendo grupos de captura nombrados), siempre y cuando el primer parmetro para replace() sea un objeto RegExp. (Corresponde a $1, $2, etc. de la tabla de arriba). Por ejemplo, si el patrn es /(\a+)(\b+)/, entonces p1 es la coincidencia para \a+, y p2 es la coincidencia para \b+. Si el grupo es parte de una disyuncin (por ejemplo, "abc".replace(/(a)|(b)/, replacer)), la alternativa que no tenga coincidencia ser undefined.

offset

La posicin de la subcadena encontrada en toda la cadena siendo examinada. Por ejemplo, si toda la cadena fuera 'abcd', y la subcadena encontrada fuera 'bc', entonces este parmetro sera 1.

string

Toda la cadena siendo examinada.

groups

Un objeto del cual las llaves son los nombres de los grupos usados, y del cual los valores son las porciones encontradas (undefined si no hubo ninguna). Solo presente si el patrn contiene al menos un grupo de captura nombrado.

El nmero exacto de parmetros depende de si el primer argumento es un objeto RegExp y, si lo es, de cuantos grupos de captura tenga.

El siguient ejemplo cambiar newString a 'abc - 12345 - #$*%':

function replacer(match, p1, p2, p3, offset, string) {
  // p1 no son dgitos, p2 son dgitos, y p3 no son alfanumricos
  return [p1, p2, p3].join(" - ");
}
const newString = "abc12345#$*%".replace(/([^\d]*)(\d*)([^\w]*)/, replacer);
console.log(newString); // abc - 12345 - #$*%

La funcin ser invocada multiple veces para cada coincidencia completa para ser reemplazada si la expresin regular en el primer parmetro es global.

Ejemplos

Definiendo la expresin regular en replace()

En el siguiente ejemplo, la expresin regular es definida en replace() e incluye el parmetro ignore case (ignorar maysculas y minsculas).

const str = "Twas the night before Xmas...";
const newstr = str.replace(/xmas/i, "Christmas");
console.log(newstr); // Twas the night before Christmas...

Esto imprime 'Twas the night before Christmas...'.

Usando los parmetros global e ignoreCase con replace()

El reemplazo global solo puede ser hecho con una expresin regular. En el siguiente ejemplo, la expresin regular incluye los parmetros global e ignoreCase los cuales permiten a replace() reemplazar cada ocurrencia de 'apples' en la cadena con 'oranges'.

const re = /apples/gi;
const str = "Apples are round, and apples are juicy.";
const newstr = str.replace(re, "oranges");
console.log(newstr); // oranges are round, and oranges are juicy.

Esto imprime 'oranges are round, and oranges are juicy'.

Intercambiando palabras en una cadena

El siguiente cdigo intercambia las palabras en la cadena. Para el texto de reemplazo, el cdigo usa grupos de captura y los patrones de reemplazo $1 y $2.

const re = /(\w+)\s(\w+)/;
const str = "Maria Cruz";
const newstr = str.replace(re, "$2, $1");
console.log(newstr); // Cruz, Maria

Esto imprime 'Cruz, Maria'.

Usando una funcin en lnea que modifica los caracteres encontrados

En este ejemplo, todas las ocurrencias de letras maysculas en la cadena son convertidas a minsculas, y un guion es insertado justo antes de cada ubicacin encontrada. La cosa importante aqu es que operaciones adicionales son necesarias en el elemento encontrado antes de que sea devuelto como un reemplazo.

La funcin de reemplazo acepta la coincidencia encontrada como parmetro, y lo usa para transformar las maysculas a minsculas y para concatenar el guin antes de retornar.

function styleHyphenFormat(propertyName) {
  function upperToHyphenLower(match, offset, string) {
    return (offset > 0 ? "-" : "") + match.toLowerCase();
  }
  return propertyName.replace(/[A-Z]/g, upperToHyphenLower);
}

Dado styleHyphenFormat('borderTop'), esto retorna 'border-top'.

Ya que queremos transformar el resultado de la coincidencia antes de que la sustitucin final sea hecha, debemos usar una funcin. Esto forza la evaluacin de la coincidencia antes del mtodo toLowerCase(). Si hemos intentado hacer esto usando la coincidencia sin una funcin, toLowerCase() no tendr efecto.

// No funcionar
const newString = propertyName.replace(/[A-Z]/g, "-" + "$&".toLowerCase());

Esto es porque '$&'.toLowerCase() sera el primero en ser evaluado como una cadena literal (resultando en el mismo '$&') antes de usar los caracteres como un patrn.

Reemplazando grados Fahrenheit con su equivalente en Celsius

El siguiente ejemplo reemplaza grados Fahrenheit con su equivalente en grados Celsius. Los grados Fahrenheit deben ser un nmero terminado en "F". La funcin retorna el nmero en Celsius terminando con "C". Por ejemplo, si el nmero de entrada es "212F", la funcin retorna "100C". Si el nmero es "0F", la funcin retorna "-17.77777777777778C".

La expresin regular test verifica cualquier nmero que termina con F. El nmero de grados Fahrenheit es accesible para la funcin a travs del segundo parmetro, p1. La funcin establece el nmero Celsius con base en el nmero de grados Fahrenheit pasados como cadena a la funcin f2c(). Entonces f2c() retorna el nmero en Celsius. Esta funcin se aproxima a la bandera de Perl s///e.

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

Creando un reemplazador genrico

Supongamos que queremos crear un reemplazador que agregue la posicin para cada coincidencia encontrada. Ya que la funcin de reemplazo ya recibe el parmetro offset, ser trivial si la regex es estticamente conocida.

"abcd".replace(/(bc)/, (match, p1, offset) => `${match} (${offset}) `);
// "abc (1) d"

Sin embargo, este reemplazador debera ser ms difcil de generalizar si queremos que trabaje con cualquier expresin regular. El reemplazador es variadic el nmero de parmetros que recibe depende del nmero de grupos de captura presentes. Podemos usar parmetros rest, pero tambin recolectara offset, string, etc. en el arreglo. El hecho de que groups pueda o no ser pasado dependiendo de la identidad de la regex tambin haria difcil conocer genricamente cul argumento corresponde al offset.

function addOffset(match, ...args) {
  const offset = args.at(-2);
  return `${match} (${offset}) `;
}

console.log("abcd".replace(/(bc)/, addOffset)); // "abc (1) d"
console.log("abcd".replace(/(?<group>bc)/, addOffset)); // "abc (abcd) d"

El ejemplo addOffset de arriba no funciona cuando regex contiene un grupo nombrado, porque en este caso args.at(-2) sera el string en lugar del offset.

En su lugar, es necesario extraer los ltimos parmetros con base en su tipo, porque groups es un objeto mientras string es una cadena.

function addOffset(match, ...args) {
  const hasNamedGroups = typeof args.at(-1) === "object";
  const offset = hasNamedGroups ? args.at(-3) : args.at(-2);
  return `${match} (${offset}) `;
}

console.log("abcd".replace(/(bc)/, addOffset)); // "abc (1) d"
console.log("abcd".replace(/(?<group>bc)/, addOffset)); // "abc (1) d"

Especificaciones

Compatibilidad con navegadores

Vase tambin

• Polyfill de String.prototype.replace en core-js con arreglos e implementacin de un comportamiento moderno como el soporte para Symbol.replace
• String.prototype.replaceAll()
• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()
• Symbol.replace
• RegExp.prototype[@@replace]()