Funções IsMatch, Match e MatchAll
Aplica-se a:
Aplicativos de tela Aplicativos baseados em modelo CLI do Power Platform
Testa uma correspondência ou extrai partes de uma cadeia de texto com base em um padrão.
Descrição
A função IsMatch testa se uma cadeia de texto corresponde a um padrão que pode incluir caracteres comuns, padrões predefinidos, ou uma expressão regular. As funções Match e MatchAll retornam o que foi correspondido, incluindo subcorrespondências.
Use IsMatch para validar o que um usuário digitou em um controle Text input. Por exemplo, você pode confirmar se o usuário inseriu um endereço de email válido antes do resultado ser salvo em sua fonte de dados. Se a entrada não corresponder aos seus critérios, adicione outros controles que solicitam que o usuário corrija a entrada.
Use Match para extrair a primeira cadeia de texto que corresponde a um padrão e MatchAll para extrair todas as cadeias de texto correspondentes. Você também pode extrair subcorrespondências para analisar cadeias de caracteres complexas.
Match retorna um registro de informações para a primeira correspondência encontrada e MatchAll retorna uma tabela de registros para cada correspondência encontrada. O registro ou os registros contêm:
| Column | Type | Description |
|---|---|---|
| subcorrespondência nomeada ou subcorrespondências | Texto | Cada subcorrespondência nomeada terá sua própria coluna. Crie uma subcorrespondência nomeada usando (?<nome>...) na expressão regular. Se uma subcorrespondência nomeada tiver o mesmo nome que uma das colunas predefinidas (abaixo), a subcorrespondência terá precedência e um aviso será gerado. Para evitar esse aviso, renomeie a subcorrespondência. |
| FullMatch | Text | Toda a cadeia de texto que foi correspondida. |
| StartMatch | Número | A posição inicial da correspondência na cadeia de texto de entrada. O primeiro caractere da cadeia de caracteres retorna 1. |
| Subcorrespondentes | Tabela de coluna única de texto (coluna Valor) | A tabela de subcorrespondências nomeadas e sem nome na ordem em que aparecem na expressão regular. Geralmente, as subcorrespondências nomeadas são mais fáceis de trabalhar e são incentivadas. Use a função ForAll ou as funções Last( FirstN( ... ) ) para trabalhar com uma subcorrespondência individual. Se nenhuma subcorrespondência for definida na expressão regular, essa tabela estará presente, mas vazia. |
Essas funções dão suporte a MatchOptions. Por padrão:
- Essas funções executam uma correspondência que diferencia maiúsculas de minúsculas. Use MatchOptions.IgnoreCase para executar correspondências que não diferenciam maiúsculas de minúsculas.
- IsMatch corresponde à cadeia de texto inteira (Complete MatchOption), enquanto Match e MatchAll pesquisam uma correspondência em qualquer lugar na cadeia de texto (Contains MatchOption). Use Complete, Contains, BeginsWith ou EndsWith conforme apropriado para seu cenário.
IsMatch retornará true se a cadeia de texto corresponder ao padrão ou false se não corresponder. Match retornará blank se não for encontrada nenhuma correspondência que possa ser testada com a função IsBlank. MatchAll retornará uma tabela vazia se não for encontrada nenhuma correspondência que possa ser testada com a função IsEmpty.
Se você estiver usando o MatchAll para dividir uma cadeia de texto, considere usar a função Split, que é mais simples de usar e mais rápida.
Padrões
A chave para usar essas funções é descrever o padrão para corresponder. Você descreve o padrão em uma cadeia de texto como uma combinação de:
- Caracteres normais, como "abc" ou "123".
- Padrões predefinidos, como letra, MultipleDigits, ou Email. (A enumeração Match define esses padrões.)
- Códigos de expressões regulares, como "\d+\s+\d+" ou "[a-z] +".
Combinar esses elementos usando o operador de concatenação de cadeia de caracteres &. Por exemplo, "abc" & Digit & "\s+" é um padrão válido que corresponde aos caracteres "a", "b" e "c", seguido por um dígito de 0 a 9, seguido por, pelo menos, um caractere de espaço em branco.
Caracteres comuns
O padrão mais simples é uma sequência de caracteres comuns a ser correspondida exatamente.
Por exemplo, quando usado com a função IsMatch , a cadeia de caracteres "Hello" corresponde ao padrão "Hello" exatamente. Nem mais, nem menos. A cadeia de caracteres "olá!" não corresponde ao padrão por causa do ponto de exclamação no final e porque a correspondência de maiúscula e minúscula é incorreta para a letra "h". (Consulte MatchOptions para maneiras de modificar esse comportamento.)
No idioma padrão, determinados caracteres são reservados para fins especiais. Para usar esses caracteres, prefixe o caractere com \ (barra invertida) para indicar que o caractere deve ser levado literalmente ou use um dos padrões predefinidos descritos posteriormente neste tópico. Esta tabela lista os caracteres especiais:
| Caractere especial | Descrição |
|---|---|
| . | ponto |
| ? | ponto de interrogação |
| * | asterisco |
| + | positivo |
| ( ) | parênteses |
| [ ] | colchetes |
| { } | chaves |
| ^ | caret |
| $ | cifrão |
| | | barra vertical ou pipe |
| \ | barra invertida |
Por exemplo, você pode corresponder "Olá?" usando o padrão "Olá\?" com uma barra invertida antes do ponto de interrogação.
Padrões predefinidos
Padrões predefinidos fornecem uma maneira simples para corresponder a um conjunto de caracteres ou uma sequência de vários caracteres. Use o operador de concatenação de cadeia de caracteres& para combinar suas próprias cadeias de texto com membros da enumeração Match:
| Enumeração Match | Descrição | Expressão regular |
|---|---|---|
| Any | Corresponde a qualquer caractere. | . |
| Comma | Corresponde a uma vírgula. | , |
| Digit | Corresponde a um único dígito ("0" a "9"). | \d |
| Corresponde a um endereço de email que contém um símbolo de "arroba" ("@") e um nome de domínio que contém um ponto (".") | .+\@.+\\.[^\\.]{2,} |
|
| Hyphen | Corresponde a um hífen. | \- |
| LeftParen | Corresponde a um parêntese esquerdo “(“. | \( |
| Letter | Corresponde a uma letra. | \p{L} |
| MultipleDigits | Corresponde a um ou mais dígitos. | \d+ |
| MultipleLetters | Corresponde a uma ou mais letras. | \p{L}+ |
| MultipleNonSpaces | Corresponde a um ou mais caracteres que não adicionam espaço em branco (não a espaço, tabulação ou nova linha). | \S+ |
| MultipleSpaces | Corresponde a um ou mais caracteres que adicionam espaço em branco (espaço, tabulação ou nova linha). | \s+ |
| NonSpace | Corresponde a um único caractere que não adiciona espaço em branco. | \S |
| OptionalDigits | Corresponde a zero, um ou mais dígitos. | \d* |
| OptionalLetters | Corresponde a zero, uma ou mais letras. | \p{L}* |
| OptionalNonSpaces | Corresponde a zero, um ou mais caracteres que não adicionam espaço em branco. | \S* |
| OptionalSpaces | Corresponde a zero, um ou mais caracteres que adicionam espaço em branco. | \s* |
| Period | Corresponde a um ponto ("."). | \. |
| RightParen | Corresponde a um parêntese direito “)”. | \) |
| Space | Corresponde a um caractere que adiciona o espaço em branco. | \s |
| Tabulação | Corresponde a um caractere de tabulação. | \t |
Por exemplo, o padrão "A" & MultipleDigits corresponderá à letra "A" seguida por um ou mais dígitos.
Expressões regulares
O padrão usado por essas funções é uma expressão regular. Os caracteres comuns e padrões predefinidos descritos anteriormente neste tópico ajudam a criar expressões regulares.
Expressões regulares são muito poderosas, disponíveis em muitas linguagens de programação e usadas em uma ampla variedade de finalidades. Geralmente, eles também podem parecer uma sequência aleatória de sinais de pontuação. Este artigo não descreve todos os aspectos de expressões regulares, mas uma infinidade de informações, tutoriais e ferramentas estão disponíveis na Web.
As expressões regulares vêm em dialetos diferentes, e os Power Apps usam uma variante do dialeto do JavaScript. Consulte a sintaxe de expressão regular para obter uma introdução à sintaxe. Há suporte para subcorrespondências nomeadas (às vezes chamadas de grupos de captura nomeados):
- Sub-correspondências nomeadas: (?<nome> ...)
- Referências anteriores nomeadas: \k<nome>
Na tabela de enumeração Match anteriormente neste tópico, cada enumeração aparece na mesma linha que a sua expressão regular correspondente.
Opções de correspondência
Você pode modificar o comportamento dessas funções especificando uma ou mais opções, que podem ser combinadas usando o operador de concatenação de cadeia de caracteres (&).
| Enumeração MatchOptions | Description | Impacto em uma expressão regular |
|---|---|---|
| MatchOptions.BeginsWith | O padrão deve corresponder desde o início do texto. | Adiciona um ^ ao início da expressão regular. |
| MatchOptions.Complete | Padrão para IsMatch. O padrão deve aparecer em algum lugar no texto, mas não precisa começar ou terminar com ele. | Adiciona um ^ ao início e um $ ao final da expressão regular. |
| MatchOptions.Contains | Padrão para Match e MatchAll. O padrão deve aparecer em algum lugar no texto, mas não precisa começar ou terminar com ele. | Não modifica a expressão regular. |
| MatchOptions.EndsWith | O padrão deve corresponder ao fim da cadeia de texto. | Adiciona um $ ao final da expressão regular. |
| MatchOptions.IgnoreCase | Trata letras maiúsculas e minúsculas como idênticas. Por padrão, a correspondência diferencia maiúsculas de minúsculas. | Não modifica a expressão regular. Essa opção é equivalente ao modificador "i" padrão para expressões regulares. |
| MatchOptions.Multiline | Corresponde em várias linhas. | Não modifica a expressão regular. Essa opção é equivalente ao modificador "m" padrão para expressões regulares. |
O uso de MatchAll é equivalente ao uso do modificador "g" padrão para expressões regulares.
Sintaxe
IsMatch( Text, Pattern [, Options ] )
- Text - obrigatório. A cadeia de texto a ser testada.
- Pattern - obrigatório. O padrão a ser testado como uma cadeia de texto. Concatenar padrões predefinidos que a enumeração Match define ou fornece uma expressão regular. O Pattern deve ser uma fórmula constante sem variáveis, fontes de dados ou outras referências dinâmicas que são alteradas conforme o aplicativo é executado.
- Options - opcional. Uma combinação de cadeia de texto de valores de enumeração MatchOptions. Por padrão, MatchOptions.Complete é usado.
Match( Text, Pattern [, Options ] )
- Text - obrigatório. A cadeia de texto a ser correspondida.
- Pattern - obrigatório. O padrão a ser correspondido como uma cadeia de texto. Concatenar padrões predefinidos que a enumeração Match define ou fornece uma expressão regular. O Pattern deve ser uma fórmula constante sem variáveis, fontes de dados ou outras referências dinâmicas que são alteradas conforme o aplicativo é executado.
- Options - opcional. Uma combinação de cadeia de texto de valores de enumeração MatchOptions. Por padrão, MatchOptions.Contains é usado.
MatchAll( Text, Pattern [, Options ] )
- Text - obrigatório. A cadeia de texto a ser correspondida.
- Pattern - obrigatório. O padrão a ser correspondido como uma cadeia de texto. Concatenar padrões predefinidos que a enumeração Match define ou fornece uma expressão regular. O Pattern deve ser uma fórmula constante sem variáveis, fontes de dados ou outras referências dinâmicas que são alteradas conforme o aplicativo é executado.
- Options - opcional. Uma combinação de cadeia de texto de valores de enumeração MatchOptions. Por padrão, MatchOptions.Contains é usado.
Exemplos de IsMatch
Caracteres comuns
Imagine que seu aplicativo contém um controle Text input chamado TextInput1. O usuário insere valores neste controle para ser armazenado em um banco de dados.
O usuário digita Hello world em TextInput1.
| Fórmula | Descrição | Resultado |
|---|---|---|
IsMatch( TextInput1.Text, "Hello world" ) |
Testa se a entrada do usuário corresponde, exatamente, à cadeia de caracteres "Hello world". | true |
IsMatch( TextInput1.Text, "Good bye" ) |
Testa se a entrada do usuário corresponde, exatamente, à cadeia de caracteres "Good bye". | false |
IsMatch( TextInput1.Text, "hello", Contains ) |
Testa se a entrada do usuário contém a palavra "hello" (com distinção entre maiúsculas e minúsculas). | false |
IsMatch( TextInput1.Text, "hello", Contains & IgnoreCase ) |
Testa se a entrada do usuário contém a palavra "hello" (sem distinção entre maiúsculas e minúsculas). | true |
Padrões predefinidos
| Fórmula | Descrição | Resultado |
|---|---|---|
IsMatch( "123-45-7890", Digit & Digit & Digit & Hyphen & Digit & Digit & Hyphen & Digit & Digit & Digit & Digit ) |
Corresponde a um número do Seguro Social dos Estados Unidos | true |
IsMatch( "joan@contoso.com", Email ) |
Corresponde a um endereço de email | true |
IsMatch( "123.456", MultipleDigits & Period & OptionalDigits ) |
Corresponde a uma sequência de dígitos, um ponto e, em seguida, zero ou mais dígitos. | true |
IsMatch( "123", MultipleDigits & Period & OptionalDigits ) |
Corresponde a uma sequência de dígitos, um ponto e, em seguida, zero ou mais dígitos. Um ponto não aparece no texto para corresponder, portanto, esse padrão não é correspondido. | false |
Expressões regulares
| Fórmula | Descrição | Resultado |
|---|---|---|
IsMatch( "986", "\d+" ) |
Corresponde a um número inteiro maior que zero. | true |
IsMatch( "1.02", "\d+(\.\d\d)?" ) |
Corresponde a um valor de moeda positivo. Se a entrada contiver um ponto decimal, a entrada também deverá conter dois caracteres numéricos após o ponto decimal. Por exemplo, 3,00 é válido, mas 3,1 não é. | true |
IsMatch( "-4.95", "(-)?\d+(\.\d\d)?" ) |
Corresponde a um valor de moeda positivo ou negativo. Se a entrada contiver um ponto decimal, a entrada também deverá conter dois caracteres numéricos após o ponto decimal. | true |
IsMatch( "111-11-1111", "\d{3}-\d{2}-\d{4}" ) |
Corresponde a um número do Seguro Social dos Estados Unidos. Valida o formato, o tipo e o comprimento do campo de entrada fornecido. A cadeia de caracteres a ser correspondida deve conter três caracteres numéricos seguidos por um traço e, em seguida, dois caracteres numéricos seguidos por um traço e, em seguida, quatro caracteres numéricos. | true |
IsMatch( "111-111-111", "\d{3}-\d{2}-\d{4}" ) |
Mesmo que no exemplo anterior, mas um hífen está fora do lugar na entrada. | false |
IsMatch( "AStrongPasswordNot", "(?!^[0-9]\*$)(?!^[a-zA-Z]\*$)([a-zA-Z0-9]{8,10})" ) |
Valida uma senha forte, que deve conter oito, nove ou 10 caracteres, além de pelo menos um dígito e pelo menos um caractere alfabético. A cadeia de caracteres não deve conter caracteres especiais. | false |
Exemplos de Match e MatchAll
| Fórmula | Descrição | Resultado |
|---|---|---|
Match( "Bob Jones <bob.jones@contoso.com>", "<(?<email>" & Match.Email & ")>" |
Extrai apenas a parte de email das informações de contato. | { email: "bob.jones@contoso.com", FullMatch: "<bob.jones@contoso.com>", SubMatches: [ "bob.jones@contoso.com" ], StartMatch: 11 } |
Match( "Bob Jones <InvalidEmailAddress>", "<(?<email>" & Match.Email & ")>" |
Extrai apenas a parte de email das informações de contato. Nenhum endereço legal foi encontrado (não há nenhum sinal de @), portanto, a função retorna blank. | blank |
Match( Language(), "(<language>\w{2})(?:-(?<script>\w{4}))?(?:-(?<region>\w{2}))?" ) |
Extrai as partes de idioma, script e região da marca de idioma que a função Language retorna. Esses resultados refletem o Estados Unidos; consulte a documentação da função Language para obter mais exemplos. O operador (?: agrupa caracteres sem criar outra subcorrespondência. | { language: "en", script: blank, region: "US", FullMatch: "en-US", SubMatches: [ "en", "", "US" ], StartMatch: 1 } |
Match( "PT2H1M39S", "PT(?:<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?" ) |
Extrai as horas, os minutos e os segundos de um valor de duração ISO 8601. Os números extraídos ainda estão em uma cadeia de texto; Use a função Value para convertê-la em um número antes que as operações matemáticas sejam executadas nela. | { hours: "2", minutes: "1", seconds: "39", FullMatch: "PT2H1M39S", Subcorrespondências:["2","1","39"], StartMatch: 1 } |
Vamos analisar o último exemplo. Se você quisesse converter essa cadeia de caracteres em um valor de data/hora usando a função Time, deverá passar as subcorrespondências nomeadas individualmente. Para fazer isso, você pode usar a função With operando no registro que o Match retorna:
With(
Match( "PT2H1M39S", "PT(?:(?<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?" ),
Time( Value( hours ), Value( minutes ), Value( seconds ) )
)
Para esses exemplos, adicione um controle Button, defina sua propriedade OnSelect como esta fórmula e, em seguida, selecione o botão:
Set( pangram, "The quick brown fox jumps over the lazy dog." )
| Fórmula | Descrição | Resultado |
|---|---|---|
Match( pangram, "THE", IgnoreCase ) |
Localiza todas as correspondências de "THE" na cadeia de texto que a variável pangram contém. A cadeia de caracteres contém duas correspondências, mas somente a primeira é retornada porque você está usando Match e não MatchAll. A coluna de subcorrespondências está vazia porque nenhuma subcorrespondência foi definida. | { FullMatch: "o", SubMatches: [ ], StartMatch: 32 } |
MatchAll( pangram, "the" ) |
Localiza todas as correspondências de "the" na cadeia de texto que a variável pangram contém. O teste diferencia maiúsculas de minúsculas, portanto, somente a segunda instância de "the" é encontrada. A coluna de subcorrespondências está vazia porque nenhuma subcorrespondência foi definida. |  |
MatchAll( pangram, "the", IgnoreCase ) |
Localiza todas as correspondências de "the" na cadeia de texto que a variável pangram contém. Nesse caso, o teste não diferencia maiúsculas de minúsculas, portanto, ambas as instâncias da palavra são encontradas. A coluna de subcorrespondências está vazia porque nenhuma subcorrespondência foi definida. |  |
MatchAll( pangram, "\b\wo\w\b" ) |
Localiza todas as palavras de três letras com um "o" no meio. Observe que "brown" é excluído porque não é uma palavra de três letras e, portanto, não corresponde a "\b" (limite de palavras). |  |
Match( pangram, "\b\wo\w\b\s\*(?<between>\w.+\w)\s\*\b\wo\w\b" ) |
Corresponde a todos os caracteres entre "raposa" e "cão". | { between: "jumps over the lazy", FullMatch: "fox jumps over the lazy dog", SubMatches: [ "jumps over the lazy" ], StartMatch: 17 } |
Para ver os resultados de MatchAll em uma galeria:
Em uma tela vazia, insira um controle Gallery vertical em branco.
Defina a propriedade Items da galeria como MatchAll( pangram, "\w+" ) ou MatchAll( pangram, MultipleLetters ).
Selecione "Adicionar um item da guia Inserir" no meio do controle da galeria para selecionar o modelo da galeria.
Adicione um controle Label ao modelo da galeria.
Defina a propriedade Text do rótulo como ThisItem.FullMatch.
A galeria é preenchida com cada palavra em nosso texto de exemplo. Redimensione o modelo da galeria e o controle de rótulo para ver todas as palavras em uma tela.
