.. _substring:

=========
substring
========= 

Um trecho a partir de uma posição inicial e de um tamanho opcional

Descrição
~~~~~~~~~
A função fn:substring usa o argumento $startingLoc como posição inicial do 
trecho; o primeiro caractere fica na posição 1 (não em 0). O argumento opcional 
$length diz quantos caracteres incluir a partir da posição inicial. Se $length 
não for informado, vai até o fim da string.

A função devolve todos os caracteres cuja posição é maior ou igual a 
$startingLoc e menor que ($startingLoc + $length). $startingLoc pode ser zero ou 
negativo: nesse caso, a função começa no início da string, mas continua 
incluindo só os caracteres até a posição ($startingLoc + $length), sem 
incluí-la. Se ($startingLoc + $length) for maior que o tamanho da string, vai 
até o fim.

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

   * - **Parâmetros**
     - **Descrição**
   * - sourceString:string()
     - a string inteira
   * - startingLoc:double()
     - o caractere inicial (começando em 1)
   * - length:double()
     - o número de caracteres a incluir

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

   * - **XPath**
     - **Resultado**
   * - substring('query', 1)
     - query
   * - substring('query', 3)
     - ery
   * - substring('query', 1, 1)
     - q
   * - substring('query', 2, 3)
     - uer
   * - substring('query', 2, 850)
     - uery
   * - substring('query', 6, 2)
     - zero-length string
   * - substring('query', -2)
     - query
   * - substring('query', -2, 5)
     - qu
   * - substring('query', 1, 0)
     - zero-length string
   * - substring('', 1)
     - zero-length string
   * - substring((), 1)
     - zero-length string

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

.. toctree::
   :titlesonly:
   :glob:

* :ref:`substring-before`.
* :ref:`substring-after`.
* :ref:`functx_substring-before-last`.
* :ref:`functx_substring-after-last`.
* :ref:`functx_substring-after-last-match`.
* :ref:`functx_substring-before-if-contains`.
* :ref:`functx_substring-after-if-contains`.