String.prototype.replace()

Pruébalo

Sintaxis

Parámetros

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.

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.

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á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.

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.

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:

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

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

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.

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.

Toda la cadena siendo examinada.

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 - #$*%':

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 en replace() e incluye el parámetro ignore case (ignorar mayúsculas y minúsculas).

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

Usando los parámetros global e ignoreCase con replace()

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'.

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 usa grupos de captura y los patrones de reemplazo $1 y $2.

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.

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.

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 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.

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ámetro offset, será trivial si la regex es estáticamente conocida.

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.

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.

Especificaciones

Compatibilidad con navegadores

Enable JavaScript to view this browser compatibility table.

Véase también

• 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]()