String.prototype.replace()

Esta tradução está incompleta. Ajude atraduzir este artigo.

Resumo

O método replace() retorna uma nova string com algum ou todas as combinações do padrão substituído por um substituto. O padrão pode ser uma string ou uma RegExp, e o substituto pode ser uma string ou uma função a ser chamada por cada combinação.

Sintaxe

str.replace(regexp|substr, newSubStr|function[, flags])

Parâmetros

regexp
Um objeto RegExp. a combinação é substituída pelo valor retornado do parâmetro #2.
substr
Uma String que é para ser substituída pela newSubStr.
newSubStr
A String que substitui a substring 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.
Função
A função (function) chamada cria uma nova substring (para ser colocada no lugar da substring recebida pelo parametro #1). The arguments supplied to this function are described in the "Specifying a function as a parameter" section below.
flags

Nota: O argumento flags não funciona no v8 Core (Chrome e NodeJs). 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 a flags correspondente. O valor deste parâmetro se for utilizado deve ser uma string consistindo de um ou mais dos seguintes caracteres para afetar a operação, tais como descrito:

g
combinação global
i
ignorar caso
m
combinação em várias linhas
y
sticky

Retornos

Uma nova string com algum ou todas as combinações do padrão substituído pelo substituidor.

Descrição

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

Para realizar uma pesquisa global e substituir, incluir a chave g na expressão regular ou se o primeiro parâmetro é 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 que 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 combinação for feita. O resultado da função (valor de retorno) 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:

Nome possível Valor
match A substring encontrada. Corresponde ao $& acima
p1, p2, ... O enésimo parâmetro entre parenteses 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 RegExp e de quantas combinações entre parênteses houver.)

O exemplo a seguir irá setar newString para 'abc - 12345 - #$*%':

function replacer(match, p1, p2, p3, offset, string) {
  // p1 is nondigits, p2 digits, and p3 non-alphanumerics
  return [p1, p2, p3].join(' - ');
}
var newString = 'abc12345#$*%'.replace(/([^\d]*)(\d*)([^\w]*)/, replacer);

Exemplos

Definindo expressão regular com replace()

No exemplo a seguir foi definida uma expressão regular com flag 'ignore' na função replace().

var str = 'Twas the night before Xmas...';
var newstr = str.replace(/xmas/i, 'Christmas');
console.log(newstr);  // Twas the night before Christmas...

O resulto é 'Twas the night before Christmas...'

Usando global e ignore com replace()

Substituir globalmente só pode ser feito com uma expressão regular. No exemplo a seguir, a expressão regular inclui as flags global e ignore case que permite a função replace() substituir cada 'apples' por 'oranges' na string.

var re = /apples/gi;
var str = 'Apples are round, and apples are juicy.';
var newstr = str.replace(re, 'oranges');
console.log(newstr);  // oranges are round, and oranges are juicy.

O resultado é: 'oranges are round, and oranges are juicy'.

Trocando palavras em uma String

O script a seguir troca as palavras da string. Para o texto ser substituido, o script usa os padrões $1 e $2.

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

O resultado é: '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 para lower case, e um hífen é inserido antes da ocorrê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 o case 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);
}

Então a chamada: styleHyphenFormat('borderTop') retorna 'border-top'.

Como queremos transformar o resultado do match 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.

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

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

Substituindo graus Fahrenheit para Celsius

O exemplo a seguir substitui graus Fahrenheit para 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 a entrada for 212F, a função deve retornar 100C. Se o número é 0F, a função retorna -17.77777777777778C.

A expressão regular test checa 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 seguinte 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.
Standard  
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'String.prototype.replace' in that specification.
Standard  

Compatibilidade de navegadores

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)

Firefox-specific notes

  • Starting with Gecko 27 (Firefox 27 / Thunderbird 27 / SeaMonkey 2.24), this method has been adjusted to conform with the ECMAScript specification. When replace() is called with a global regular expression, the RegExp.lastIndex property (if specified) will be reset to 0 (bug 501739).

Veja também

Etiquetas do documento e colaboradores

 Colaboradores desta página: BrOrlandi, solangealmn, acdcjunior, mazulo
 Última atualização por: BrOrlandi,