9.5. Функции и операторы двоичных строк #
В этом разделе описываются функции и операторы для работы с двоичными строками, то есть со значениями типа bytea
. Многие из них идентичны по функциональности и синтаксису описанным в предыдущем разделе функциям, предназначенным для текстовых строк.
В SQL определены несколько строковых функций, в которых аргументы разделяются не запятыми, а ключевыми словами. Подробнее это описано в Таблице 9.11. Postgres Pro также предоставляет варианты этих функций с синтаксисом, обычным для функций (см. Таблицу 9.12).
Таблица 9.11. SQL-функции и операторы для работы с двоичными строками
Функция/оператор Описание Пример(ы) |
---|
bytea || bytea → bytea Соединяет две двоичные строки. '\x123456'::bytea || '\x789a00bcde'::bytea → \x123456789a00bcde
|
bit_length ( bytea ) → integer Возвращает число бит в двоичной строке (это число в 8 раз больше octet_length ). bit_length('\x123456'::bytea) → 24
|
btrim ( bytes bytea , bytesremoved bytea ) → bytea Удаляет наибольшую строку, содержащую только байты, заданные в параметре bytesremoved , с начала и с конца строки bytes . btrim('\x1234567890'::bytea, '\x9012'::bytea) → \x345678
|
ltrim ( bytes bytea , bytesremoved bytea ) → bytea Удаляет наибольшую строку, содержащую только байты, заданные в параметре bytesremoved , с начала строки bytes . ltrim('\x1234567890'::bytea, '\x9012'::bytea) → \x34567890
|
octet_length ( bytea ) → integer Возвращает число байт в двоичной строке. octet_length('\x123456'::bytea) → 3
|
overlay ( bytes bytea PLACING newsubstring bytea FROM start integer [FOR count integer ] ) → bytea Заменяет подстроку в bytes , начиная с байта с номером start , длиной count байт, на подстроку newsubstring . В отсутствие параметра count количество заменяемых байтов определяется длиной newsubstring . overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3) → \x12020390
|
position ( substring bytea IN bytes bytea ) → integer Возвращает начальную позицию первого вхождения substring в bytes либо 0, если такого вхождения нет. position('\x5678'::bytea in '\x1234567890'::bytea) → 3
|
rtrim ( bytes bytea , bytesremoved bytea ) → bytea Удаляет наибольшую строку, содержащую только байты, заданные в параметре bytesremoved , с конца строки bytes . rtrim('\x1234567890'::bytea, '\x9012'::bytea) → \x12345678
|
substring ( bytes bytea [FROM start integer ] [FOR count integer ] ) → bytea Извлекает из bytes подстроку, начиная с позиции start (если она указана), длиной до count символов (если она указана). Параметры start и count могут опускаться, но не оба сразу. substring('\x1234567890'::bytea from 3 for 2) → \x5678
|
trim ( [LEADING | TRAILING | BOTH ] bytesremoved bytea FROM bytes bytea ) → bytea Удаляет наибольшую строку, содержащую только байты, заданные в параметре bytesremoved , с начала, с конца или с обеих сторон (по умолчанию подразумевается указание BOTH ) строки bytes . trim('\x9012'::bytea from '\x1234567890'::bytea) → \x345678
|
trim ( [LEADING | TRAILING | BOTH ] [FROM ] bytes bytea , bytesremoved bytea ) → bytea
Это нестандартный синтаксис вызова trim() . trim(both from '\x1234567890'::bytea, '\x9012'::bytea) → \x345678
|
В PostgreSQL есть и другие функции для работы с двоичными строками, перечисленные в Таблице 9.12. Некоторые из них используются в качестве внутренней реализации стандартных функций SQL, приведённых в Таблице 9.11.
Таблица 9.12. Другие функции для работы с двоичными строками
Функция Описание Пример(ы) |
---|
bit_count ( bytes bytea ) → bigint Возвращает число бит в двоичной строке (эту операцию также называют «popcount»). bit_count('\x1234567890'::bytea) → 15
|
get_bit ( bytes bytea , n bigint ) → integer Извлекает из двоичной строки бит с номером n. get_bit('\x1234567890'::bytea, 30) → 1
|
get_byte ( bytes bytea , n integer ) → integer Извлекает из двоичной строки байт с номером n. get_byte('\x1234567890'::bytea, 4) → 144
|
length ( bytea ) → integer Выдаёт число байт в двоичной строке. length('\x1234567890'::bytea) → 5
|
length ( bytes bytea , encoding name ) → integer
Выдаёт число символов в двоичной строке, в предположении, что она содержит текст в кодировке encoding . length('jose'::bytea, 'UTF8') → 4
|
md5 ( bytea ) → text Вычисляет MD5-хеш двоичной строки и выдаёт результат в шестнадцатеричном виде. md5('Th\000omas'::bytea) → 8ab2d3c9689aaf18b4958c334c82d8b1
|
set_bit ( bytes bytea , n bigint , newvalue integer ) → bytea Устанавливает в двоичной строке для бита с номером n значение newvalue . set_bit('\x1234567890'::bytea, 30, 0) → \x1234563890
|
set_byte ( bytes bytea , n integer , newvalue integer ) → bytea Устанавливает в двоичной строке для байта с номером n значение newvalue . set_byte('\x1234567890'::bytea, 4, 64) → \x1234567840
|
sha224 ( bytea ) → bytea Вычисляет хеш SHA-224 для двоичной строки. sha224('abc'::bytea) → \x23097d223405d8228642a477bda255b32aadbce4bda0b3f7e36c9da7
|
sha256 ( bytea ) → bytea Вычисляет хеш SHA-256 для двоичной строки. sha256('abc'::bytea) → \xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
|
sha384 ( bytea ) → bytea Вычисляет хеш SHA-384 для двоичной строки. sha384('abc'::bytea) → \xcb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7
|
sha512 ( bytea ) → bytea Вычисляет хеш SHA-512 для двоичной строки. sha512('abc'::bytea) → \xddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f
|
substr ( bytes bytea , start integer [, count integer ] ) → bytea Извлекает из bytes подстроку, начиная с позиции start , длиной до count байт (если это значение указано). (Ей равнозначна функция substring(bytes from start for count ) .) substr('\x1234567890'::bytea, 3, 2) → \x5678
|
Для функций get_byte
и set_byte
байты нумеруется с 0. Функции get_bit
и set_bit
нумеруют биты справа налево; например, бит 0 будет меньшим значащим битом первого байта, а бит 15 — большим значащим битом второго байта.
По историческим причинам функция md5
возвращает значение в шестнадцатеричном виде в типе text
, тогда как функции SHA-2 возвращают тип bytea
. Для преобразования значения из одного представления в другое используйте функции encode
и decode
. Например, вызвав encode(sha256('abc'), 'hex')
, вы получите значение в шестнадцатеричном виде в текстовой строке, а decode(md5('abc'), 'hex')
выдаст значение bytea
.
В Таблице 9.13 показаны функции для перекодирования текста из одного набора символов (кодировки) в другой и для представления произвольных двоичных данных в текстовом виде. Для всех этих функций аргумент или результат типа text
содержит текст в текущей кодировке базы данных, тогда как аргументы или результаты типа bytea
содержат текст в кодировке, заданной соответствующим аргументом.
Таблица 9.13. Функции для преобразования текстовых/двоичных строк
Функция Описание Пример(ы) |
---|
convert ( bytes bytea , src_encoding name , dest_encoding name ) → bytea Преобразует двоичную строку, содержащую текст в кодировке src_encoding , в двоичную строку с текстом в кодировке dest_encoding (возможные варианты преобразований описаны в Подразделе 22.3.4). convert('text_in_utf8', 'UTF8', 'LATIN1') → \x746578745f696e5f75746638
|
convert_from ( bytes bytea , src_encoding name ) → text Преобразует двоичную строку, содержащую текст в кодировке src_encoding , в строку типа text в кодировке базы данных (возможные варианты преобразований описаны в Подразделе 22.3.4). convert_from('text_in_utf8', 'UTF8') → text_in_utf8
|
convert_to ( string text , dest_encoding name ) → bytea Преобразует строку типа text в кодировке базы данных в двоичную строку с текстом в кодировке dest_encoding (возможные варианты преобразований описаны в Подразделе 22.3.4). convert_to('некоторый_текст', 'UTF8') → \x736f6d655f74657874
|
encode ( bytes bytea , format text ) → text Переводит двоичные данные в текстовое представление; поддерживаются следующие значения format : base64 , escape , hex . encode('123\000\001', 'base64') → MTIzAAE=
|
decode ( string text , format text ) → bytea Переводит двоичные данные из текстового представления; поддерживает те же значения format , что и функция encode . decode('MTIzAAE=', 'base64') → \x3132330001
|
Функции encode
и decode
поддерживают следующие текстовые форматы:
- base64 #
Формат base64
описан в RFC 2045, Разделе 6.8. Согласно этому RFC, закодированные строки разбиваются по 76 символов. Однако завершаются строки не символами CRLF (как требуется в соответствии с MIME), а одним символом конца строки. Функция decode
, с другой стороны, игнорирует символы перевода каретки, новой строки, пробелы и табуляции. Если на вход decode
поступают некорректные данные base64, возникает ошибка — в том числе, если оказывается некорректным завершающее выравнивание.
- escape #
В формате escape
нулевые байты и байты с установленным старшим битом переводятся в восьмеричные спецпоследовательности (\
nnn
), а обратная косая черта дублируется. Другие байтовые значения представляются в буквальном виде. Функция decode
выдаст ошибку, встретив обратную косую черту, за которой не следует ещё одна обратная косая или три восьмеричных цифры; другие значения байта она принимает без изменений.
- hex #
В формате hex
каждые 4 бита данных представляются одной шестнадцатеричной цифрой, от 0
до f
, при этом первой идёт цифра, представляющая старшие биты. Шестнадцатеричные цифры a
-f
функция encode
выводит в нижнем регистре. Так как наименьшая единица данных — байт (8 бит), функция encode
всегда возвращает чётное количество символов. Функция decode
, с другой стороны, принимает символы a
-f
в любом регистре. Если на вход функции decode
поступают некорректные данные, возникает ошибка — в том числе, если число символов оказывается нечётным.
См. также агрегатную функцию string_agg
в Разделе 9.21 и функции для работы с большими объектами в Разделе 33.4.