Histórico da Página

Sintaxe

SUBSTR( <expressão caracter>, <expressão numérica 1>  [ , <expressão numérica 2> ] )

Propósito

Extrai uma parte de uma cadeia de caracteres.

Argumentos

< expressão caracter >

Define a cadeia de caracteres do qual se extrairá uma parte.

< expressão numérica 1 >

Define a posição inicial da parte que será extraída da expressão caracter. Se for positiva será contada da esquerda para a direita. Ou seja, do início para o fim. Se for negativa será contada da direita para a esquerda. Ou seja, do fim para o início.

Essa informação é obrigatória.

< expressão numérica 2 >

Define o número de caracteres que serão extraídos da expressão caracter, contados a partir da posição inicial especificada pela expressão numérica 1. Se omitida, a extração partirá da posição inicial determinada e irá até o final da expressão caracter. Se for maior do que o número de caracteres existentes do início da parte que será extraída até o fim da expressão caracter, será ignorada.

Utilização

Utiliza-se essa função quando é necessário extrair um conjunto de caracteres  de uma determinada cadeia de caracteres.

Um exemplo típico de utilização dessa função é a manipulação de códigos compostos, como em geral são os números de contas contábeis, nos quais cada parte do código identifica um grupo ou um subgrupo de contas.

Dicas

As funções LEFT(), RIGHT() e SUBSTR() são relacionadas, fornecendo partes extraídas de uma cadeia de caracteres especificada. A função LEFT() fornece a parte da esquerda, RIGHT() fornece a parte da direita e SUBSTR() fornece uma parte intermediária. Estas funções costumam ser utilizadas com as funções AT() e RAT(), que podem localizar a posição das partes a serem extraídas.

Através dessas funções pode-se manipular qualquer cadeia de caracteres com no máximo 64 Kbytes de comprimento (65.535 caracteres).

A função RIGHT() é equivalente à função SUBSTR() se o argumento que determina a posição inicial da parte for igual à -1. Por exemplo: RIGHT(“Clipper”, 3) fornece a mesma parte que SUBSTR(“Clipper”, -1, 3).

A função LEFT() é equivalente à função SUBSTR() se o argumento que determina a posição inicial da parte for igual à 1. Por exemplo: LEFT(“Clipper”, 3) fornece a mesma parte que SUBSTR(“Clipper”, 1, 3).

Exemplos

Para extrair “11” do número da conta “2.22.11.21.00”, utilizamos a função da seguinte forma:

SUBSTR(“2.22.11.21.00”, 6, 2)

cTexto := “AdvPL – A linguagem de programação do Protheus”

SUBSTR(cTexto, 23, 11)     // Resulta “programação”

SUBSTR(cTexto, 38)           // Resulta “Protheus”

SUBSTR(cTexto, -1, 8)        // Resulta “Protheus”