String.prototype.replaceAll()
=============================

El método **`replaceAll()`** retorna una nueva cadena con todas las coincidencias de un `patrón` reemplazadas por un `reemplazo`. El `patrón` puede ser una cadena o un objeto `RegExp`, y el `reemplazo` puede ser una cadena o una función que será llamada para cada coincidencia. La cadena original permanecerá inalterada.

Pruébalo
--------

Sintasix
--------


```js
replaceAll(patrón, reemplazo)
```

### Parámetros

`patrón`

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

Si `patrón` es una *regex*, entonces debe tener el parámetro global (`g`) establecido, o un `TypeError` es lanzado.

`reemplazo`

Puede ser una cadena o una función. El reemplazo tiene la misma semántica que la de `String.prototype.replace()`.

### Valor de retorno

Una nueva cadena, con todas las coincidencias de un patrón reemplazadas por un reemplazo.

### Excepciones

`TypeError`

Lanzado si el `patrón` es una *regex* que no tiene el parámetro global (`g`) configurado (su propiedad `flags` (en-US) no contiene `"g"`)

Descripción
-----------

Este método no modifica el valor de la cadena en la que es ejecutado. Regresa una nueva cadena.

A diferencia de `replace()`, este método reemplazará todas las coincidencias de una cadena, no solo la primera. Esto es especialmente útil si la cadena no es estáticamente conocida, como llamando al contructor del objeto `RegExp()` sin escapar caracteres especiales podría cambiar su semántica sin intención.


```js
function unsafeRedactName(text, name) {
  return text.replace(new RegExp(name, "g"), "[REDACTED]");
}
function safeRedactName(text, name) {
  return text.replaceAll(name, "[REDACTED]");
}

const report =
  "A hacker called ha.\*er used special characters in their name to breach the system.";

console.log(unsafeRedactName(report, "ha.\*er")); // "A [REDACTED]s in their name to breach the system."
console.log(safeRedactName(report, "ha.\*er")); // "A hacker called [REDACTED] used special characters in their name to breach the system."
```


Si el `patrón` es un objeto con un método `Symbol.replace` (incluyendo objetos `RegExp`), ese método es llamado con la cadena objetivo y `reemplazo` como argumento. Su valor de retorno se convierte en el valor de retorno de `replaceAll()`. En este caso el comportamiento de `replaceAll()` es enteramente codificado por el método `@@replace`, y por lo tanto tendrá el mismo resultado que `replace()` (aparte de la validación extra de que *regex* es global).

Si el `patrón` es una cadena vacía, el reemplazo será insertado entre cada unidad de código UTF-16, similar al comportamiento de `split()`.


```js
"xxx".replaceAll("", "\_"); // "\_x\_x\_x\_"
```


Para más información acerca de cómo interactúan las propiedades de una *regex* (especialmente el paramétro sticky (en-US)), véase `RegExp.prototype[@@replace]()` (en-US).

Ejemplos
--------

### Usando replaceAll()


```js
"aabbcc".replaceAll("b", ".");
// 'aa..cc'
```

### Excepciones de una regex no global

Cuando se usa una expresión regular como valor de búsqueda, ésta debe ser global. Esto no funcionará:


```js
"aabbcc".replaceAll(/b/, ".");
// TypeError: replaceAll must be called with a global RegExp
```


Esto sí funcionará:


```js
"aabbcc".replaceAll(/b/g, ".");
// "aa..cc"
```

Especificaciones
----------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.replaceall |

Compatibilidad con navegadores
------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Véase también
-------------

* Polyfill de `String.prototype.replaceAll` en `core-js`
* `String.prototype.replace()`
* `String.prototype.match()`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`