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.

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

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

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

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.

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 e os padrões de substituição $1 e $2.

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.

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.

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.

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:

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

Especificação Status Comentário
ECMAScript 3rd Edition. Standard Defnição inicial. Implementado no JavaScript 1.2.
ECMAScript 5.1 (ECMA-262)
The definition of 'String.prototype.replace' in that specification.
Padrão
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'String.prototype.replace' in that specification.
Padrão
Estamos convertendo nossos dados de compatibilidade para o formato JSON. Esta tabela de compatibilidade ainda usa o formato antigo, pois ainda não convertemos os dados que ela contém. Descubra como você pode ajudar!
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support (Yes) (Yes) (Yes) (Yes) (Yes)
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)

Notas específicas do Firefox

  • Começando no Gecko 27 (Firefox 27 / Thunderbird 27 / SeaMonkey 2.24), esse método foi ajustado conforme as especificações do ECMAScript. Quando replace() é chamado com uma expressão regular global, a propriedade RegExp.lastIndex (se especificada) será resetada para 0 (bug 501739).

Veja também