.. _replace:

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

Substitui as partes de uma string que casam com uma expressão regular

Descrição
~~~~~~~~~
A função fn:replace substitui as partes de uma string que casam 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. O argumento $pattern é uma 
expressão regular. É bom ter esse poder, mas, se você só quer trocar uma 
sequência de caracteres, não precisa conhecer expressões regulares: basta pôr em 
$pattern a string a trocar, desde que ela não tenha caracteres especiais.

O argumento $replacement é uma string (não um padrão) usada na substituição.

O argumento $flags dá opções a mais na interpretação da expressão regular, como 
o modo multilinha e ignorar maiúsculas e minúsculas.

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

   * - **Parâmetros**
     - **Descrição**
   * - input:string()
     - a string a alterar
   * - pattern:string()
     - a expressão regular que casa com as partes a substituir
   * - replacement:string()
     - a string de substituição
   * - flags:string()
     - flags que controlam o modo multilinha, a diferença entre maiúsculas e minúsculas etc.

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

   * - **XPath**
     - **Resultado**
   * - 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

Os exemplos a seguir mostram a diferença entre quantificadores relutantes e normais:

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

   * - **XPath**
     - **Resultado**
   * - replace('reluctant', 'r.\*t', 'X')
     - X
   * - replace('reluctant', 'r.\*?t', 'X')
     - Xant
   * - replace('aaah', 'a{2,3}', 'X')
     - Xh
   * - replace('aaah', 'a{2,3}?', 'X')
     - Xah
   * - replace('aaaah', 'a{2,3}', 'X')
     - Xah
   * - replace('aaaah', 'a{2,3}?', 'X')
     - XXh

Os exemplos a seguir mostram o uso de subexpressões:

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

   * - **XPath**
     - **Resultado**
   * - replace('Chap 2...Chap 3...Chap 4...', 'Chap (\\d)', 'Sec $1.0')
     - Sec 2.0...Sec 3.0...Sec 4.0...
   * - replace('abc123', '([a-z])', '$1x')
     - axbxcx123
   * - replace('2315551212', '(\\d{3})(\\d{3})(\\d{4})', '($1) $2-$3')
     - (231) 555-1212
   * - replace('2006-10-18', '\\d{2}(\\d{2})-(\\d{2})-(\\d{2})', '$2/$3/$1')
     - 10/18/06
   * - replace('25', '(\\d+)', '\\$$1.00')
     - $25.00

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

.. toctree::
   :titlesonly:
   :glob:

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