9.5. Fonctions et opérateurs pour les chaînes binaires

» » »

Précédent	Niveau supérieur	Suivant
9.4. Fonctions et opérateurs sur des chaînes de caractères	Sommaire	9.6. Fonctions et opérateurs pour les chaînes de bit

9.5. Fonctions et opérateurs pour les chaînes binaires #

Cette section décrit les fonctions et opérateurs pour examiner et manipuler des chaînes binaires, c'est-à-dire des valeurs de type bytea. Beaucoup sont équivalentes, dans le but et dans la syntaxe, aux fonctions de chaînes de caractères décrites dans la section précédente.

Le standard SQL définit certaines fonctions de chaînes de caractères utilisant des mots-clés plutôt que des virgules, pour séparer des arguments. Les détails sont dans Tableau 9.11. PostgreSQL fournit aussi des versions de ces fonctions utilisant la syntaxe d'appel de fonctions standards (voir Tableau 9.12).

Tableau 9.11. Fonctions et opérateurs SQL pour des chaînes binaires

Fonction/Opérateur Description Exemple(s)
`bytea` `\|\|` `bytea` → `bytea` Concatène deux chaînes binaires. `'\x123456'::bytea \|\| '\x789a00bcde'::bytea` → `\x123456789a00bcde`
`bit_length` ( `bytea` ) → `integer` Renvoie le nombre de bits dans la chaîne binaire (8 fois le résultat de `octet_length`). `bit_length('\x123456'::bytea)` → `24`
`btrim` ( `bytes` `bytea`, `bytesremoved` `bytea` ) → `bytea` Supprime la chaîne la plus longue contenant seulement des octets apparaissant dans `bytesremoved` à partir du début et à la fin de `bytes`. `btrim('\x1234567890'::bytea, '\x9012'::bytea)` → `\x345678`
`ltrim` ( `bytes` `bytea`, `bytesremoved` `bytea` ) → `bytea` Supprime la plus longue chaîne contenant seulement les octets apparaissant dans `bytesremoved` depuis le début de `bytes`. `ltrim('\x1234567890'::bytea, '\x9012'::bytea)` → `\x34567890`
`octet_length` ( `bytea` ) → `integer` Renvoie le nombre d'octets dans la chaîne binaire. `octet_length('\x123456'::bytea)` → `3`
`overlay` ( `bytes` `bytea` `PLACING` `newsubstring` `bytea` `FROM` `start` `integer` [ `FOR` `count` `integer` ] ) → `bytea` Remplace la sous-chaîne de `bytes` commençant au `start`-ième octet et s'étendant sur `count` octets avec `newsubstring`. Si `count` est omis, sa valeur par défaut est la taille de `newsubstring`. `overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)` → `\x12020390`
`position` ( `substring` `bytea` `IN` `bytes` `bytea` ) → `integer` Renvoie la première position de début de `substring` dans `bytes`, ou zéro s'il n'est pas présent. `position('\x5678'::bytea in '\x1234567890'::bytea)` → `3`
`rtrim` ( `bytes` `bytea`, `bytesremoved` `bytea` ) → `bytea` Supprime la plus longue chaîne contenant seulement les octets apparaissant dans `bytesremoved` depuis la fin de `bytes`. `rtrim('\x1234567890'::bytea, '\x9012'::bytea)` → `\x12345678`
`substring` ( `bytes` `bytea` [ `FROM` `start` `integer` ] [ `FOR` `count` `integer` ] ) → `bytea` Extrait la sous-chaîne de `bytes` commençant au `start`-ième octet s'il est indiqué, et s'arrêtant après `count` octets s'il est indiqué. Il est nécessaire de fournir au moins soit `start` soit `count`. `substring('\x1234567890'::bytea from 3 for 2)` → `\x5678`
`trim` ( [ `LEADING` \| `TRAILING` \| `BOTH` ] `bytesremoved` `bytea` `FROM` `bytes` `bytea` ) → `bytea` Supprime la plus longue chaîne contenant seulement les octets apparaissant dans `bytesremoved` à partir du début, de la fin ou des deux de `bytes`. `trim('\x9012'::bytea from '\x1234567890'::bytea)` → `\x345678`
`trim` ( [ `LEADING` \| `TRAILING` \| `BOTH` ] [ `FROM` ] `bytes` `bytea`, `bytesremoved` `bytea` ) → `bytea` Ceci est une syntaxe non standard pour `trim()`. `trim(both from '\x1234567890'::bytea, '\x9012'::bytea)` → `\x345678`

