pregReplace

Substitui todas as ocorrências de uma expressão regular.

Sintaxe

string pregReplace ( string texto, string padrao, string substituto [, int/string flags = 0 ] )

Parâmetros

Nome	Tipo	Padrão	Descrição
texto	string	—	Texto a transformar. Um número vira texto.
padrao	string	—	Expressão regular.
substituto	string	—	No que cada ocorrência se transforma. $1 ou ${1} insere um grupo de captura, $0 a ocorrência inteira e $$ um cifrão literal.
flags	int ou string	0	Opções de busca — veja abaixo.

O argumento flags é um número — a soma dos bits abaixo — ou uma string com as letras:

Letra	Bit	Efeito
i	1	Não diferencia maiúsculas de minúsculas.
m	2	Multilinha: ^ e $ também casam nas quebras de linha.
d	4	Dot-all: . também casa com uma quebra de linha.
e	8	Estendido: espaços e comentários # dentro do padrão são ignorados.
u	16	UTF-8: padrão e texto são lidos como UTF-8, e \w, \d e afins seguem o Unicode.

Uma string com qualquer outra letra registra Bad usage @ '<função>' [Flags all wrong] e a chamada devolve false; um número negativo também. Qualquer outro tipo — nil, um booleano — significa sem flags.

Retorno

O texto com todas as ocorrências substituídas. Quando nada casou, devolve false, e não o texto original — então escreva pregReplace(...) or texto se quiser sempre uma string de volta. Um padrão que não compila também dá false, sem aviso, e um argumento inválido registra um aviso e devolve false.

O resultado termina no primeiro byte zero, se o texto tiver um.

Os padrões usam a sintaxe do PCRE2. Cada busca tem um teto fixo de trabalho de backtracking, então um padrão patológico para de casar em vez de travar o script.

Exemplo

local arrumado = pregReplace("espaços    demais   aqui", "\\s+", " ") or ""
-- "espaços demais aqui"

local invertido = pregReplace("Maria Silva", "(\\w+) (\\w+)", "$2, $1")
-- "Silva, Maria"

Veja também

• getUserdataType — Diz que tipo de handle um userdata é.
• pregFind — Diz se uma expressão regular casa com uma string.
• pregMatch — Junta todas as ocorrências de uma expressão regular.