.. _replace:

=======
replace
======= 

Replaces parts of a string that match a regular expression

Description
~~~~~~~~~~~
The fn:replace function replaces parts of a string that match a regular 
expression. The regular expression syntax used is defined by XML Schema with a 
few modifications/additions in XQueryXPath/XSLT. The $pattern argument is a 
regular expression. While it is nice to have the power of regular expressions, 
if you simply want to replace a particular sequence of characters you don't have 
to be familiar with regular expressions to do that; you can just specify the 
string you want replaced for $pattern, as long as it doesn't contain any special 
characters.

The $replacement argument specifies a string (not a pattern) that is to be used 
as a replacement.

The $flags argument allows for additional options in the interpretation of the 
regular expression, such as multi-line processing and case insensitivity.

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

   * - **Parameters**
     - **Description**
   * - input:string()
     - the string to change
   * - pattern:string()
     - regular expression to match the areas to be replaced
   * - replacement:string()
     - the replacement  string
   * - flags:string()
     - flags that control multiline mode, case insensitivity, etc.

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

   * - **XPath**
     - **Results**
   * - replace('query', 'r', 'as')
     - queasy
   * - replace('query', 'qu', 'quack')
     - quackery
   * - replace('query', '[ry]', 'l')
     - quell
   * - replace('query', '[ry]+', 'l')
     - quel
   * - replace('query', 'z', 'a')
     - query
   * - replace('query', 'query', '')
     - zero-length string
   * - replace( (), 'r', 'as')
     - zero-length string
   * - replace('query', 'r?', 'as')
     - Error FORX0003
   * - replace('query', '(r', 'as')
     - Error FORX0002
   * - replace('Chapter', '(Chap)|(Chapter)', 'x')
     - xter
   * - 
     - 
   * - 
     - 

See Also
~~~~~~~~

.. toctree::
   :titlesonly:
   :glob:

* :ref:`functx_replace-multi`.
* :ref:`functx_replace-first`.
* :ref:`functx_replace-beginning`.
* :ref:`functx_escape-for-regex`.