As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Função SUBSTRING
Retorna o subconjunto de uma string com base na posição inicial especificada da string.
Se a entrada for uma cadeia de caracteres, a posição inicial e o número de caracteres extraídos são baseados nos caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples. Se a entrada for uma expressão binária, a posição inicial e a substring extraída são baseadas em bytes. Você não pode especificar um comprimento negativo, mas pode especificar uma posição inicial negativa.
## Sintaxe
```
SUBSTRING(charactestring FROM start_position [ FOR numbecharacters ] )
```
```
SUBSTRING(charactestring, start_position, numbecharacters )
```
```
SUBSTRING(binary_expression, start_byte, numbebytes )
```
```
SUBSTRING(binary_expression, start_byte )
```
## Argumentos
*cadeia de caracteres*
A string a ser pesquisada. Tipos de dados não caracteres são tratados como uma string.
*start\$1position*
A posição dentro da sequência para começar a extração, começando em 1. A *start\$1position* é baseada no número de caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples. Esse número pode ser negativo.
*caracteres numéricos*
O número de caracteres a extrair (o comprimento da substring). Os *caracteres numéricos* são baseados no número de caracteres, não em bytes, de modo que os caracteres de vários bytes sejam contados como caracteres únicos. Esse número não pode ser negativo.
*start\$1byte*
A posição dentro da expressão binária para começar a extração, começando por 1. Esse número pode ser negativo.
*número de bytes*
O número de bytes a serem extraídos, ou seja, o comprimento da substring. Esse número não pode ser negativo.
## Tipo de retorno
VARCHAR
## Notas de uso para cadeias de caracteres
O seguinte exemplo retorna uma string de quatro caracteres começando com o sexto caractere.
```
select substring('caterpillar',6,4);
substring
-----------
pill
(1 row)
```
*Se os caracteres *start\$1position* \$1 *numbecharacters* excederem o comprimento da *string, SUBSTRING retornará uma substring* começando da start\$1position até o final da string.* Por exemplo:
```
select substring('caterpillar',6,8);
substring
-----------
pillar
(1 row)
```
Se `start_position` for negativa ou 0, a função SUBSTRING retornará uma substring começando no primeiro caractere da string com um comprimento de `start_position` \$1 `numbecharacters` -1. Por exemplo:
```
select substring('caterpillar',-2,6);
substring
-----------
cat
(1 row)
```
Se `start_position` \$1 `numbecharacters` -1 for menor ou igual a zero, a SUBSTRING retornará uma string vazia. Por exemplo:
```
select substring('caterpillar',-5,4);
substring
-----------
(1 row)
```
## Exemplos
O seguinte exemplo retorna o mês da string LISTTIME na tabela LISTING:
```
select listid, listtime,
substring(listtime, 6, 2) as month
from listing
order by 1, 2, 3
limit 10;
listid | listtime | month
--------+---------------------+-------
1 | 2008-01-24 06:43:29 | 01
2 | 2008-03-05 12:25:29 | 03
3 | 2008-11-01 07:35:33 | 11
4 | 2008-05-24 01:18:37 | 05
5 | 2008-05-17 02:29:11 | 05
6 | 2008-08-15 02:08:13 | 08
7 | 2008-11-15 09:38:15 | 11
8 | 2008-11-09 05:07:30 | 11
9 | 2008-09-09 08:03:36 | 09
10 | 2008-06-17 09:44:54 | 06
(10 rows)
```
O seguinte exemplo é o mesmo que o exemplo acima, mas usa a opção FROM...FOR:
```
select listid, listtime,
substring(listtime from 6 for 2) as month
from listing
order by 1, 2, 3
limit 10;
listid | listtime | month
--------+---------------------+-------
1 | 2008-01-24 06:43:29 | 01
2 | 2008-03-05 12:25:29 | 03
3 | 2008-11-01 07:35:33 | 11
4 | 2008-05-24 01:18:37 | 05
5 | 2008-05-17 02:29:11 | 05
6 | 2008-08-15 02:08:13 | 08
7 | 2008-11-15 09:38:15 | 11
8 | 2008-11-09 05:07:30 | 11
9 | 2008-09-09 08:03:36 | 09
10 | 2008-06-17 09:44:54 | 06
(10 rows)
```
Não é possível usar a SUBSTRING para extrair previsivelmente o prefixo de uma string que possa conter caracteres multibyte, pois é necessário especificar o comprimento de uma string multibyte com base no número de bytes, e não no número de caracteres. Para extrair o segmento inicial de uma sequência com base no comprimento em bytes, você pode CAST a string como VARCHAR (*byte\$1length*) para truncar a string, onde *byte\$1length* é o tamanho exigido. O seguinte exemplo extrai os primeiros cinco bytes da string `'Fourscore and seven'`.
```
select cast('Fourscore and seven' as varchar(5));
varchar
-------
Fours
```
O exemplo a seguir retorna o nome `Ana` que aparece após o último espaço na string de entrada `Silva, Ana`.
```
select reverse(substring(reverse('Silva, Ana'), 1, position(' ' IN reverse('Silva, Ana'))))
reverse
-----------
Ana
```