SUBSTR , SUBSTRING¶

Sintaxe¶

SUBSTR( <base_expr>, <start_expr> [ , <length_expr> ] )

SUBSTRING( <base_expr>, <start_expr> [ , <length_expr> ] )

Argumentos¶

base_expr

Este deve ser um valor VARCHAR ou BINARY.

start_expr

A posição inicial deve ser uma expressão que avalia como um número inteiro. Especifica o offset a partir do qual a subcadeia de caracteres começa. O offset é medido em:

• O número de caracteres UTF-8 se a entrada for VARCHAR.

• O número de bytes se a entrada for BINARY.

A posição inicial é baseada em 1, não em 0. SUBSTR('abc', 1, 1) retorna “a”, não “b”.

length_expr

O comprimento deve ser uma expressão que avalia como um número inteiro. Deve especificar:

• O número de caracteres UTF-8 a retornar se a entrada for VARCHAR.

• O número de bytes a retornar se a entrada for BINARY.

O comprimento deve ser maior ou igual a zero. Se o comprimento for um número negativo, a função retorna uma cadeia de caracteres vazia.

Retornos¶

O tipo de dados do valor retornado é o mesmo que o tipo de dados do base_expr (BINARY ou VARCHAR).

Notas de uso¶

• Se for utilizado length_expr, até length_expr caracteres/bytes são devolvidos, caso contrário todos os caracteres até o final da cadeia de caracteres ou valor binário são devolvidos.

• Os valores em start_expr começam a partir de 1:

  • Se 0 for especificado, ele será tratado como 1.

  • Se um valor negativo for especificado, a posição inicial é calculada como os start_expr caracteres/bytes a partir do final da cadeia de caracteres ou valor binário. Se a posição estiver fora do intervalo de uma cadeia de caracteres ou valor binário, um valor vazio é devolvido.

• Se qualquer uma das entradas for NULL, NULL será retornado.

Detalhes do agrupamento¶

• O agrupamento se aplica às entradas VARCHAR. O agrupamento não se aplica se o tipo de dados de entrada do primeiro parâmetro for BINARY.

• No impact. Embora o agrupamento seja aceito sintaticamente, os agrupamentos não têm impacto no processamento. Por exemplo, idiomas com letras de dois e três caracteres (por exemplo, «dzs» em húngaro, «ch» em tcheco) ainda contam esses como dois ou três caracteres (não um caractere) para o argumento da extensão.

• The collation of the result is the same as the collation of the input. Isso pode ser útil se o valor retornado for passado para outra função como parte de chamadas de funções aninhadas.

Exemplos¶

SELECT SUBSTR('testing 1 2 3', 9, 5) FROM x;

-------------------------------+
 substr('testing 1 2 3', 9, 5) |
-------------------------------+
 1 2 3                         |
-------------------------------+

SELECT '123456', pos, len, SUBSTR('123456', pos, len) FROM o;

----------+--------+-----+----------------------------+
 '123456' |  pos   | len | substr('123456', pos, len) |
----------+--------+-----+----------------------------+
 123456   | -1     | 3   | 6                          |
 123456   | -3     | 3   | 456                        |
 123456   | -3     | 7   | 456                        |
 123456   | -5     | 3   | 234                        |
 123456   | -7     | 3   |                            |
 123456   | 0      | 3   | 123                        |
 123456   | 0      | 7   | 123456                     |
 123456   | 1      | 3   | 123                        |
 123456   | 3      | 3   | 345                        |
 123456   | 3      | 7   | 3456                       |
 123456   | 5      | 3   | 56                         |
 123456   | 5      | 7   | 56                         |
 123456   | 7      | 3   |                            |
 123456   | [NULL] | 3   | [NULL]                     |
 123456   | [NULL] | 7   | [NULL]                     |
----------+--------+-----+----------------------------+