String.prototype.replace()

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.

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

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

Uma nova string com alguma ou todas as combinações do padrão substituído(s) pelo valor de substituiçã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.

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

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:

(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 - #$*%"

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..."

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."

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

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.

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);
}

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.

• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()