.. _tokenize:

========
tokenize
======== 

Divide uma string por uma expressão regular

Descrição
~~~~~~~~~
A função fn:tokenize divide uma string usando 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 é uma expressão regular que representa o 
separador. Os padrões mais simples podem ser um espaço ou uma string com o 
caractere separador, como ,. Mas alguns caracteres precisam ser escapados em 
expressões regulares: .\?*+|^${}()[].

Os separadores não entram nas strings do resultado. Se houver dois separadores 
seguidos, entra uma string vazia no resultado. Se a string começar com o 
separador, o primeiro valor é uma string vazia. Do mesmo jeito, se terminar com 
o separador, o último valor é uma string vazia.

O parâmetro $flags dá opções a mais na interpretação da expressão regular.

Se um ponto da string puder casar com mais de uma alternativa, vale a primeira. 
É o que mostra o último exemplo abaixo, em que a função considera a vírgula como 
separador, embora "vírgula seguida de asterisco" também sirva.

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

   * - **Parâmetros**
     - **Descrição**
   * - input:string()
     - a string a dividir
   * - pattern:string()
     - a expressão regular que casa com os separadores
   * - 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**
   * - tokenize('a b c', '\\s')
     - ('a', 'b', 'c')
   * - tokenize('a   b c', '\\s')
     - ('a', '', '', 'b', 'c')
   * - tokenize('a   b c', '\\s+')
     - ('a', 'b', 'c')
   * - tokenize(' b c', '\\s')
     - ('', 'b', 'c')
   * - tokenize('a,b,c', ',')
     - ('a', 'b', 'c')
   * - tokenize('a,b,,c', ',')
     - ('a', 'b', '', 'c')
   * - tokenize('a, b, c', '[,\\s]+')
     - ('a', 'b', 'c')
   * - tokenize('2006-12-25T12:15:00', '[\\-T:]')
     - ('2006', '12', '25', '12', '15', '00')
   * - tokenize('Hello, there.', '\\W+')
     - ('Hello', 'there', '')
   * - tokenize((), '\\s+')
     - ()
   * - tokenize('abc', '\\s')
     - abc
   * - tokenize('abcd', 'b?')
     - Error FORX0003
   * - tokenize('a,xb,xc', ',\|,x')
     - ('a', 'xb', 'xc')

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

.. toctree::
   :titlesonly:
   :glob:

* :ref:`functx_chars`.