Fonction/Opérateur

Description

Exemple(s)

bytea || bytea → bytea

Concatène deux chaînes binaires.

'\x123456'::bytea || '\x789a00bcde'::bytea → \x123456789a00bcde

bit_length ( bytea ) → integer

Renvoie le nombre de bits dans la chaîne binaire (8 fois le résultat de octet_length).

bit_length('\x123456'::bytea) → 24

btrim ( bytes bytea, bytesremoved bytea ) → bytea

Supprime la chaîne la plus longue contenant seulement des octets apparaissant dans bytesremoved à partir du début et à la fin de bytes.

btrim('\x1234567890'::bytea, '\x9012'::bytea) → \x345678

ltrim ( bytes bytea, bytesremoved bytea ) → bytea

Supprime la plus longue chaîne contenant seulement les octets apparaissant dans bytesremoved depuis le début de bytes.

ltrim('\x1234567890'::bytea, '\x9012'::bytea) → \x34567890

octet_length ( bytea ) → integer

Renvoie le nombre d'octets dans la chaîne binaire.

octet_length('\x123456'::bytea) → 3

overlay ( bytes bytea PLACING newsubstring bytea FROM start integer [ FOR count integer ] ) → bytea

Remplace la sous-chaîne de bytes commençant au start-ième octet et s'étendant sur count octets avec newsubstring. Si count est omis, sa valeur par défaut est la taille de newsubstring.

overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3) → \x12020390

position ( substring bytea IN bytes bytea ) → integer

Renvoie la première position de début de substring dans bytes, ou zéro s'il n'est pas présent.

position('\x5678'::bytea in '\x1234567890'::bytea) → 3

rtrim ( bytes bytea, bytesremoved bytea ) → bytea

Supprime la plus longue chaîne contenant seulement les octets apparaissant dans bytesremoved depuis la fin de bytes.

rtrim('\x1234567890'::bytea, '\x9012'::bytea) → \x12345678

substring ( bytes bytea [ FROM start integer ] [ FOR count integer ] ) → bytea

Extrait la sous-chaîne de bytes commençant au start-ième octet s'il est indiqué, et s'arrêtant après count octets s'il est indiqué. Il est nécessaire de fournir au moins soit start soit count.

substring('\x1234567890'::bytea from 3 for 2) → \x5678

trim ( [ LEADING | TRAILING | BOTH ] bytesremoved bytea FROM bytes bytea ) → bytea

Supprime la plus longue chaîne contenant seulement les octets apparaissant dans bytesremoved à partir du début, de la fin ou des deux de bytes.

trim('\x9012'::bytea from '\x1234567890'::bytea) → \x345678

trim ( [ LEADING | TRAILING | BOTH ] [ FROM ] bytes bytea, bytesremoved bytea ) → bytea

Ceci est une syntaxe non standard pour trim().

trim(both from '\x1234567890'::bytea, '\x9012'::bytea) → \x345678

Des fonctions supplémentaires de manipulation de chaîne binaire sont disponibles et listées dans Tableau 9.12. Certaines d'entre elles sont utilisées en interne pour implémenter les fonctions de chaînes du standard SQL listées dans Tableau 9.11.

Tableau 9.12. Autres fonctions de chaînes binaires

