Esta seção descreve as funções e operadores para examinar e tratar
cadeia binária, ou seja, valores do tipo de dados bytea.
Muitas delas são equivalentes, em propósito e sintaxe, às funções
de cadeia de caracteres de texto descritas na seção anterior.
O padrão SQL define algumas funções de cadeias binárias que usam palavras-chave, em vez de vírgulas, para separar os argumentos. Os detalhes estão na Tabela 9.11. O PostgreSQL também fornece versões destas funções que usam a sintaxe de chamada de função regular (veja a Tabela 9.12).
Tabela 9.11. Funções e operadores SQL de cadeia binária
Estão disponíveis as funções adicionais para tratamento de cadeias binárias descritas na Tabela 9.12. Algumas destas funções são usadas internamente para implementar as funções de cadeia binária do padrão SQL listadas na Tabela 9.11.
Tabela 9.12. Outras funções de cadeia binária
Função Descrição Exemplo(s) |
|---|
Retorna o número de bits definidos na cadeia binária (também conhecida como “popcount”).
|
|
Calcula o valor de CRC-32 da cadeia binária.
|
|
Calcula o valor de CRC-32 da cadeia binária.
|
Extrai o n-ésimo bit da cadeia binária.
|
Extrai o n-ésimo byte da cadeia binária.
|
|
Retorna o número de bytes na cadeia binária.
|
Retorna o número de caracteres na cadeia binária, assumindo que
se trata de um texto na codificação
|
|
Calcula o hash MD5 da cadeia binária, com o resultado escrito em hexadecimal.
|
|
Inverte a ordem dos bytes na cadeia binária.
|
Define o n-ésimo
bit na cadeia binária como
|
Define o n-ésimo
byte na cadeia binária como
|
|
Calcula o hash SHA-224 da cadeia binária.
|
|
Calcula o hash SHA-256 da cadeia binária.
|
|
Calcula o hash SHA-384 da cadeia binária.
|
|
Calcula o hash SHA-512 da cadeia binária.
|
Extrai a sub-cadeia de
|
As funções get_byte e set_byte
numeram o primeiro byte da cadeia binária como byte 0.
As funções get_bit e set_bit
numeram os bits a partir da direita dentro de cada byte; por exemplo,
o bit 0 é o bit menos significativo do primeiro byte,
e o bit 15 é o bit mais significativo do segundo byte.
Por razões históricas, a função md5 retorna um
valor codificado em hexadecimal do tipo de dados text,
enquanto as funções SHA-2 retornam o tipo de dados bytea.
Devem ser usadas as funções
encode
e decode
para converter entre as duas formas.
Por exemplo, deve ser escrito
encode(sha256('abc'), 'hex') para obter uma
representação textual codificada em hexadecimal, ou
decode(md5('abc'), 'hex') para obter o valor
bytea.
A Tabela 9.13 descreve
funções para converter uma cadeia entre diferentes conjuntos
de caracteres (codificações), e para representar dados binários
arbitrários em formato de texto.
Para estas funções, o argumento ou resultado do tipo de dados
text é expresso na codificação padrão do banco de dados,
enquanto argumentos ou resultados do tipo de dados bytea
estão em uma codificação com nome especificado por outro argumento.
Tabela 9.13. Funções de conversão de cadeia texto/binária
Função Descrição Exemplo(s) |
|---|
Converte uma cadeia binária que representa texto na codificação
|
Converte uma cadeia binária que representa texto na codificação
|
Converte uma cadeia de caracteres do tipo de dados
|
Codifica dados binários em uma representação textual;
os valores de
|
Decodifica dados binários a partir da representação textual;
os valores de
|
As funções encode e decode
oferecem suporte para os seguintes formatos de texto:
O formato base64 é o especificado pelo
RFC 2045 Section 6.8.
Segundo o RFC, as linhas codificadas
são quebradas em 76 caracteres.
No entanto, em vez do marcador de fim de linha
MIME
CRLF, apenas o caractere de nova linha é usado
para marcar o fim da linha.
A função decode ignora os caracteres de
retorno de carro, nova linha, espaço e tabulação.
De outra forma, será gerado erro quando for fornecido para a
função decode dados base64 inválidos —
inclusive quando o preenchimento à direita estiver incorreto.
O formato escape converte bytes zero e bytes
com o bit alto definido em sequências de escape octais
(\nnn), e duplica
as contrabarras.
Outros valores de byte são representados literalmente.
A função decode gera erro se uma
contrabarra não for seguida por uma segunda contrabarra, ou três
dígitos octais; a função aceita os outros valores de byte sem
alterações.
O formato hex representa cada 4 bits de dados
como um dígito hexadecimal, de 0 a
f, escrevendo primeiro o dígito de ordem
superior de cada byte.
A função encode gera os dígitos hexadecimais
a-f em letras minúsculas.
Como a menor unidade de dados é 8 bits, sempre há um número par
de caracteres retornados pela função encode.
A função decode aceita os caracteres
a-f em maiúsculas ou
minúsculas.
É gerado erro quando a função decode
recebe dados hexadecimais inválidos — inclusive quando
é fornecido um número ímpar de caracteres.
Além disso, é possível converter valores inteiros de e para o
tipo de dados bytea.
Converter um inteiro para bytea produz 2, 4 ou 8 bytes,
dependendo da largura do tipo de dados inteiro.
O resultado é a representação em complemento de dois do valor inteiro,
com o byte mais significativo primeiro. Alguns exemplos:
1234::smallint::bytea →\x04d2cast(1234 as bytea) →\x000004d2cast(-1234 as bytea) →\xfffffb2e'\x8000'::bytea::smallint →-32768'\x8000'::bytea::integer →32768
Converter de `bytea` para um inteiro resultará em um
erro se o comprimento de `bytea` exceder a largura do
tipo de dados inteiro.
Veja também a função de agregação string_agg na
Seção 9.21, e as funções de objeto grande
na Seção 33.4.