.. _matches:

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

Whether a string matches a regular expression

Description
~~~~~~~~~~~
The fn:matches function determines whether a string matches a regular 
expression. The regular expression syntax used is defined by XML Schema with a 
few modifications/additions in XQueryXPath/XSLT 2.0. The $pattern argument is a 
regular expression. Unlike many of the string-related functions, the fn:matches 
function does not use collations at all. Regular expression matching is solely 
based on Unicode code points. Unless the anchors "^" or "$" are used, the 
function returns true if any substring of $input matches the regular expression.

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

   * - **Parameters**
     - **Description**
   * - input:string()
     - the string to test
   * - pattern:string()
     - the regular expression to test for
   * - flags:string()
     - flags that control multiline mode, case insensitivity, etc.

Examples
~~~~~~~~
.. list-table::
   :widths: 50 50
   :header-rows: 1

   * - **XPath**
     - **Results**
   * - matches('query', 'q')
     - true
   * - matches('query', 'ue')
     - true
   * - matches('query', '^qu')
     - true
   * - matches('query', 'qu$')
     - false
   * - matches('query', '[ux]')
     - true
   * - matches('query', 'q.*')
     - true
   * - matches('query', '[a-z]{5}')
     - true
   * - matches((), 'q' )
     - false
   * - matches('query', '[qu')
     - Error FORX0002
   * - matches($address, 'Street.*City')
     - false
   * - matches($address, 'Street.*City', 's')
     - true
   * - matches($address, 'Street$')
     - false
   * - matches($address, 'Street$', 'm')
     - true
   * - matches($address, 'street')
     - false
   * - matches($address, 'street', 'i')
     - true
   * - matches($address, 'Main Street')
     - true
   * - matches($address, 'Main Street', 'x')
     - false
   * - matches($address, 'Main \s Street', 'x')
     - true
   * - matches($address, 'street$', 'im')
     - true
   * - matches($address, 'Street$', 'q')
     - Error FORX0001

See Also
~~~~~~~~

.. toctree::
   :titlesonly:
   :glob:

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