El métodoreplace() devuelve una nueva cadena con una, algunas, o todas las coincidencias de unpatrón, siendo cada una de estas coincidencias reemplazadas por unreemplazo. Elpatrón puede ser una cadena o un objetoRegExp, y elreemplazo puede ser una cadena o una función que será llamada para cada coincidencia. Si elpatrón es una cadena, sólo la primera coincidencia será reemplazada. La cadena original permanecerá inalterada.

Pruébalo

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(patrón, reemplazo)

Parámetros

patrón

Puede ser una cadena o un objeto con un métodoSymbol.replace — el ejemplo típico es unaexpresión regular. Cualquier valor que no tenga el métodoSymbol.replace será convertido a una cadena.

reemplazo

Puede ser una cadena o una función.

• Si es una cadena, reemplazará la subcadena que coincida conpatrón. Un número de patrones de reemplazo especiales son soportados; consulta la secciónEspecificando una cadena como el reemplazo.
• Si es una función, será invocada para cada coincidencia y su valor de retorno será usado como el texto de reemplazo. Los parámetros proporcionados a esta función son descritos en la secciónEspecificando una función como el reemplazo.

Valor de retorno

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

Descripción

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

Un patrón de cadena solo será reemplazado una vez. Para realizar una búsqueda y reemplazo global, se debe usar una expresión regular con el parámetrog, o usarreplaceAll() en su lugar.

Sipatrón es un objeto con un métodoSymbol.replace (incluyendo objetos de tipoRegExp), ese método es llamado con la cadena objetivo yreemplazo como parámetros. Su valor de retorno se convierte en el valor de retorno dereplace(). En este caso el comportamiento dereplace() es completamente codificado por el método@@replace — por ejemplo, cualquier mención de "grupos de captura" en la descripción de abajo es funcionalidad proporcionada porRegExp.prototype[@@replace].

Si elpatrón es una cadena vacía, el reemplazo será añadido al inicio de la cadena.

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

Unaregexp con el parámetrog es el único caso dondereplace() reemplaza más de una vez. Para más información acerca de cómo interactúan las propiedades de unaregex (especialmente el paramétrosticky), véaseRegExp.prototype[@@replace]().

Especificando una cadena como el reemplazo

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

$n y$<Name> solo están disponibles si el parámetropatrón es un objetoRegExp. Si elpatrón es una cadena, o si el correspondiente grupo de captura no está presente en laregex, entonces el patrón será reemplazado como un literal. Si el grupo está presente pero no tiene ninguna coincidencia (porque es parte de una disyunción), será reemplazado con una cadena vacía.

"foo".replace(/(f)/, "$2");// "$2oo"; la expresión regular no tiene el segundo grupo"foo".replace("f", "$1");// "$1oo"; el patrón es una cadena, por lo que no tiene ningún grupo"foo".replace(/(f)|(g)/, "$2");// "oo"; el segundo grupo existe pero no tiene coincidencia

Especificando una función como el reemplazo

Se puede especificar un función como el segundo parámetro. En este caso, la función será invocada después de haber buscado las coincidencias. El resultado de la función (valor de retorno) será usado como la cadena de reemplazo.

La función tiene la siguiente firma:

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

Los parámetros para la función son los siguientes:

match

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

p1, p2, …, pN

Lan-sima cadena encontrada por un grupo de captura (incluyendo grupos de captura nombrados), siempre y cuando el primer parámetro parareplace() sea un objetoRegExp. (Corresponde a$1,$2, etc. de la tabla de arriba). Por ejemplo, si elpatrón es/(\a+)(\b+)/, entoncesp1 es la coincidencia para\a+, yp2 es la coincidencia para\b+. Si el grupo es parte de una disyunción (por ejemplo,"abc".replace(/(a)|(b)/, replacer)), la alternativa que no tenga coincidencia seráundefined.

offset

La posición 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 parámetro sería1.

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 elpatrón contiene al menos un grupo de captura nombrado.

