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

Este artigo fornece observações complementares à documentação de referência para essa 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 para o qual o Match(String, Int32) método pesquisa é definido pela chamada para um dos construtores de Regex classe. 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 startat parâmetro

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 em uma pesquisa da esquerda para a direita e a extremidade direita de inputinput 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 , ele não ignora a cadeia de caracteres antes startatstartat. Isso significa que asserções como âncoras ou asserções lookbehind ainda se aplicam à entrada como um todo. Por exemplo, o código a seguir inclui um padrão com uma asserção lookbehind que é satisfeita mesmo que ocorra antes do startat índice de 5 na cadeia de caracteres 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: {0}", match.Value);
        }
    }
}

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

Dica

• Se um padrão começar com a âncora ^ , mas startat for maior que 0, nenhuma correspondência será encontrada em uma pesquisa de linha única, pois elas são restringidas a ^ começar no índice 0.
• O \G âncora está satisfeito em startat. Por isso, se você quiser restringir uma correspondência para que ela comece exatamente em uma posição de caractere específica na cadeia de caracteres, ancore a expressão regular com um à esquerda para um \G padrão da esquerda para a direita. Isso restringe a partida, então ela deve começar exatamente em startat (ou, quando várias correspondências são desejadas, para que as partidas sejam contíguas).

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 RegexOptions.RightToLeft opção, se comporta das seguintes maneiras:

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

Para obter mais informações sobre pesquisas da direita para a esquerda, consulte 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 do Success objeto retornadoMatch. Se uma correspondência for encontrada, a propriedade do Value objeto retornado Match conterá a subcadeia de caracteres que corresponde ao padrão de input expressão regular. Se nenhuma correspondência for encontrada, seu valor será String.Empty.

Primeira ou várias correspondências

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

Exceções de tempo limite

A RegexMatchTimeoutException exceção será lançada se o tempo de execução da operação correspondente 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á lançada 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 construtor ou nas propriedades do domínio do Regex aplicativo, ou se o valor de tempo limite for Regex.InfiniteMatchTimeout, nenhuma exceção será lançada.