Método System.Text.RegularExpressions.Regex.Match

Este artigo fornece comentários complementares à documentação de referência para esta API.

O Match(String, Int32) método retorna a primeira subcadeia de caracteres que corresponde a um padrão de expressão regular, começando em ou após a posição do startat caractere, em uma cadeia de caracteres de entrada. O padrão de expressão regular pelo qual o método Match(String, Int32) pesquisa é definido pela chamada para um dos construtores da classe Regex. Para obter informações sobre os elementos de linguagem usados para criar um padrão de expressão regular, consulte Linguagem de Expressão Regular – Referência Rápida.

O parâmetro startat

Opcionalmente, você pode especificar uma posição inicial na cadeia de caracteres usando o startat parâmetro. Todas as correspondências que começam antes startat na cadeia de caracteres são ignoradas. Se você não especificar uma posição inicial, a pesquisa começará na posição padrão, que é a extremidade esquerda de input em uma pesquisa da esquerda para a direita, e a extremidade direita de input em uma pesquisa da direita para a esquerda. Apesar de começar em startat, o índice de qualquer correspondência retornada é relativo ao início da cadeia de caracteres.

Embora o mecanismo de expressão regular não retorne nenhuma correspondência começando antes startat, ele não ignora a cadeia de caracteres antes startat. Isso significa que afirmações como âncoras ou asserções de retrocesso ainda se aplicam à entrada como um todo. Por exemplo, o código a seguir inclui um padrão com uma asserção de lookbehind que é satisfeita, mesmo ocorrendo antes do índice startat do valor 5 na string de entrada.

using System;
using System.Text.RegularExpressions;

namespace Examples
{
    public class Example3
    {
        public static void Main()
        {
            string input = "Zip code: 98052";
            var regex = new Regex(@"(?<=Zip code: )\d{5}");
            Match match = regex.Match(input, 5);
            if (match.Success)
                Console.WriteLine($"Match found: {match.Value}");
        }
    }
}

// This code prints the following output:
// Match found: 98052

Pesquisas da direita para a esquerda

Uma pesquisa da direita para a esquerda, ou seja, quando o padrão de expressão regular é construído com a opção RegexOptions.RightToLeft , comporta-se das seguintes maneiras:

• O escaneamento se move na direção oposta e o padrão é correspondido de trás (direita) para a frente (esquerda).
• A posição inicial padrão é a extremidade direita da cadeia de caracteres de entrada.
• Se startat for especificado, a verificação da direita para a esquerda começará no caractere em startat - 1 (não startat).
• A âncora de \G, quando especificada no final direito de um padrão, restringe a primeira correspondência para terminar exatamente em startat - 1.

Para obter mais informações sobre pesquisas da direita para a esquerda, consulte o modo da direita para a esquerda.

Determinar se uma correspondência foi encontrada

Você pode determinar se o padrão de expressão regular foi encontrado na cadeia de caracteres de entrada verificando o valor da propriedade Match do objeto Success retornado. Se uma correspondência for encontrada, a propriedade Match do objeto retornado Value contém a subcadeia de caracteres de input que corresponde ao padrão de expressão regular. Se nenhuma correspondência for encontrada, seu valor será String.Empty.

Primeiras ou múltiplas correspondências

Esse método retorna a primeira subcadeia de caracteres encontrada na posição de caractere startat ou depois em input, que corresponde ao padrão de expressão regular. Você pode recuperar correspondências subsequentes chamando repetidamente o método Match do objeto retornado Match.NextMatch. Você também pode recuperar todas as correspondências em uma única chamada ao método Regex.Matches(String, Int32).

Exceções de tempo limite

A RegexMatchTimeoutException exceção será gerada se o tempo de execução da operação de correspondência exceder o intervalo de tempo limite especificado pelo Regex.Regex(String, RegexOptions, TimeSpan) construtor. Se você não definir um intervalo de tempo limite ao chamar o construtor, a exceção será gerada se a operação exceder qualquer valor de tempo limite estabelecido para o domínio do aplicativo no qual o Regex objeto é criado. Se nenhum tempo limite for definido na chamada do Regex construtor ou nas propriedades do domínio do aplicativo ou se o valor de tempo limite for Regex.InfiniteMatchTimeout, nenhuma exceção será gerada.