String.prototype.replace()
==========================

Resumo
------

O método `replace()` retorna uma nova string com algumas ou todas as correspondências de um padrão substituídas por um determinado caractere (ou caracteres). 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 correspondência. Se o padrão for uma string, apenas a primeira ocorrência será substituída.

A string original não é modificada.

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

Sintaxe
-------
```

str.replace(regexp|substr, newSubStr|function)
```

### Parâmetros

`regexp`

Um objeto `RegExp` ou literal. A correspondência ou correspondências são substituídas por *`newSubStr`* ou o valor retornado pela `function` especificada.

`substr`

Uma `String` que será substituída por `newSubStr`. Ele é tratado como uma string textual e não é interpretado como uma expressão regular. Apenas a primeira ocorrência será substituída.

`newSubStr`

A `String` que substitui a `substr` recebida do parâmetro #1. Uma série de padrões de substituições especiais são suportados. Veja a seção "

Especificando uma string como parâmetro

" abaixo.

`function`

A função (function) chamada cria uma nova substring (para ser colocada no lugar da substring recebida pelo parametro #1). Os argumentos fornececidos para essa função estão descritos na seção "

Especificando uma função como parâmetro

" mais abaixo.

`flags` 
Non-standard

Uma string especificando uma combinação de flags de expressão regular. O uso do parâmetro `flags` no método `String.prototype.replace()` é não-padrão. Ao invés de usar este parâmetro, use um objeto `RegExp` com as flags correspondentes. O valor deste parâmetro deve ser uma string consistindo em um ou mais dos seguintes caracteres para afetar a operação, tais como descrito:

`g`

Combinação global.

`i`

Ignora diferenças entre maiúsculas e minúsculas.

`m`

Combinação em várias linhas.

`y` 
Experimental

Sticky


> 
> \*\*Nota:\*\*O argumento `flags` não funciona no v8 Core (Chrome e NodeJs).
> 
> 
> 

### Valor retornado

Uma nova string com alguma ou todas as combinações do padrão substituído(s) pelo valor de substituição.

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

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

Para realizar uma pesquisa global e substituir, inclua a flag `g` na expressão regular ou se o primeiro parâmetro for uma string, inclua `g` no parâmetro flags.

### Especificando uma string como parâmetro

A string substituidora pode incluir o seguinte padrão de substituição especial:

| **Padrão** | **Insere** |
| --- | --- |
| `$$` | Insere um "$". |
| `$&` | Insere a string casada. |
| `$`` | Insere a porção da string que precede a substring combinada. |
| `$'` | Insere a porção da string que segue a substring combinada. |
| `$n` ou `$nn` | Onde `n` ou `nn` são dígitos decimais, insere a *n*-ésima substring entre parêntesis casada, dado o primeiro argumento foi um objeto `RegExp`. |

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

Você pode especificar uma função no segundo parâmetro. Neste caso, a função será chamada depois que a correspôndecia for encontrada. O resultado da função (valor retornado) será usado como a string substituta. (Atenção: os padrões de substituição citados acima não se aplicam neste caso). Note que a função será chamada múltiplas vezes para combinação que deve ser substituída se a expressão regular no primeiro parâmetro tiver a regra global.

Os parâmetros da função são:

| **Possíveis nomes** | **Valor fornecido** |
| --- | --- |
| `match` | A substring encontrada. Corresponde ao `$&` acima. |
| `p1, p2, ...` | O enésimo parâmetro entre parênteses da RegEx no primeiro parâmetro na função `replace()` `RegExp`. (Corresponde a `$1`, `$2`, etc. acima.) Por exemplo, se `/(\a+)(\b+)/`, for o primeiro parâmetro, `p1` é a combinação para `\a+`, e `p2` para `\b+`. |
| `offset` | O offset da string encontrada em relação ao resto da string. Por exemplo, se a string for 'abcd' e a string a ser encontrada for 'bc', então este parâmetro terá o valor 1. |
| `string` | A string completa que está sendo examinada. |

(O número exato de argumentos dependerá se o primeiro parâmetro for uma `RegExp` e de quantas combinações entre parênteses houver).

O exemplo a seguir irá substituir o valor de `newString` para `'abc - 12345 - #$*%'`:


```js
function replacer(match, p1, p2, p3, offset, string) {
  // p1 não possui digitos,
  // p2 possui dígitos, e p3 não possui alfanuméricos
  return [p1, p2, p3].join(" - ");
}
var newString = "abc12345#$\*%".replace(/([^\d]\*)(\d\*)([^\w]\*)/, replacer);

// retorna "abc - 12345 - #$\*%"
```

Exemplos
--------

### Definindo uma expressão regular com `replace()`

No exemplo a seguir foi definida uma expressão regular com a flag "`i`" (que ignora diferenças entre maiúsculas e minúsculas) no método `replace()`.


```js
var str = "Twas the night before Xmas...";
var newstr = str.replace(/xmas/i, "Christmas");

console.log(newstr);
// retorna "Twas the night before Christmas..."
```


**Nota:** Veja este guia para maiores explicações as sobre expressões regulares.

### Usando `global` e `ignore` com `replace()`

Substituir globalmente, "`g`", só pode ser feito com uma expressão regular. No exemplo a seguir, a expressão regular inclui as flags global e ignore que permitem a função `replace()` substituir cada "`maçãs`" por "`laranjas`" na string.


```js
var re = /maçãs/gi;
var str = "As maçãs são redondas. As maçãs são suculentas.";
var newstr = str.replace(re, "laranjas");

console.log(newstr);
// retorna
// "As laranjas são redondas. As laranjas são suculentas."
```

### Trocando palavras em uma string

O script a seguir troca as palavras na string. Para o texto que vai substituir, o script usa grupos de captura (en-US) e os padrões de substituição `$1` e `$2`.


```js
var re = /(\w+)\s(\w+)/;
var str = "John Smith";
var newstr = str.replace(re, "$2, $1");
console.log(newstr); // Smith, John
```

### Usando uma função que modifica os caracteres coincidentes

Neste exemplo, todas as ocorrências de letras maiúsculas na string são convertidas em minúsculas e um hífen é inserido antes do local de correspondência. O importante aqui é que é necessário uma operação adicional no item antes dele ser retornado como substituído.

A função de substituição aceita a string coincidida como parâmetro e usa ela para transformar os caracteres e concatenar um hífen antes de retornar.


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


Dado o seguinte parâmetro: `styleHyphenFormat('borderTop')`, o valor retornado é '`border-top`'.

Como queremos transformar o resultado da coincidencia antes da substituição final, nós devemos usar uma função. Isto força que a transformação seja feita antes da chamada do método `toLowerCase()`. Se tivéssemos tentado isto sem a função, o método `toLowerCase()` não teria efeito.


```js
let newString = propertyName.replace(/[A-Z]/g, "-" + "$&".toLowerCase()); // não funciona
```


Isso acontece porque `'$&'.toLowerCase()` será executada antes (resultando no mesmo que `'$&'`) em vez de usar os caracteres da string a ser transformada.

### Substituindo graus Fahrenheit em Celsius

O exemplo a seguir converte graus Fahrenheit em Celsius. O grau Fahrenheit deve ser um número terminado com "`F`". A função retorna o número em Celsius terminando em "`C`". Por exemplo, se o valor de entrada for "`212F`", a função deve retornar "`100C`". Se o número for "`0F`", a função deve retornar "`-17.77777777777778C`".

A expressão regular `test` verifica por números que terminem com "`F`". O número de graus Fahrenheit é acessível pela função pelo segundo parâmetro, `p1`. A função calcula o Celsius baseado no Fahrenheit passado via string para a função `f2c()`. A `f2c()` então retorna o número em Celsius.


```js
function f2c(x) {
  function convert(str, p1, offset, s) {
    return ((p1 - 32) \* 5) / 9 + "C";
  }
  var s = String(x);
  var test = /(-?\d+(?:\.\d\*)?)F\b/g;
  return s.replace(test, convert);
}
```

### Use uma função com expressão regular para evitar loops for

O exemplo a seguir pega um padrão de string e converte em um array de objetos.

**Entrada:**

Uma string com caracteres: `x`, `-` e `_`
```

x-x_
x---x---x---x---
x-xxx-xx-x-
x_x_x___x___x___
```


**Saída:**

Um array de objetos. Um `'x'` denota um estado `'on'`, um `'-'` (hífen) denota um estado `'off'` e um `'_'` (underline) denota o comprimento do estado `'on'`.
```

[
  { on: true, length: 1 },
  { on: false, length: 1 },
  { on: true, length: 2 }
  ...
]
```


**Código:**


```js
var str = "x-x\_";
var retArr = [];
str.replace(/(x\_\*)|(-)/g, function (match, p1, p2) {
  if (p1) {
    retArr.push({ on: true, length: p1.length });
  }
  if (p2) {
    retArr.push({ on: false, length: 1 });
  }
});

console.log(retArr);
```


O código gera um array de 3 objetos como desejado sem usar uma função de loop.

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

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

Navegadores compatíveis
-----------------------

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

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

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