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