El número exacto de parámetros depende de si el primer argumento es un objetoRegExp — 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 dígitos, p2 son dígitos, y p3 no son alfanuméricos  return [p1, p2, p3].join(" - ");}const newString = "abc12345#$*%".replace(/([^\d]*)(\d*)([^\w]*)/, replacer);console.log(newString); // abc - 12345 - #$*%

La función será invocada multiple veces para cada coincidencia completa para ser reemplazada si la expresión regular en el primer parámetro es global.

Ejemplos

Definiendo la expresión regular en replace()

En el siguiente ejemplo, la expresión regular es definida enreplace() e incluye el parámetroignore case (ignorar mayúsculas y minúsculas).

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 parámetrosglobal eignoreCase con replace()

El reemplazo global solo puede ser hecho con una expresión regular. En el siguiente ejemplo, la expresión regular incluyelos parámetrosglobal eignoreCase los cuales permiten areplace() 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 código intercambia las palabras en la cadena. Para el texto de reemplazo, el código usagrupos 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 función en línea que modifica los caracteres encontrados

En este ejemplo, todas las ocurrencias de letras mayúsculas en la cadena son convertidas a minúsculas, y un guion es insertado justo antes de cada ubicación encontrada. La cosa importante aquí es que operaciones adicionales son necesarias en el elemento encontrado antes de que sea devuelto como un reemplazo.

La función de reemplazo acepta la coincidencia encontrada como parámetro, y lo usa para transformar las mayúsculas a minúsculas y para concatenar el guión antes de retornar.

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

DadostyleHyphenFormat('borderTop'), esto retorna'border-top'.

Ya que queremos transformar elresultado de la coincidencia antes de que la sustitución final sea hecha, debemos usar una función. Esto forza la evaluación de la coincidencia antes del métodotoLowerCase(). Si hemos intentado hacer esto usando la coincidencia sin una función,toLowerCase() no tendrá efecto.

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

Esto es porque'$&'.toLowerCase() sería el primero en ser evaluado como una cadena literal (resultando en el mismo'$&') antes de usar los caracteres como un patrón.

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 número terminado en"F". La función retorna el número en Celsius terminando con"C". Por ejemplo, si el número de entrada es"212F", la función retorna"100C". Si el número es"0F", la función retorna"-17.77777777777778C".

La expresión regulartest verifica cualquier número que termina conF. El número de grados Fahrenheit es accesible para la función a través del segundo parámetro,p1. La función establece el número Celsius con base en el número de grados Fahrenheit pasados como cadena a la funciónf2c(). Entoncesf2c() retorna el número en Celsius. Esta función se aproxima a la bandera de Perls///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 genérico

Supongamos que queremos crear un reemplazador que agregue la posición para cada coincidencia encontrada. Ya que la función de reemplazo ya recibe el parámetrooffset, será trivial si laregex es estáticamente conocida.

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

Sin embargo, este reemplazador debería ser más difícil de generalizar si queremos que trabaje con cualquier expresión regular. El reemplazador esvariadic — el número de parámetros que recibe depende del número de grupos de captura presentes. Podemos usarparámetros rest, pero también recolectaríaoffset,string, etc. en el arreglo. El hecho de quegroups pueda o no ser pasado dependiendo de la identidad de laregex también haria difícil conocer genéricamente cuál argumento corresponde aloffset.

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 ejemploaddOffset de arriba no funciona cuandoregex contiene un grupo nombrado, porque en este casoargs.at(-2) sería elstring en lugar deloffset.

En su lugar, es necesario extraer los últimos parámetros con base en su tipo, porquegroups es un objeto mientrasstring 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

Véase también

• Polyfill deString.prototype.replace encore-js con arreglos e implementación de un comportamiento moderno como el soporte paraSymbol.replace
• String.prototype.replaceAll()
• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()
• Symbol.replace
• RegExp.prototype[@@replace]()