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

O método `replaceAll()` retorna uma nova string com todas as ocorrências de um padrão substituídas por uma substituição. O padrão pode ser uma string ou uma `RegExp`, e a substituição pode ser uma string ou uma função a ser chamada para cada ocorrência.

A *string* original é mantida sem modificação.

Experimente
-----------

Sintaxe
-------
```

const newStr = str.replaceAll(regexp|substr, newSubstr|function)
```


**Nota:** quando usar uma `regexp`, você deve colocar o sinalizador (flag) global "`g`". Do contrário, será retornado um `TypeError`: "*replaceAll must be called with a global RegExp*".

### Parâmetros

`regexp` (padrão)

Uma `RegExp` ou literal com o sinalizador (flag) global. As ocorrências serão substituídas por *`newSubstr`* ou pelo valor retornado da *`function`* (função) especificada.

`substr` (padrão)

Uma `String` que deve ser substituída por `newSubstr`. É tratada como uma string literal e não é interpretada como uma expressão regular (*`RegExp`*).

`newSubstr` (substituição)

É a `String` que substitui a `substring` especificada pelo parâmetro `regexp` ou `substr`. Um número de padrões especiais para substituição são suportados; veja a seção "

Especificando uma string como parâmetro

" abaixo.

`function` (substituição)

Uma função a ser chamada retornando a nova `substring` a ser usada para substituir as correspondências para a dada `regexp` ou `substr`. Os argumentos passados para esta função são descritos na seção "Especificando uma função como parâmetro" abaixo.

### Valor de retorno

Um nova *string*, com todas as ocorrências de um padrão substituído por uma substituição.

Descrição
---------

Este método não muda o objeto `String` original. Ele simplesmente retorna uma nova *string*.

### Especificando uma string como parâmetro

A *string* de substituição pode incluir os seguimentos padrões especiais de substituição:

| Padrão | Insere |
| --- | --- |
| `$$` | Insere um `"$"`. |
| `$&` | Insere a *substring* correspondente. |
| `$`` | Insere a porção da *string* que precede a *substring* correspondente. |
| `$'` | Insere a porção da *string* que sucede a *substring* correspondente. |
| `$n` | Onde `n` é um inteiro positivo menor que 100, insere a *`n`*-ésima *string* submatch entre parênteses, desde que o primeiro argumento seja um objeto `RegExp`. Note que isso é indexado começando pelo `1`. |

### Especificando uma função como parâmetro

Você pode especificar uma função como segundo parâmetro. Neste caso, a função será chamada depois da ocorrência ter sido encontrada. O resultado da função (valor de retorno) será usado como uma *string* para substituição. (**Nota:** Os padrões especiais mencionados acima **não se aplicam** neste caso.)

Note que a função será chamada múltiplas vezes para cada ocorrência a ser substituída se a expressão regular no primeiro parâmetro for global "`g`".

Os argumentos para funções são os seguintes:

| Nome possível | Valor fornecido |
| --- | --- |
| `match` | A *substring* correspondida. (Corresponde ao `$&` acima.) |
| `p1, p2, ...` | A *n*-ésima string encontrada por um grupo de captura entre parênteses, desde que o primeiro argumento para `replace()` seja uma `RegExp`. (Corresponde a `$1`, `$2`, etc. acima.) Por exemplo, se `/(\a+)(\b+)/`, foi dado, `p1` é a correspondência para `\a+`, e `p2` para `\b+`. |
| `offset` | O deslocamento da substring correspondente em toda a string sendo examinada. (Por exemplo, se toda a string for '`abcd`' e a substring correspondente for '`bc`', este argumento será `1`.) |
| `string` | A *string* inteira será examinada. |

(O número exato de argumentos depende se o primeiro argumento é um objeto `RegExp` — e, se então, quantas *subcorrespondências* entre parênteses são especificadas.)

Exemplos
--------

### Usando `replaceAll()`


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

### RegExp sem flag "g" retorando erro

Ao usar uma expressão regular para realizar uma pesquisa, a mesma deve conter a flag global "`g`". O código abaixo não irá funcionar:


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


Já o código abaixo vai funcionar:


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

Especificações
--------------

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

Compatibilidade com navegadores
-------------------------------

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

Veja também
-----------

* `String.prototype.replace()`
* `String.prototype.match()`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`