String.prototype.replace()

patrón

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

reemplazo

Puede ser una cadena o una función.

• Si es una cadena, reemplazará la subcadena que coincida con patrón. Un número de patrones de reemplazo especiales son soportados; consulta la sección Especificando 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ón Especificando una función como el reemplazo.

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

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ámetro g, o usar replaceAll() en su lugar.

Si patrón es un objeto con un método Symbol.replace (incluyendo objetos de tipo RegExp), ese método es llamado con la cadena objetivo y reemplazo como parámetros. 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 método @@replace — por ejemplo, cualquier mención de "grupos de captura" en la descripción de abajo es funcionalidad proporcionada por RegExp.prototype[@@replace].

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

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

Una regexp con el parámetro g es el único caso donde replace() reemplaza más de una vez. Para más información acerca de cómo interactúan las propiedades de una regex (especialmente el paramétro sticky), véase 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 están disponibles si el parámetro patrón es un objeto RegExp. Si el patrón es una cadena, o si el correspondiente grupo de captura no está presente en la regex, 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

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

La n-sima cadena encontrada por un grupo de captura (incluyendo grupos de captura nombrados), siempre y cuando el primer parámetro para replace() sea un objeto RegExp. (Corresponde a $1, $2, etc. de la tabla de arriba). Por ejemplo, si el patrón es /(\a+)(\b+)/, entonces p1 es la coincidencia para \a+, y p2 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ía 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 patrón contiene al menos un grupo de captura nombrado.

El número exacto de parámetros 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 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.

En el siguiente ejemplo, la expresión regular es definida en replace() e incluye el parámetro ignore 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...'.

El reemplazo global solo puede ser hecho con una expresión regular. En el siguiente ejemplo, la expresión regular incluye los parámetros 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'.

El siguiente código intercambia las palabras en la cadena. Para el texto de reemplazo, el código 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'.

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

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

Ya que queremos transformar el resultado 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étodo toLowerCase(). 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.

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 regular test verifica cualquier número que termina con F. 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ón f2c(). Entonces f2c() retorna el número en Celsius. Esta función 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);
}

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ámetro offset, será trivial si la regex 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 es variadic — el número de parámetros que recibe depende del número de grupos de captura presentes. Podemos usar parámetros rest, pero también recolectaría offset, string, etc. en el arreglo. El hecho de que groups pueda o no ser pasado dependiendo de la identidad de la regex también haria difícil conocer genéricamente cuál 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) sería el string en lugar del offset.

En su lugar, es necesario extraer los últimos parámetros 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"

• Polyfill de String.prototype.replace en core-js con arreglos e implementación 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]()