.. _matches:

=======
matches
======= 

Se uma string casa com uma expressão regular

Descrição
~~~~~~~~~
A função fn:matches diz se uma string casa com uma expressão regular. A sintaxe 
das expressões regulares é a do XML Schema, com algumas mudanças e acréscimos do 
XPath/XSLT 2.0. O argumento $pattern é a expressão regular. Ao contrário de 
muitas funções de string, fn:matches não usa collations: a comparação é feita só 
pelos code points Unicode. A menos que se usem as âncoras "^" ou "$", a função 
devolve true se qualquer trecho de $input casar com a expressão.

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - **Parâmetros**
     - **Descrição**
   * - input:string()
     - a string a testar
   * - pattern:string()
     - a expressão regular a procurar
   * - flags:string()
     - flags que controlam o modo multilinha, a diferença entre maiúsculas e minúsculas etc.

Exemplos
~~~~~~~~
Os exemplos abaixo usam este documento de entrada:

.. code-block:: xml

   <xsl:variable name="address" as="xs:string">123 Main Street
   Traverse City, MI 49684</xsl:variable>

.. list-table::
   :widths: 25 25 50
   :header-rows: 1

   * - **XPath**
     - **Resultado**
     - **Explicação**
   * - matches('query', 'q')
     - true
     - q aparece na string.
   * - matches('query', 'ue')
     - true
     - ue aparece na string.
   * - matches('query', '^qu')
     - true
     - ^ prende o padrão no início.
   * - matches('query', 'qu$')
     - false
     - $ prende o padrão no fim, e a string termina com ry.
   * - matches('query', '[ux]')
     - true
     - A string contém u.
   * - matches('query', 'q.\*')
     - true
     - q seguido de quaisquer caracteres.
   * - matches('query', '[a-z]{5}')
     - true
     - Cinco letras minúsculas seguidas.
   * - matches((), 'q' )
     - false
     - A sequência vazia é tratada como uma string vazia, que não contém q.
   * - matches('query', '[qu')
     - Error FORX0002
     - [qu não é uma expressão regular válida: o colchete não foi fechado.
   * - matches($address, 'Street.\*City')
     - false
     - Sem o flag s, o . não casa com a quebra de linha.
   * - matches($address, 'Street.\*City', 's')
     - true
     - Com o flag s (dot-all), o . também casa com a quebra de linha.
   * - matches($address, 'Street$')
     - false
     - Sem o flag m, o $ só casa no fim da string inteira.
   * - matches($address, 'Street$', 'm')
     - true
     - Com o flag m (multilinha), o $ também casa no fim de cada linha.
   * - matches($address, 'street')
     - false
     - A comparação diferencia maiúsculas de minúsculas.
   * - matches($address, 'street', 'i')
     - true
     - O flag i ignora maiúsculas e minúsculas.
   * - matches($address, 'Main Street')
     - true
     - O texto contém Main Street.
   * - matches($address, 'Main Street', 'x')
     - false
     - Com o flag x, os espaços do padrão são ignorados, então ele procura MainStreet.
   * - matches($address, 'Main \\s Street', 'x')
     - true
     - Com o flag x, é preciso \\s para casar com o espaço.
   * - matches($address, 'street$', 'im')
     - true
     - O i ignora maiúsculas e minúsculas, e o m deixa o $ casar no fim da primeira linha.
   * - matches($address, 'Street$', 'q')
     - false
     - Desde o XPath 3.0 o flag q é válido: o padrão é lido como texto literal, então $ não é o fim da linha. No XPath 2.0 dava o erro FORX0001.

Veja também
~~~~~~~~~~~

.. toctree::
   :titlesonly:
   :glob:

* :ref:`contains`.
* :ref:`functx_number-of-matches`.