Fonction Description Exemple(s)
`bit_count` ( `bytes` `bytea` ) → `bigint` Renvoie le nombre de bits initialisés dans une chaîne de bits (également appelée « popcount »). `bit_count('\x1234567890'::bytea)` → `15`
`get_bit` ( `bytes` `bytea`, `n` `bigint` ) → `integer` Extrait le n-ième bit de la chaîne binaire. `get_bit('\x1234567890'::bytea, 30)` → `1`
`get_byte` ( `bytes` `bytea`, `n` `integer` ) → `integer` Extrait le n-ième octet de la chaîne binaire. `get_byte('\x1234567890'::bytea, 4)` → `144`
`length` ( `bytea` ) → `integer` Renvoie le nombre d'octets de la chaîne binaire. `length('\x1234567890'::bytea)` → `5`
`length` ( `bytes` `bytea`, `encoding` `name` ) → `integer` Renvoie le nombre de caractères de la chaîne binaire, en supposant qu'il s'agit de texte dans l'encodage indiqué par `encoding`. `length('jose'::bytea, 'UTF8')` → `4`
`md5` ( `bytea` ) → `text` Calcule le hachage MD5 dans la chaîne binaire, le résultat étant écrit en hexadécimal. `md5('Th\000omas'::bytea)` → `8ab2d3c9689aaf18b4958c334c82d8b1`
`set_bit` ( `bytes` `bytea`, `n` `bigint`, `newvalue` `integer` ) → `bytea` Initialise le n-ième bit dans la chaîne binaire à la valeur `newvalue`. `set_bit('\x1234567890'::bytea, 30, 0)` → `\x1234563890`
`set_byte` ( `bytes` `bytea`, `n` `integer`, `newvalue` `integer` ) → `bytea` Initialise le n-ième octet dans la chaîne binaire à la valeur `newvalue`. `set_byte('\x1234567890'::bytea, 4, 64)` → `\x1234567840`
`sha224` ( `bytea` ) → `bytea` Calcule le hachage SHA-224 de la chaîne binaire. `sha224('abc'::bytea)` → `\x23097d223405d8228642a477bda255b32aadbce4bda0b3f7e36c9da7`
`sha256` ( `bytea` ) → `bytea` Calcule le hachage SHA-256 de la chaîne binaire. `sha256('abc'::bytea)` → `\xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad`
`sha384` ( `bytea` ) → `bytea` Calcule le hachage SHA-384 de la chaîne binaire. `sha384('abc'::bytea)` → `\xcb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7`
`sha512` ( `bytea` ) → `bytea` Calcule le hachage SHA-512 de la chaîne binaire. `sha512('abc'::bytea)` → `\xddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f`
`substr` ( `bytes` `bytea`, `start` `integer` [, `count` `integer` ] ) → `bytea` Extrait la sous-chaîne de `bytes` commençant au `start`-ième octet, et s'étendant sur `count` octets si ce dernier est indiqué. (Identique à `substring(bytes from start for count)`.) `substr('\x1234567890'::bytea, 3, 2)` → `\x5678`

Fonction

Description

Exemple(s)

bit_count ( bytes bytea ) → bigint

Renvoie le nombre de bits initialisés dans une chaîne de bits (également appelée « popcount »).

bit_count('\x1234567890'::bytea) → 15

get_bit ( bytes bytea, n bigint ) → integer

Extrait le n-ième bit de la chaîne binaire.

get_bit('\x1234567890'::bytea, 30) → 1

get_byte ( bytes bytea, n integer ) → integer

Extrait le n-ième octet de la chaîne binaire.

get_byte('\x1234567890'::bytea, 4) → 144

length ( bytea ) → integer

Renvoie le nombre d'octets de la chaîne binaire.

length('\x1234567890'::bytea) → 5

length ( bytes bytea, encoding name ) → integer

Renvoie le nombre de caractères de la chaîne binaire, en supposant qu'il s'agit de texte dans l'encodage indiqué par encoding.

length('jose'::bytea, 'UTF8') → 4

md5 ( bytea ) → text

Calcule le hachage MD5 dans la chaîne binaire, le résultat étant écrit en hexadécimal.

md5('Th\000omas'::bytea) → 8ab2d3c9689aaf18b4958c334c82d8b1

set_bit ( bytes bytea, n bigint, newvalue integer ) → bytea

Initialise le n-ième bit dans la chaîne binaire à la valeur newvalue.

set_bit('\x1234567890'::bytea, 30, 0) → \x1234563890

set_byte ( bytes bytea, n integer, newvalue integer ) → bytea

Initialise le n-ième octet dans la chaîne binaire à la valeur newvalue.

set_byte('\x1234567890'::bytea, 4, 64) → \x1234567840

sha224 ( bytea ) → bytea

Calcule le hachage SHA-224 de la chaîne binaire.

sha224('abc'::bytea) → \x23097d223405d8228642a477bda255b32aadbce4bda0b3f7e36c9da7

sha256 ( bytea ) → bytea

Calcule le hachage SHA-256 de la chaîne binaire.

sha256('abc'::bytea) → \xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

sha384 ( bytea ) → bytea

Calcule le hachage SHA-384 de la chaîne binaire.

sha384('abc'::bytea) → \xcb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7

sha512 ( bytea ) → bytea

Calcule le hachage SHA-512 de la chaîne binaire.

sha512('abc'::bytea) → \xddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f

substr ( bytes bytea, start integer [, count integer ] ) → bytea

Extrait la sous-chaîne de bytes commençant au start-ième octet, et s'étendant sur count octets si ce dernier est indiqué. (Identique à substring(bytes from start for count).)

substr('\x1234567890'::bytea, 3, 2) → \x5678

Les fonctions get_byte et set_byte numérotent le premier octet d'une chaîne binaire comme l'octet 0. Les fonctions get_bit et set_bit numérotent les bits à partir de la droite dans chaque octet. Par exemple, le bit 0 est le bit le moins significatif du premier octet, et le bit 15 est le bit le plus significatif du deuxième octet.

Pour des raisons historiques, la fonction md5 renvoie une valeur encodée en hexadécimal de type text alors que les fonctions SHA-2 renvoient le type bytea. Utilisez les fonctions encode et decode pour convertir entre les deux. Par exemple, écrivez encode(sha256('abc'), 'hex') pour obtenir une représentation textuelle encodée en hexadécimal ou decode(md5('abc'), 'hex') pour obtenir une valeur de type bytea.

Les fonctions de conversion de chaîne entre des ensembles de caractères différents (encodage), et pour représenter des données binaires arbitraires dans leur forme textuelle, sont affichées dans Tableau 9.13. Pour ces fonctions, un argument ou un résultat de type text est exprimé dans l'encodage par défaut de la base de données alors que les arguments ou résultats de type bytea sont dans un encodage nommé par un autre argument.

Tableau 9.13. Fonctions de conversion texte/binaire

Fonction Description Exemple(s)
`convert` ( `bytes` `bytea`, `src_encoding` `name`, `dest_encoding` `name` ) → `bytea` Convertit une chaîne binaire représentant du texte dans l'encodage `src_encoding` en une chaîne binaire dans l'encodage `dest_encoding` (voir Section 23.3.4 pour les conversions disponibles). `convert('text_in_utf8', 'UTF8', 'LATIN1')` → `\x746578745f696e5f75746638`
`convert_from` ( `bytes` `bytea`, `src_encoding` `name` ) → `text` Convertit une chaîne binaire représentant du texte dans l'encodage `src_encoding` vers le type `text` dans l'encodage de la base de données (voir Section 23.3.4 pour les conversions disponibles). `convert_from('text_in_utf8', 'UTF8')` → `text_in_utf8`
`convert_to` ( `string` `text`, `dest_encoding` `name` ) → `bytea` Convertit une chaîne de type `text` (dans l'encodage de la base) en une chaîne binaire encodée dans l'encodage `dest_encoding` (voir Section 23.3.4 pour les conversions disponibles). `convert_to('some_text', 'UTF8')` → `\x736f6d655f74657874`
`encode` ( `bytes` `bytea`, `format` `text` ) → `text` Encode les données binaires dans leur représentation textuelle ; les valeurs `format` disponibles sont : `base64`, `escape`, `hex`. `encode('123\000\001', 'base64')` → `MTIzAAE=`
`decode` ( `string` `text`, `format` `text` ) → `bytea` Décode les données binaires à partir d'une représentation textuelle ; les valeurs supportées de `format` sont les mêmes que pour `encode`. `decode('MTIzAAE=', 'base64')` → `\x3132330001`

Fonction

Description

Exemple(s)

convert ( bytes bytea, src_encoding name, dest_encoding name ) → bytea

Convertit une chaîne binaire représentant du texte dans l'encodage src_encoding en une chaîne binaire dans l'encodage dest_encoding (voir Section 23.3.4 pour les conversions disponibles).

convert('text_in_utf8', 'UTF8', 'LATIN1') → \x746578745f696e5f75746638

convert_from ( bytes bytea, src_encoding name ) → text

Convertit une chaîne binaire représentant du texte dans l'encodage src_encoding vers le type text dans l'encodage de la base de données (voir Section 23.3.4 pour les conversions disponibles).

convert_from('text_in_utf8', 'UTF8') → text_in_utf8

convert_to ( string text, dest_encoding name ) → bytea

Convertit une chaîne de type text (dans l'encodage de la base) en une chaîne binaire encodée dans l'encodage dest_encoding (voir Section 23.3.4 pour les conversions disponibles).

convert_to('some_text', 'UTF8') → \x736f6d655f74657874

encode ( bytes bytea, format text ) → text

Encode les données binaires dans leur représentation textuelle ; les valeurs format disponibles sont : base64, escape, hex.

encode('123\000\001', 'base64') → MTIzAAE=

decode ( string text, format text ) → bytea

Décode les données binaires à partir d'une représentation textuelle ; les valeurs supportées de format sont les mêmes que pour encode.

decode('MTIzAAE=', 'base64') → \x3132330001

Les fonctions encode et decode supportent les formats textuels suivants :

base64 #: Le format base64 est celui de la RFC 2045 Section 6.8. D'après la RFC, les lignes encodées sont réparties sur 76 caractères. Néanmoins, à la place du marqueur de fin de ligne CRLF MIME, seul un caractère nouvelle ligne est utilisée pour une fin de ligne. La fonction decode ignore les caractères de retour chariot, de nouvelle ligne, l'espace et la tabulation. Sinon une erreur est levée quand decode se voit fourni des données base64 invalides -- ceci incluant quand le remplissage en fin est incorrect.
escape #: Le format escape convertit les octets zéro et les octets avec le bit de poids fort configuré en séquences d'échappement octales (\nnn), et il double les antislashes. Les autres valeurs d'octet sont représentées littéralement. La fonction decode lèvera une erreur si un antislash n'est pas suivi soit par un deuxième antislash ou par trois chiffres octals. Il accepte les autres valeurs sans changement.
hex #: Le format hex représente chacun 4 bits de données sous la forme d'un chiffre hexadécimal, de 0 à f, en écrivant le chiffre de haut niveau de chaque octet en premier. La fonction encode affiche les chiffres hexadécimaux a-f en minuscule. Comme l'unité la plus petite des données est de 8 bits, un nombre pair de caractères est renvoyé par encode. La fonction decode accepte les caractères a-f en minuscule comme en majuscule. Une erreur est levée quand decode se voit fourni des données hexadécimales invalides -- ceci incluant un nombre impair de caractères.

Voir aussi la fonction d'agrégat string_agg dans Section 9.21 et les fonctions sur les Large Objects dans Section 33.4.