Postgres Pro Enterprise : Документация: 11: 9.4. Строковые функции и операторы : Компания Postgres Professional

9.4. Строковые функции и операторы
Пред.	Наверх	Глава 9. Функции и операторы	Начало	След.

9.4. Строковые функции и операторы

9.4.1. format

В этом разделе описаны функции и операторы для работы с текстовыми строками. Под строками в данном контексте подразумеваются значения типов character, character varying и text. Если не отмечено обратное, все нижеперечисленные функции работают со всеми этими типами, хотя с типом character следует учитывать возможные эффекты автоматического дополнения строк пробелами. Некоторые из этих функций также поддерживают битовые строки.

В SQL определены несколько строковых функций, в которых аргументы разделяются не запятыми, а ключевыми словами. Они перечислены в Таблице 9.8. Postgres Pro также предоставляет варианты этих функций с синтаксисом, обычным для функций (см. Таблицу 9.9).

Примечание

До версии 8.3 в PostgreSQL эти функции также прозрачно принимали значения некоторых не строковых типов, неявно приводя эти значения к типу text. Сейчас такие приведения исключены, так как они часто приводили к неожиданным результатам. Однако оператор конкатенации строк (||) по-прежнему принимает не только строковые данные, если хотя бы один аргумент имеет строковый тип, как показано в Таблице 9.8. Во всех остальных случаях для повторения предыдущего поведения потребуется добавить явное преобразование в text.

Таблица 9.8. Строковые функции и операторы языка SQL

Функция	Тип результата	Описание	Пример	Результат
`string \|\| string`	`text`	Конкатенация строк	`'Post' \|\| 'greSQL'`	`PostgreSQL`
`string \|\| не string` или `не string \|\| string`	`text`	Конкатенация строк с одним не строковым операндом	`'Value: ' \|\| 42`	`Value: 42`
`bit_length(string)`	`int`	Число бит в строке	`bit_length('jose')`	`32`
`char_length(string)` или `character_length(string)`	`int`	Число символов в строке	`char_length('jose')`	`4`
`lower(string)`	`text`	Переводит символы строки в нижний регистр	`lower('TOM')`	`tom`
`octet_length(string)`	`int`	Число байт в строке	`octet_length('jose')`	`4`
`overlay(string placing string from int [for int])`	`text`	Заменяет подстроку	`overlay('Txxxxas' placing 'hom' from 2 for 4)`	`Thomas`
`position(substring in string)`	`int`	Положение указанной подстроки	`position('om' in 'Thomas')`	`3`
`substring(string [from int] [for int])`	`text`	Извлекает подстроку	`substring('Thomas' from 2 for 3)`	`hom`
`substring(string from шаблон)`	`text`	Извлекает подстроку, соответствующую регулярному выражению в стиле POSIX. Подробно шаблоны описаны в Разделе 9.7.	`substring('Thomas' from '...$')`	`mas`
`substring(string from шаблон for спецсимвол)`	`text`	Извлекает подстроку, соответствующую регулярному выражению в стиле SQL. Подробно шаблоны описаны в Разделе 9.7.	`substring('Thomas' from '%#"o_a#"_' for '#')`	`oma`
`trim([leading \| trailing \| both] [characters] from string)`	`text`	Удаляет наибольшую подстроку, содержащую только символы `characters` (по умолчанию пробелы), с начала (`leading`), с конца (`trailing`) или с обеих сторон (`both`, (по умолчанию)) строки `string`	`trim(both 'xyz' from 'yxTomxx')`	`Tom`
`trim([leading \| trailing \| both] [from] string [, characters] )`	`text`	Нестандартный синтаксис `trim()`	`trim(both from 'yxTomxx', 'xyz')`	`Tom`
`upper(string)`	`text`	Переводит символы строки в верхний регистр	`upper('tom')`	`TOM`

Кроме этого, в PostgreSQL есть и другие функции для работы со строками, перечисленные в Таблице 9.9. Некоторые из них используются в качестве внутренней реализации стандартных строковых функций SQL, приведённых в Таблице 9.8.

Таблица 9.9. Другие строковые функции

Функция	Тип результата	Описание	Пример	Результат
`ascii(string)`	`int`	Возвращает ASCII-код первого символа аргумента. Для UTF8 возвращает код символа в Unicode. Для других многобайтных кодировок аргумент должен быть ASCII-символом.	`ascii('x')`	`120`
`btrim(string text [, characters text])`	`text`	Удаляет наибольшую подстроку, состоящую только из символов `characters` (по умолчанию пробелов), с начала и с конца строки `string`	`btrim('xyxtrimyyx', 'xyz')`	`trim`
`chr(int)`	`text`	Возвращает символ с данным кодом. Для UTF8 аргумент воспринимается как код символа Unicode, а для других кодировок он должен указывать на ASCII-символ. Код 0 (NULL) не допускается, так как байты с нулевым кодом в текстовых строках сохранить нельзя.	`chr(65)`	`A`
`concat(str "any" [, str "any" [, ...] ])`	`text`	Соединяет текстовые представления всех аргументов, игнорируя NULL.	`concat('abcde', 2, NULL, 22)`	`abcde222`
`concat_ws(sep text, str "any" [, str "any" [, ...] ])`	`text`	Соединяет все аргументы, кроме первого, через разделитель, игнорируя аргументы NULL. Разделитель указывается в первом аргументе.	`concat_ws(',', 'abcde', 2, NULL, 22)`	`abcde,2,22`
`convert(string bytea, src_encoding name, dest_encoding name)`	`bytea`	Преобразует строку `string` из кодировки `src_encoding` в `dest_encoding`. Переданная строка должна быть допустимой для исходной кодировки. Преобразования могут быть определены с помощью `CREATE CONVERSION`. Все встроенные преобразования перечислены в Таблице 9.10.	`convert('text_in_utf8', 'UTF8', 'LATIN1')`	строка `text_in_utf8`, представленная в кодировке Latin-1 (ISO 8859-1)
`convert_from(string bytea, src_encoding name)`	`text`	Преобразует строку `string` из кодировки `src_encoding` в кодировку базы данных. Переданная строка должна быть допустимой для исходной кодировки.	`convert_from('text_in_utf8', 'UTF8')`	строка `text_in_utf8`, представленная в кодировке текущей базы данных
`convert_to(string text, dest_encoding name)`	`bytea`	Преобразует строку в кодировку `dest_encoding`.	`convert_to('некоторый текст', 'UTF8')`	`некоторый текст`, представленный в кодировке UTF8
`decode(string text, format text)`	`bytea`	Получает двоичные данные из текстового представления в `string`. Значения параметра `format` те же, что и для функции `encode`.	`decode('MTIzAAE=', 'base64')`	`\x3132330001`
`encode(data bytea, format text)`	`text`	Переводит двоичные данные в текстовое представление в одном из форматов: `base64`, `hex`, `escape`. Формат `escape` преобразует нулевые байты и байты с 1 в старшем бите в восьмеричные последовательности `\nnn` и дублирует обратную косую черту.	`encode('123\000\001', 'base64')`	`MTIzAAE=`
`format(formatstr text [, formatarg "any" [, ...] ])`	`text`	Форматирует аргумент в соответствии со строкой формата. Эта функция работает подобно `sprintf` в языке C. См. Подраздел 9.4.1.	`format('Hello %s, %1$s', 'World')`	`Hello World, World`
`initcap(string)`	`text`	Переводит первую букву каждого слова в строке в верхний регистр, а остальные — в нижний. Словами считаются последовательности алфавитно-цифровых символов, разделённые любыми другими символами.	`initcap('hi THOMAS')`	`Hi Thomas`
`left(str text, n int)`	`text`	Возвращает первые `n` символов в строке. Когда `n` меньше нуля, возвращаются все символы слева, кроме последних \|`n`\|.	`left('abcde', 2)`	`ab`
`length(string)`	`int`	Число символов в строке `string`	`length('jose')`	`4`
`length(string bytea, encoding name )`	`int`	Число символов, которые содержит строка `string` в заданной кодировке `encoding`. Переданная строка должна быть допустимой в этой кодировке.	`length('jose', 'UTF8')`	`4`
`lpad(string text, length int [, fill text])`	`text`	Дополняет строку `string` слева до длины `length` символами `fill` (по умолчанию пробелами). Если длина строки уже больше заданной, она обрезается справа.	`lpad('hi', 5, 'xy')`	`xyxhi`
`ltrim(string text [, characters text])`	`text`	Удаляет наибольшую подстроку, содержащую только символы `characters` (по умолчанию пробелы), с начала строки `string`	`ltrim('zzzytest', 'xyz')`	`test`
`md5(string)`	`text`	Вычисляет MD5-хеш строки `string` и возвращает результат в 16-ричном виде	`md5('abc')`	`900150983cd24fb0 d6963f7d28e17f72`
`parse_ident(qualified_identifier text [, strictmode boolean DEFAULT true ] )`	`text[]`	Раскладывает полный идентификатор, задаваемый параметром `qualified_identifier`, на массив идентификаторов, удаляя кавычки, обрамляющие отдельные идентификаторы. По умолчанию лишние символы после последнего идентификатора вызывают ошибку, но если отключить строгий режим (передать во втором параметре `false`), такие символы игнорируются. (Это поведение полезно для разбора имён таких объектов, как функции.) Заметьте, что эта функция не усекает чрезмерно длинные идентификаторы. Если вы хотите получить усечённые имена, можно привести результат к `name[]`.	`parse_ident('"SomeSchema".someTable')`	`{SomeSchema,sometable}`
`pg_client_encoding()`	`name`	Возвращает имя текущей клиентской кодировки	`pg_client_encoding()`	`SQL_ASCII`
`quote_ident(string text)`	`text`	Переданная строка оформляется для использования в качестве идентификатора в SQL -операторе. При необходимости идентификатор заключается в кавычки (например, если он содержит символы, недопустимые в открытом виде, или буквы в разном регистре). Если переданная строка содержит кавычки, они дублируются. См. также Пример 44.1.	`quote_ident('Foo bar')`	`"Foo bar"`
`quote_literal(string text)`	`text`	Переданная строка оформляется для использования в качестве текстовой строки в SQL-операторе. Включённые символы апостроф и обратная косая черта при этом дублируются. Заметьте, что `quote_literal` возвращает NULL, когда на вход ей передаётся строка NULL; если же нужно получить представление и такого аргумента, лучше использовать `quote_nullable`. См. также Пример 44.1.	`quote_literal(E'O\'Reilly')`	`'O''Reilly'`
`quote_literal(value anyelement)`	`text`	Переводит данное значение в текстовый вид и заключает в апострофы как текстовую строку. Символы апостроф и обратная косая черта при этом дублируются.	`quote_literal(42.5)`	`'42.5'`
`quote_nullable(string text)`	`text`	Переданная строка оформляется для использования в качестве текстовой строки в SQL-операторе; при этом для аргумента NULL возвращается строка `NULL`. Символы апостроф и обратная косая черта дублируются должным образом. См. также Пример 44.1.	`quote_nullable(NULL)`	`NULL`
`quote_nullable(value anyelement)`	`text`	Переводит данное значение в текстовый вид и заключает в апострофы как текстовую строку, при этом для аргумента NULL возвращается строка `NULL`. Символы апостроф и обратная косая черта дублируются должным образом.	`quote_nullable(42.5)`	`'42.5'`
`regexp_match(string text, pattern text [, flags text])`	`text[]`	Возвращает подходящие подстроки, полученные из первого вхождения регулярного выражения POSIX в строке `string`. Подробности описаны в Подразделе 9.7.3.	`regexp_match('foobarbequebaz', '(bar)(beque)')`	`{bar,beque}`
`regexp_matches(string text, pattern text [, flags text])`	`setof text[]`	Возвращает подходящие подстроки, полученные в результате применения регулярного выражения POSIX к `string`. Подробности описаны в Подразделе 9.7.3.	`regexp_matches('foobarbequebaz', 'ba.', 'g')`	`{bar}` `{baz}` (2 строки)
`regexp_replace(string text, pattern text, замена text [, flags text])`	`text`	Заменяет подстроки, соответствующие заданному регулярному выражению в стиле POSIX. Подробности описаны в Подразделе 9.7.3.	`regexp_replace('Thomas', '.[mN]a.', 'M')`	`ThM`
`regexp_split_to_array(string text, pattern text [, flags text ])`	`text[]`	Разделяет содержимое `string` на элементы, используя в качестве разделителя регулярное выражение POSIX. Подробности описаны в Подразделе 9.7.3.	`regexp_split_to_array('hello world', '\s+')`	`{hello,world}`
`regexp_split_to_table(string text, pattern text [, flags text])`	`setof text`	Разделяет содержимое `string` на элементы, используя в качестве разделителя регулярное выражение POSIX. Подробности описаны в Подразделе 9.7.3.	`regexp_split_to_table('hello world', '\s+')`	`hello` `world` (2 строки)
`repeat(string text, number int)`	`text`	Повторяет содержимое `string` указанное число (`number`) раз	`repeat('Pg', 4)`	`PgPgPgPg`
`replace(string text, from text, to text)`	`text`	Заменяет все вхождения в `string` подстроки `from` подстрокой `to`	`replace('abcdefabcdef', 'cd', 'XX')`	`abXXefabXXef`
`reverse(str)`	`text`	Возвращает перевёрнутую строку	`reverse('abcde')`	`edcba`
`right(str text, n int)`	`text`	Возвращает последние `n` символов в строке. Когда `n` меньше нуля, возвращаются все символы справа, кроме первых \|`n`\|.	`right('abcde', 2)`	`de`
`rpad(string text, length int [, fill text])`	`text`	Дополняет строку `string` справа до длины `length` символами `fill` (по умолчанию пробелами). Если длина строки уже больше заданной, она обрезается.	`rpad('hi', 5, 'xy')`	`hixyx`
`rtrim(string text [, characters text])`	`text`	Удаляет наибольшую подстроку, содержащую только символы `characters` (по умолчанию пробелы), с конца строки `string`	`rtrim('testxxzx', 'xyz')`	`test`
`split_part(string text, delimiter text, field int)`	`text`	Разделяет строку `string` по символу `delimiter` и возвращает элемент по заданному номеру (считая с 1)	`split_part('abc~@~def~@~ghi', '~@~', 2)`	`def`
`strpos(string, substring)`	`int`	Возвращает положение указанной подстроки (подобно `position(substring in string)`, но с другим порядком аргументов)	`strpos('high', 'ig')`	`2`
`substr(string, from [, count])`	`text`	Извлекает подстроку (подобно `substring(string from from for count)`)	`substr('alphabet', 3, 2)`	`ph`
`starts_with(string, prefix)`	`bool`	Возвращает `true`, если строка `string` начинается с подстроки `prefix`.	`starts_with('alphabet', 'alph')`	`t`
`to_ascii(string text [, encoding text])`	`text`	Преобразует `string` в ASCII из кодировки `encoding` (поддерживаются только `LATIN1`, `LATIN2`, `LATIN9` и `WIN1250`)	`to_ascii('Karel')`	`Karel`
`to_hex(number int или bigint)`	`text`	Преобразует число `number` в 16-ричный вид	`to_hex(2147483647)`	`7fffffff`
`translate(string text, from text, to text)`	`text`	Заменяет символы в `string`, найденные в наборе `from`, на соответствующие символы в множестве `to`. Если строка `from` длиннее `to`, найденные в исходной строке лишние символы `from` удаляются.	`translate('12345', '143', 'ax')`	`a2x5`

Функции concat, concat_ws и format принимают переменное число аргументов, так что им для объединения или форматирования можно передавать значения в виде массива, помеченного ключевым словом VARIADIC (см. Подраздел 39.5.5). Элементы такого массива обрабатываются, как если бы они были обычными аргументами функции. Если вместо массива в соответствующем аргументе передаётся NULL, функции concat и concat_ws возвращают NULL, а format воспринимает NULL как массив нулевого размера.

См. также агрегатную функцию string_agg в Разделе 9.20.

Таблица 9.10. Встроенные преобразования

Имя преобразования ^[a]	Исходная кодировка	Целевая кодировка
`ascii_to_mic`	`SQL_ASCII`	`MULE_INTERNAL`
`ascii_to_utf8`	`SQL_ASCII`	`UTF8`
`big5_to_euc_tw`	`BIG5`	`EUC_TW`
`big5_to_mic`	`BIG5`	`MULE_INTERNAL`
`big5_to_utf8`	`BIG5`	`UTF8`
`euc_cn_to_mic`	`EUC_CN`	`MULE_INTERNAL`
`euc_cn_to_utf8`	`EUC_CN`	`UTF8`
`euc_jp_to_mic`	`EUC_JP`	`MULE_INTERNAL`
`euc_jp_to_sjis`	`EUC_JP`	`SJIS`
`euc_jp_to_utf8`	`EUC_JP`	`UTF8`
`euc_kr_to_mic`	`EUC_KR`	`MULE_INTERNAL`
`euc_kr_to_utf8`	`EUC_KR`	`UTF8`
`euc_tw_to_big5`	`EUC_TW`	`BIG5`
`euc_tw_to_mic`	`EUC_TW`	`MULE_INTERNAL`
`euc_tw_to_utf8`	`EUC_TW`	`UTF8`
`gb18030_to_utf8`	`GB18030`	`UTF8`
`gbk_to_utf8`	`GBK`	`UTF8`
`iso_8859_10_to_utf8`	`LATIN6`	`UTF8`
`iso_8859_13_to_utf8`	`LATIN7`	`UTF8`
`iso_8859_14_to_utf8`	`LATIN8`	`UTF8`
`iso_8859_15_to_utf8`	`LATIN9`	`UTF8`
`iso_8859_16_to_utf8`	`LATIN10`	`UTF8`
`iso_8859_1_to_mic`	`LATIN1`	`MULE_INTERNAL`
`iso_8859_1_to_utf8`	`LATIN1`	`UTF8`
`iso_8859_2_to_mic`	`LATIN2`	`MULE_INTERNAL`
`iso_8859_2_to_utf8`	`LATIN2`	`UTF8`
`iso_8859_2_to_windows_1250`	`LATIN2`	`WIN1250`
`iso_8859_3_to_mic`	`LATIN3`	`MULE_INTERNAL`
`iso_8859_3_to_utf8`	`LATIN3`	`UTF8`
`iso_8859_4_to_mic`	`LATIN4`	`MULE_INTERNAL`
`iso_8859_4_to_utf8`	`LATIN4`	`UTF8`
`iso_8859_5_to_koi8_r`	`ISO_8859_5`	`KOI8R`
`iso_8859_5_to_mic`	`ISO_8859_5`	`MULE_INTERNAL`
`iso_8859_5_to_utf8`	`ISO_8859_5`	`UTF8`
`iso_8859_5_to_windows_1251`	`ISO_8859_5`	`WIN1251`
`iso_8859_5_to_windows_866`	`ISO_8859_5`	`WIN866`
`iso_8859_6_to_utf8`	`ISO_8859_6`	`UTF8`
`iso_8859_7_to_utf8`	`ISO_8859_7`	`UTF8`
`iso_8859_8_to_utf8`	`ISO_8859_8`	`UTF8`
`iso_8859_9_to_utf8`	`LATIN5`	`UTF8`
`johab_to_utf8`	`JOHAB`	`UTF8`
`koi8_r_to_iso_8859_5`	`KOI8R`	`ISO_8859_5`
`koi8_r_to_mic`	`KOI8R`	`MULE_INTERNAL`
`koi8_r_to_utf8`	`KOI8R`	`UTF8`
`koi8_r_to_windows_1251`	`KOI8R`	`WIN1251`
`koi8_r_to_windows_866`	`KOI8R`	`WIN866`
`koi8_u_to_utf8`	`KOI8U`	`UTF8`
`mic_to_ascii`	`MULE_INTERNAL`	`SQL_ASCII`
`mic_to_big5`	`MULE_INTERNAL`	`BIG5`
`mic_to_euc_cn`	`MULE_INTERNAL`	`EUC_CN`
`mic_to_euc_jp`	`MULE_INTERNAL`	`EUC_JP`
`mic_to_euc_kr`	`MULE_INTERNAL`	`EUC_KR`
`mic_to_euc_tw`	`MULE_INTERNAL`	`EUC_TW`
`mic_to_iso_8859_1`	`MULE_INTERNAL`	`LATIN1`
`mic_to_iso_8859_2`	`MULE_INTERNAL`	`LATIN2`
`mic_to_iso_8859_3`	`MULE_INTERNAL`	`LATIN3`
`mic_to_iso_8859_4`	`MULE_INTERNAL`	`LATIN4`
`mic_to_iso_8859_5`	`MULE_INTERNAL`	`ISO_8859_5`
`mic_to_koi8_r`	`MULE_INTERNAL`	`KOI8R`
`mic_to_sjis`	`MULE_INTERNAL`	`SJIS`
`mic_to_windows_1250`	`MULE_INTERNAL`	`WIN1250`
`mic_to_windows_1251`	`MULE_INTERNAL`	`WIN1251`
`mic_to_windows_866`	`MULE_INTERNAL`	`WIN866`
`sjis_to_euc_jp`	`SJIS`	`EUC_JP`
`sjis_to_mic`	`SJIS`	`MULE_INTERNAL`
`sjis_to_utf8`	`SJIS`	`UTF8`
`windows_1258_to_utf8`	`WIN1258`	`UTF8`
`uhc_to_utf8`	`UHC`	`UTF8`
`utf8_to_ascii`	`UTF8`	`SQL_ASCII`
`utf8_to_big5`	`UTF8`	`BIG5`
`utf8_to_euc_cn`	`UTF8`	`EUC_CN`
`utf8_to_euc_jp`	`UTF8`	`EUC_JP`
`utf8_to_euc_kr`	`UTF8`	`EUC_KR`
`utf8_to_euc_tw`	`UTF8`	`EUC_TW`
`utf8_to_gb18030`	`UTF8`	`GB18030`
`utf8_to_gbk`	`UTF8`	`GBK`
`utf8_to_iso_8859_1`	`UTF8`	`LATIN1`
`utf8_to_iso_8859_10`	`UTF8`	`LATIN6`
`utf8_to_iso_8859_13`	`UTF8`	`LATIN7`
`utf8_to_iso_8859_14`	`UTF8`	`LATIN8`
`utf8_to_iso_8859_15`	`UTF8`	`LATIN9`
`utf8_to_iso_8859_16`	`UTF8`	`LATIN10`
`utf8_to_iso_8859_2`	`UTF8`	`LATIN2`
`utf8_to_iso_8859_3`	`UTF8`	`LATIN3`
`utf8_to_iso_8859_4`	`UTF8`	`LATIN4`
`utf8_to_iso_8859_5`	`UTF8`	`ISO_8859_5`
`utf8_to_iso_8859_6`	`UTF8`	`ISO_8859_6`
`utf8_to_iso_8859_7`	`UTF8`	`ISO_8859_7`
`utf8_to_iso_8859_8`	`UTF8`	`ISO_8859_8`
`utf8_to_iso_8859_9`	`UTF8`	`LATIN5`
`utf8_to_johab`	`UTF8`	`JOHAB`
`utf8_to_koi8_r`	`UTF8`	`KOI8R`
`utf8_to_koi8_u`	`UTF8`	`KOI8U`
`utf8_to_sjis`	`UTF8`	`SJIS`
`utf8_to_windows_1258`	`UTF8`	`WIN1258`
`utf8_to_uhc`	`UTF8`	`UHC`
`utf8_to_windows_1250`	`UTF8`	`WIN1250`
`utf8_to_windows_1251`	`UTF8`	`WIN1251`
`utf8_to_windows_1252`	`UTF8`	`WIN1252`
`utf8_to_windows_1253`	`UTF8`	`WIN1253`
`utf8_to_windows_1254`	`UTF8`	`WIN1254`
`utf8_to_windows_1255`	`UTF8`	`WIN1255`
`utf8_to_windows_1256`	`UTF8`	`WIN1256`
`utf8_to_windows_1257`	`UTF8`	`WIN1257`
`utf8_to_windows_866`	`UTF8`	`WIN866`
`utf8_to_windows_874`	`UTF8`	`WIN874`
`windows_1250_to_iso_8859_2`	`WIN1250`	`LATIN2`
`windows_1250_to_mic`	`WIN1250`	`MULE_INTERNAL`
`windows_1250_to_utf8`	`WIN1250`	`UTF8`
`windows_1251_to_iso_8859_5`	`WIN1251`	`ISO_8859_5`
`windows_1251_to_koi8_r`	`WIN1251`	`KOI8R`
`windows_1251_to_mic`	`WIN1251`	`MULE_INTERNAL`
`windows_1251_to_utf8`	`WIN1251`	`UTF8`
`windows_1251_to_windows_866`	`WIN1251`	`WIN866`
`windows_1252_to_utf8`	`WIN1252`	`UTF8`
`windows_1256_to_utf8`	`WIN1256`	`UTF8`
`windows_866_to_iso_8859_5`	`WIN866`	`ISO_8859_5`
`windows_866_to_koi8_r`	`WIN866`	`KOI8R`
`windows_866_to_mic`	`WIN866`	`MULE_INTERNAL`
`windows_866_to_utf8`	`WIN866`	`UTF8`
`windows_866_to_windows_1251`	`WIN866`	`WIN`
`windows_874_to_utf8`	`WIN874`	`UTF8`
`euc_jis_2004_to_utf8`	`EUC_JIS_2004`	`UTF8`
`utf8_to_euc_jis_2004`	`UTF8`	`EUC_JIS_2004`
`shift_jis_2004_to_utf8`	`SHIFT_JIS_2004`	`UTF8`
`utf8_to_shift_jis_2004`	`UTF8`	`SHIFT_JIS_2004`
`euc_jis_2004_to_shift_jis_2004`	`EUC_JIS_2004`	`SHIFT_JIS_2004`
`shift_jis_2004_to_euc_jis_2004`	`SHIFT_JIS_2004`	`EUC_JIS_2004`
^[a]Имена преобразований следуют стандартной схеме именования. К официальному названию исходной кодировки, в котором все не алфавитно-цифровые символы заменяются подчёркиваниями, добавляется `_to_`, а за ним аналогично подготовленное имя целевой кодировки. Таким образом, имена кодировок могут не совпадать буквально с общепринятыми названиями.

9.4.1. `format`

Функция format выдаёт текст, отформатированный в соответствии со строкой формата, подобно функции sprintf в C.

format(formatstr text [, formatarg "any" [, ...] ])

formatstr — строка, определяющая, как будет форматироваться результат. Обычный текст в строке формата непосредственно копируется в результат, за исключением спецификаторов формата. Спецификаторы формата представляют собой местозаполнители, определяющие, как должны форматироваться и выводиться в результате аргументы функции. Каждый аргумент formatarg преобразуется в текст по правилам выводам своего типа данных, а затем форматируется и вставляется в результирующую строку согласно спецификаторам формата.

Спецификаторы формата предваряются символом % и имеют форму

%[позиция][флаги][ширина]тип

Здесь:

позиция (необязателен)

Строка вида n$, где n — индекс выводимого аргумента. Индекс, равный 1, выбирает первый аргумент после formatstr. Если позиция опускается, по умолчанию используется следующий аргумент по порядку.

флаги (необязателен)

Дополнительные параметры, управляющие форматированием данного спецификатора. В настоящее время поддерживается только знак минус (-), который выравнивает результата спецификатора по левому краю. Он работает, только если также определена ширина.

ширина (необязателен)

Задаёт минимальное число символов, которое будет занимать результат данного спецификатора. Выводимое значение выравнивается по правой или левой стороне (в зависимости от флага -) с дополнением необходимым числом пробелов. Если ширина слишком мала, она просто игнорируется, т. е. результат не усекается. Ширину можно обозначить положительным целым, звёздочкой (*), тогда ширина будет получена из следующего аргумента функции, или строкой вида *n$, тогда ширина будет задаваться в n-ом аргументе функции.

Если ширина передаётся в аргументе функции, этот аргумент выбирается до аргумента, используемого для спецификатора. Если аргумент ширины отрицательный, результат выравнивается по левой стороне (как если бы был указан флаг -) в рамках поля длины abs(ширина).

тип (обязателен)

Тип спецификатора определяет преобразование соответствующего выводимого значения. Поддерживаются следующие типы:

s форматирует значение аргумента как простую строку. Значение NULL представляется пустой строкой.
I обрабатывает значение аргумента как SQL-идентификатор, при необходимости заключая его в кавычки. Значение NULL для такого преобразования считается ошибочным (так же, как и для quote_ident).
L заключает значение аргумента в апострофы, как строку SQL. Значение NULL выводится буквально, как NULL, без кавычек (так же, как и с quote_nullable).

В дополнение к спецификаторам, описанным выше, можно использовать спецпоследовательность %%, которая просто выведет символ %.

Несколько примеров простых преобразований формата:

SELECT format('Hello %s', 'World');
Результат: Hello World

SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three');
Результат: Testing one, two, three, %

SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly');
Результат: INSERT INTO "Foo bar" VALUES('O''Reilly')

SELECT format('INSERT INTO %I VALUES(%L)', 'locations', 'C:\Program Files');
Результат: INSERT INTO locations VALUES('C:\Program Files')

Следующие примеры иллюстрируют использование поля ширина и флага -:

SELECT format('|%10s|', 'foo');
Результат: |       foo|

SELECT format('|%-10s|', 'foo');
Результат: |foo       |

SELECT format('|%*s|', 10, 'foo');
Результат: |       foo|

SELECT format('|%*s|', -10, 'foo');
Результат: |foo       |

SELECT format('|%-*s|', 10, 'foo');
Результат: |foo       |

SELECT format('|%-*s|', -10, 'foo');
Результат: |foo       |

Эти примеры показывают применение полей позиция:

SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
Результат: Testing three, two, one

SELECT format('|%*2$s|', 'foo', 10, 'bar');
Результат: |       bar|

SELECT format('|%1$*2$s|', 'foo', 10, 'bar');
Результат: |       foo|

В отличие от стандартной функции C sprintf, функция format в Postgres Pro позволяет комбинировать в одной строке спецификаторы с полями позиция и без них. Спецификатор формата без поля позиция всегда использует следующий аргумент после последнего выбранного. Кроме того, функция format не требует, чтобы в строке формата использовались все аргументы функции. Пример этого поведения:

SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
Результат: Testing three, two, three

Спецификаторы формата %I и %L особенно полезны для безопасного составления динамических операторов SQL. См. Пример 44.1.

Пред.	Наверх	След.
9.3. Математические функции и операторы	Начало	9.5. Функции и операторы двоичных строк

9.4. String Functions and Operators
Prev	Up	Chapter 9. Functions and Operators	Home	Next

9.4. String Functions and Operators

9.4.1. format

This section describes functions and operators for examining and manipulating string values. Strings in this context include values of the types character, character varying, and text. Unless otherwise noted, all of the functions listed below work on all of these types, but be wary of potential effects of automatic space-padding when using the character type. Some functions also exist natively for the bit-string types.

SQL defines some string functions that use key words, rather than commas, to separate arguments. Details are in Table 9.8. Postgres Pro also provides versions of these functions that use the regular function invocation syntax (see Table 9.9).

Note

Before PostgreSQL 8.3, these functions would silently accept values of several non-string data types as well, due to the presence of implicit coercions from those data types to text. Those coercions have been removed because they frequently caused surprising behaviors. However, the string concatenation operator (||) still accepts non-string input, so long as at least one input is of a string type, as shown in Table 9.8. For other cases, insert an explicit coercion to text if you need to duplicate the previous behavior.

Table 9.8. SQL String Functions and Operators

Function	Return Type	Description	Example	Result
`string \|\| string`	`text`	String concatenation	`'Post' \|\| 'greSQL'`	`PostgreSQL`
`string \|\| non-string` or `non-string \|\| string`	`text`	String concatenation with one non-string input	`'Value: ' \|\| 42`	`Value: 42`
`bit_length(string)`	`int`	Number of bits in string	`bit_length('jose')`	`32`
`char_length(string)` or `character_length(string)`	`int`	Number of characters in string	`char_length('jose')`	`4`
`lower(string)`	`text`	Convert string to lower case	`lower('TOM')`	`tom`
`octet_length(string)`	`int`	Number of bytes in string	`octet_length('jose')`	`4`
`overlay(string placing string from int [for int])`	`text`	Replace substring	`overlay('Txxxxas' placing 'hom' from 2 for 4)`	`Thomas`
`position(substring in string)`	`int`	Location of specified substring	`position('om' in 'Thomas')`	`3`
`substring(string [from int] [for int])`	`text`	Extract substring	`substring('Thomas' from 2 for 3)`	`hom`
`substring(string from pattern)`	`text`	Extract substring matching POSIX regular expression. See Section 9.7 for more information on pattern matching.	`substring('Thomas' from '...$')`	`mas`
`substring(string from pattern for escape)`	`text`	Extract substring matching SQL regular expression. See Section 9.7 for more information on pattern matching.	`substring('Thomas' from '%#"o_a#"_' for '#')`	`oma`
`trim([leading \| trailing \| both] [characters] from string)`	`text`	Remove the longest string containing only characters from `characters` (a space by default) from the start, end, or both ends (`both` is the default) of `string`	`trim(both 'xyz' from 'yxTomxx')`	`Tom`
`trim([leading \| trailing \| both] [from] string [, characters] )`	`text`	Non-standard syntax for `trim()`	`trim(both from 'yxTomxx', 'xyz')`	`Tom`
`upper(string)`	`text`	Convert string to upper case	`upper('tom')`	`TOM`

Additional string manipulation functions are available and are listed in Table 9.9. Some of them are used internally to implement the SQL-standard string functions listed in Table 9.8.

Table 9.9. Other String Functions

Function	Return Type	Description	Example	Result
`ascii(string)`	`int`	ASCII code of the first character of the argument. For UTF8 returns the Unicode code point of the character. For other multibyte encodings, the argument must be an ASCII character.	`ascii('x')`	`120`
`btrim(string text [, characters text])`	`text`	Remove the longest string consisting only of characters in `characters` (a space by default) from the start and end of `string`	`btrim('xyxtrimyyx', 'xyz')`	`trim`
`chr(int)`	`text`	Character with the given code. For UTF8 the argument is treated as a Unicode code point. For other multibyte encodings the argument must designate an ASCII character. The NULL (0) character is not allowed because text data types cannot store such bytes.	`chr(65)`	`A`
`concat(str "any" [, str "any" [, ...] ])`	`text`	Concatenate the text representations of all the arguments. NULL arguments are ignored.	`concat('abcde', 2, NULL, 22)`	`abcde222`
`concat_ws(sep text, str "any" [, str "any" [, ...] ])`	`text`	Concatenate all but the first argument with separators. The first argument is used as the separator string. NULL arguments are ignored.	`concat_ws(',', 'abcde', 2, NULL, 22)`	`abcde,2,22`
`convert(string bytea, src_encoding name, dest_encoding name)`	`bytea`	Convert string to `dest_encoding`. The original encoding is specified by `src_encoding`. The `string` must be valid in this encoding. Conversions can be defined by `CREATE CONVERSION`. Also there are some predefined conversions. See Table 9.10 for available conversions.	`convert('text_in_utf8', 'UTF8', 'LATIN1')`	`text_in_utf8` represented in Latin-1 encoding (ISO 8859-1)
`convert_from(string bytea, src_encoding name)`	`text`	Convert string to the database encoding. The original encoding is specified by `src_encoding`. The `string` must be valid in this encoding.	`convert_from('text_in_utf8', 'UTF8')`	`text_in_utf8` represented in the current database encoding
`convert_to(string text, dest_encoding name)`	`bytea`	Convert string to `dest_encoding`.	`convert_to('some text', 'UTF8')`	`some text` represented in the UTF8 encoding
`decode(string text, format text)`	`bytea`	Decode binary data from textual representation in `string`. Options for `format` are same as in `encode`.	`decode('MTIzAAE=', 'base64')`	`\x3132330001`
`encode(data bytea, format text)`	`text`	Encode binary data into a textual representation. Supported formats are: `base64`, `hex`, `escape`. `escape` converts zero bytes and high-bit-set bytes to octal sequences (`\``nnn`) and doubles backslashes.	`encode('123\000\001', 'base64')`	`MTIzAAE=`
`format(formatstr text [, formatarg "any" [, ...] ])`	`text`	Format arguments according to a format string. This function is similar to the C function `sprintf`. See Section 9.4.1.	`format('Hello %s, %1$s', 'World')`	`Hello World, World`
`initcap(string)`	`text`	Convert the first letter of each word to upper case and the rest to lower case. Words are sequences of alphanumeric characters separated by non-alphanumeric characters.	`initcap('hi THOMAS')`	`Hi Thomas`
`left(str text, n int)`	`text`	Return first `n` characters in the string. When `n` is negative, return all but last \|`n`\| characters.	`left('abcde', 2)`	`ab`
`length(string)`	`int`	Number of characters in `string`	`length('jose')`	`4`
`length(string bytea, encoding name )`	`int`	Number of characters in `string` in the given `encoding`. The `string` must be valid in this encoding.	`length('jose', 'UTF8')`	`4`
`lpad(string text, length int [, fill text])`	`text`	Fill up the `string` to length `length` by prepending the characters `fill` (a space by default). If the `string` is already longer than `length` then it is truncated (on the right).	`lpad('hi', 5, 'xy')`	`xyxhi`
`ltrim(string text [, characters text])`	`text`	Remove the longest string containing only characters from `characters` (a space by default) from the start of `string`	`ltrim('zzzytest', 'xyz')`	`test`
`md5(string)`	`text`	Calculates the MD5 hash of `string`, returning the result in hexadecimal	`md5('abc')`	`900150983cd24fb0 d6963f7d28e17f72`
`parse_ident(qualified_identifier text [, strictmode boolean DEFAULT true ] )`	`text[]`	Split `qualified_identifier` into an array of identifiers, removing any quoting of individual identifiers. By default, extra characters after the last identifier are considered an error; but if the second parameter is `false`, then such extra characters are ignored. (This behavior is useful for parsing names for objects like functions.) Note that this function does not truncate over-length identifiers. If you want truncation you can cast the result to `name[]`.	`parse_ident('"SomeSchema".someTable')`	`{SomeSchema,sometable}`
`pg_client_encoding()`	`name`	Current client encoding name	`pg_client_encoding()`	`SQL_ASCII`
`quote_ident(string text)`	`text`	Return the given string suitably quoted to be used as an identifier in an SQL statement string. Quotes are added only if necessary (i.e., if the string contains non-identifier characters or would be case-folded). Embedded quotes are properly doubled. See also Example 44.1.	`quote_ident('Foo bar')`	`"Foo bar"`
`quote_literal(string text)`	`text`	Return the given string suitably quoted to be used as a string literal in an SQL statement string. Embedded single-quotes and backslashes are properly doubled. Note that `quote_literal` returns null on null input; if the argument might be null, `quote_nullable` is often more suitable. See also Example 44.1.	`quote_literal(E'O\'Reilly')`	`'O''Reilly'`
`quote_literal(value anyelement)`	`text`	Coerce the given value to text and then quote it as a literal. Embedded single-quotes and backslashes are properly doubled.	`quote_literal(42.5)`	`'42.5'`
`quote_nullable(string text)`	`text`	Return the given string suitably quoted to be used as a string literal in an SQL statement string; or, if the argument is null, return `NULL`. Embedded single-quotes and backslashes are properly doubled. See also Example 44.1.	`quote_nullable(NULL)`	`NULL`
`quote_nullable(value anyelement)`	`text`	Coerce the given value to text and then quote it as a literal; or, if the argument is null, return `NULL`. Embedded single-quotes and backslashes are properly doubled.	`quote_nullable(42.5)`	`'42.5'`
`regexp_match(string text, pattern text [, flags text])`	`text[]`	Return captured substring(s) resulting from the first match of a POSIX regular expression to the `string`. See Section 9.7.3 for more information.	`regexp_match('foobarbequebaz', '(bar)(beque)')`	`{bar,beque}`
`regexp_matches(string text, pattern text [, flags text])`	`setof text[]`	Return captured substring(s) resulting from matching a POSIX regular expression to the `string`. See Section 9.7.3 for more information.	`regexp_matches('foobarbequebaz', 'ba.', 'g')`	`{bar}` `{baz}` (2 rows)
`regexp_replace(string text, pattern text, replacement text [, flags text])`	`text`	Replace substring(s) matching a POSIX regular expression. See Section 9.7.3 for more information.	`regexp_replace('Thomas', '.[mN]a.', 'M')`	`ThM`
`regexp_split_to_array(string text, pattern text [, flags text ])`	`text[]`	Split `string` using a POSIX regular expression as the delimiter. See Section 9.7.3 for more information.	`regexp_split_to_array('hello world', '\s+')`	`{hello,world}`
`regexp_split_to_table(string text, pattern text [, flags text])`	`setof text`	Split `string` using a POSIX regular expression as the delimiter. See Section 9.7.3 for more information.	`regexp_split_to_table('hello world', '\s+')`	`hello` `world` (2 rows)
`repeat(string text, number int)`	`text`	Repeat `string` the specified `number` of times	`repeat('Pg', 4)`	`PgPgPgPg`
`replace(string text, from text, to text)`	`text`	Replace all occurrences in `string` of substring `from` with substring `to`	`replace('abcdefabcdef', 'cd', 'XX')`	`abXXefabXXef`
`reverse(str)`	`text`	Return reversed string.	`reverse('abcde')`	`edcba`
`right(str text, n int)`	`text`	Return last `n` characters in the string. When `n` is negative, return all but first \|`n`\| characters.	`right('abcde', 2)`	`de`
`rpad(string text, length int [, fill text])`	`text`	Fill up the `string` to length `length` by appending the characters `fill` (a space by default). If the `string` is already longer than `length` then it is truncated.	`rpad('hi', 5, 'xy')`	`hixyx`
`rtrim(string text [, characters text])`	`text`	Remove the longest string containing only characters from `characters` (a space by default) from the end of `string`	`rtrim('testxxzx', 'xyz')`	`test`
`split_part(string text, delimiter text, field int)`	`text`	Split `string` on `delimiter` and return the given field (counting from one)	`split_part('abc~@~def~@~ghi', '~@~', 2)`	`def`
`strpos(string, substring)`	`int`	Location of specified substring (same as `position(substring in string)`, but note the reversed argument order)	`strpos('high', 'ig')`	`2`
`substr(string, from [, count])`	`text`	Extract substring (same as `substring(string from from for count)`)	`substr('alphabet', 3, 2)`	`ph`
`starts_with(string, prefix)`	`bool`	Returns true if `string` starts with `prefix`.	`starts_with('alphabet', 'alph')`	`t`
`to_ascii(string text [, encoding text])`	`text`	Convert `string` to ASCII from another encoding (only supports conversion from `LATIN1`, `LATIN2`, `LATIN9`, and `WIN1250` encodings)	`to_ascii('Karel')`	`Karel`
`to_hex(number int or bigint)`	`text`	Convert `number` to its equivalent hexadecimal representation	`to_hex(2147483647)`	`7fffffff`
`translate(string text, from text, to text)`	`text`	Any character in `string` that matches a character in the `from` set is replaced by the corresponding character in the `to` set. If `from` is longer than `to`, occurrences of the extra characters in `from` are removed.	`translate('12345', '143', 'ax')`	`a2x5`

The concat, concat_ws and format functions are variadic, so it is possible to pass the values to be concatenated or formatted as an array marked with the VARIADIC keyword (see Section 39.5.5). The array's elements are treated as if they were separate ordinary arguments to the function. If the variadic array argument is NULL, concat and concat_ws return NULL, but format treats a NULL as a zero-element array.

See also the aggregate function string_agg in Section 9.20.

Table 9.10. Built-in Conversions

Conversion Name ^[a]	Source Encoding	Destination Encoding
`ascii_to_mic`	`SQL_ASCII`	`MULE_INTERNAL`
`ascii_to_utf8`	`SQL_ASCII`	`UTF8`
`big5_to_euc_tw`	`BIG5`	`EUC_TW`
`big5_to_mic`	`BIG5`	`MULE_INTERNAL`
`big5_to_utf8`	`BIG5`	`UTF8`
`euc_cn_to_mic`	`EUC_CN`	`MULE_INTERNAL`
`euc_cn_to_utf8`	`EUC_CN`	`UTF8`
`euc_jp_to_mic`	`EUC_JP`	`MULE_INTERNAL`
`euc_jp_to_sjis`	`EUC_JP`	`SJIS`
`euc_jp_to_utf8`	`EUC_JP`	`UTF8`
`euc_kr_to_mic`	`EUC_KR`	`MULE_INTERNAL`
`euc_kr_to_utf8`	`EUC_KR`	`UTF8`
`euc_tw_to_big5`	`EUC_TW`	`BIG5`
`euc_tw_to_mic`	`EUC_TW`	`MULE_INTERNAL`
`euc_tw_to_utf8`	`EUC_TW`	`UTF8`
`gb18030_to_utf8`	`GB18030`	`UTF8`
`gbk_to_utf8`	`GBK`	`UTF8`
`iso_8859_10_to_utf8`	`LATIN6`	`UTF8`
`iso_8859_13_to_utf8`	`LATIN7`	`UTF8`
`iso_8859_14_to_utf8`	`LATIN8`	`UTF8`
`iso_8859_15_to_utf8`	`LATIN9`	`UTF8`
`iso_8859_16_to_utf8`	`LATIN10`	`UTF8`
`iso_8859_1_to_mic`	`LATIN1`	`MULE_INTERNAL`
`iso_8859_1_to_utf8`	`LATIN1`	`UTF8`
`iso_8859_2_to_mic`	`LATIN2`	`MULE_INTERNAL`
`iso_8859_2_to_utf8`	`LATIN2`	`UTF8`
`iso_8859_2_to_windows_1250`	`LATIN2`	`WIN1250`
`iso_8859_3_to_mic`	`LATIN3`	`MULE_INTERNAL`
`iso_8859_3_to_utf8`	`LATIN3`	`UTF8`
`iso_8859_4_to_mic`	`LATIN4`	`MULE_INTERNAL`
`iso_8859_4_to_utf8`	`LATIN4`	`UTF8`
`iso_8859_5_to_koi8_r`	`ISO_8859_5`	`KOI8R`
`iso_8859_5_to_mic`	`ISO_8859_5`	`MULE_INTERNAL`
`iso_8859_5_to_utf8`	`ISO_8859_5`	`UTF8`
`iso_8859_5_to_windows_1251`	`ISO_8859_5`	`WIN1251`
`iso_8859_5_to_windows_866`	`ISO_8859_5`	`WIN866`
`iso_8859_6_to_utf8`	`ISO_8859_6`	`UTF8`
`iso_8859_7_to_utf8`	`ISO_8859_7`	`UTF8`
`iso_8859_8_to_utf8`	`ISO_8859_8`	`UTF8`
`iso_8859_9_to_utf8`	`LATIN5`	`UTF8`
`johab_to_utf8`	`JOHAB`	`UTF8`
`koi8_r_to_iso_8859_5`	`KOI8R`	`ISO_8859_5`
`koi8_r_to_mic`	`KOI8R`	`MULE_INTERNAL`
`koi8_r_to_utf8`	`KOI8R`	`UTF8`
`koi8_r_to_windows_1251`	`KOI8R`	`WIN1251`
`koi8_r_to_windows_866`	`KOI8R`	`WIN866`
`koi8_u_to_utf8`	`KOI8U`	`UTF8`
`mic_to_ascii`	`MULE_INTERNAL`	`SQL_ASCII`
`mic_to_big5`	`MULE_INTERNAL`	`BIG5`
`mic_to_euc_cn`	`MULE_INTERNAL`	`EUC_CN`
`mic_to_euc_jp`	`MULE_INTERNAL`	`EUC_JP`
`mic_to_euc_kr`	`MULE_INTERNAL`	`EUC_KR`
`mic_to_euc_tw`	`MULE_INTERNAL`	`EUC_TW`
`mic_to_iso_8859_1`	`MULE_INTERNAL`	`LATIN1`
`mic_to_iso_8859_2`	`MULE_INTERNAL`	`LATIN2`
`mic_to_iso_8859_3`	`MULE_INTERNAL`	`LATIN3`
`mic_to_iso_8859_4`	`MULE_INTERNAL`	`LATIN4`
`mic_to_iso_8859_5`	`MULE_INTERNAL`	`ISO_8859_5`
`mic_to_koi8_r`	`MULE_INTERNAL`	`KOI8R`
`mic_to_sjis`	`MULE_INTERNAL`	`SJIS`
`mic_to_windows_1250`	`MULE_INTERNAL`	`WIN1250`
`mic_to_windows_1251`	`MULE_INTERNAL`	`WIN1251`
`mic_to_windows_866`	`MULE_INTERNAL`	`WIN866`
`sjis_to_euc_jp`	`SJIS`	`EUC_JP`
`sjis_to_mic`	`SJIS`	`MULE_INTERNAL`
`sjis_to_utf8`	`SJIS`	`UTF8`
`windows_1258_to_utf8`	`WIN1258`	`UTF8`
`uhc_to_utf8`	`UHC`	`UTF8`
`utf8_to_ascii`	`UTF8`	`SQL_ASCII`
`utf8_to_big5`	`UTF8`	`BIG5`
`utf8_to_euc_cn`	`UTF8`	`EUC_CN`
`utf8_to_euc_jp`	`UTF8`	`EUC_JP`
`utf8_to_euc_kr`	`UTF8`	`EUC_KR`
`utf8_to_euc_tw`	`UTF8`	`EUC_TW`
`utf8_to_gb18030`	`UTF8`	`GB18030`
`utf8_to_gbk`	`UTF8`	`GBK`
`utf8_to_iso_8859_1`	`UTF8`	`LATIN1`
`utf8_to_iso_8859_10`	`UTF8`	`LATIN6`
`utf8_to_iso_8859_13`	`UTF8`	`LATIN7`
`utf8_to_iso_8859_14`	`UTF8`	`LATIN8`
`utf8_to_iso_8859_15`	`UTF8`	`LATIN9`
`utf8_to_iso_8859_16`	`UTF8`	`LATIN10`
`utf8_to_iso_8859_2`	`UTF8`	`LATIN2`
`utf8_to_iso_8859_3`	`UTF8`	`LATIN3`
`utf8_to_iso_8859_4`	`UTF8`	`LATIN4`
`utf8_to_iso_8859_5`	`UTF8`	`ISO_8859_5`
`utf8_to_iso_8859_6`	`UTF8`	`ISO_8859_6`
`utf8_to_iso_8859_7`	`UTF8`	`ISO_8859_7`
`utf8_to_iso_8859_8`	`UTF8`	`ISO_8859_8`
`utf8_to_iso_8859_9`	`UTF8`	`LATIN5`
`utf8_to_johab`	`UTF8`	`JOHAB`
`utf8_to_koi8_r`	`UTF8`	`KOI8R`
`utf8_to_koi8_u`	`UTF8`	`KOI8U`
`utf8_to_sjis`	`UTF8`	`SJIS`
`utf8_to_windows_1258`	`UTF8`	`WIN1258`
`utf8_to_uhc`	`UTF8`	`UHC`
`utf8_to_windows_1250`	`UTF8`	`WIN1250`
`utf8_to_windows_1251`	`UTF8`	`WIN1251`
`utf8_to_windows_1252`	`UTF8`	`WIN1252`
`utf8_to_windows_1253`	`UTF8`	`WIN1253`
`utf8_to_windows_1254`	`UTF8`	`WIN1254`
`utf8_to_windows_1255`	`UTF8`	`WIN1255`
`utf8_to_windows_1256`	`UTF8`	`WIN1256`
`utf8_to_windows_1257`	`UTF8`	`WIN1257`
`utf8_to_windows_866`	`UTF8`	`WIN866`
`utf8_to_windows_874`	`UTF8`	`WIN874`
`windows_1250_to_iso_8859_2`	`WIN1250`	`LATIN2`
`windows_1250_to_mic`	`WIN1250`	`MULE_INTERNAL`
`windows_1250_to_utf8`	`WIN1250`	`UTF8`
`windows_1251_to_iso_8859_5`	`WIN1251`	`ISO_8859_5`
`windows_1251_to_koi8_r`	`WIN1251`	`KOI8R`
`windows_1251_to_mic`	`WIN1251`	`MULE_INTERNAL`
`windows_1251_to_utf8`	`WIN1251`	`UTF8`
`windows_1251_to_windows_866`	`WIN1251`	`WIN866`
`windows_1252_to_utf8`	`WIN1252`	`UTF8`
`windows_1256_to_utf8`	`WIN1256`	`UTF8`
`windows_866_to_iso_8859_5`	`WIN866`	`ISO_8859_5`
`windows_866_to_koi8_r`	`WIN866`	`KOI8R`
`windows_866_to_mic`	`WIN866`	`MULE_INTERNAL`
`windows_866_to_utf8`	`WIN866`	`UTF8`
`windows_866_to_windows_1251`	`WIN866`	`WIN`
`windows_874_to_utf8`	`WIN874`	`UTF8`
`euc_jis_2004_to_utf8`	`EUC_JIS_2004`	`UTF8`
`utf8_to_euc_jis_2004`	`UTF8`	`EUC_JIS_2004`
`shift_jis_2004_to_utf8`	`SHIFT_JIS_2004`	`UTF8`
`utf8_to_shift_jis_2004`	`UTF8`	`SHIFT_JIS_2004`
`euc_jis_2004_to_shift_jis_2004`	`EUC_JIS_2004`	`SHIFT_JIS_2004`
`shift_jis_2004_to_euc_jis_2004`	`SHIFT_JIS_2004`	`EUC_JIS_2004`
^[a] The conversion names follow a standard naming scheme: The official name of the source encoding with all non-alphanumeric characters replaced by underscores, followed by `_to_`, followed by the similarly processed destination encoding name. Therefore, the names might deviate from the customary encoding names.

9.4.1. `format`

The function format produces output formatted according to a format string, in a style similar to the C function sprintf.

format(formatstr text [, formatarg "any" [, ...] ])

formatstr is a format string that specifies how the result should be formatted. Text in the format string is copied directly to the result, except where format specifiers are used. Format specifiers act as placeholders in the string, defining how subsequent function arguments should be formatted and inserted into the result. Each formatarg argument is converted to text according to the usual output rules for its data type, and then formatted and inserted into the result string according to the format specifier(s).

Format specifiers are introduced by a % character and have the form

%[position][flags][width]type

where the component fields are:

position (optional)

A string of the form n$ where n is the index of the argument to print. Index 1 means the first argument after formatstr. If the position is omitted, the default is to use the next argument in sequence.

flags (optional)

Additional options controlling how the format specifier's output is formatted. Currently the only supported flag is a minus sign (-) which will cause the format specifier's output to be left-justified. This has no effect unless the width field is also specified.

width (optional)

Specifies the minimum number of characters to use to display the format specifier's output. The output is padded on the left or right (depending on the - flag) with spaces as needed to fill the width. A too-small width does not cause truncation of the output, but is simply ignored. The width may be specified using any of the following: a positive integer; an asterisk (*) to use the next function argument as the width; or a string of the form *n$ to use the nth function argument as the width.

If the width comes from a function argument, that argument is consumed before the argument that is used for the format specifier's value. If the width argument is negative, the result is left aligned (as if the - flag had been specified) within a field of length abs(width).

type (required)

The type of format conversion to use to produce the format specifier's output. The following types are supported:

s formats the argument value as a simple string. A null value is treated as an empty string.
I treats the argument value as an SQL identifier, double-quoting it if necessary. It is an error for the value to be null (equivalent to quote_ident).
L quotes the argument value as an SQL literal. A null value is displayed as the string NULL, without quotes (equivalent to quote_nullable).

In addition to the format specifiers described above, the special sequence %% may be used to output a literal % character.

Here are some examples of the basic format conversions:

SELECT format('Hello %s', 'World');
Result: Hello World

SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three');
Result: Testing one, two, three, %

SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly');
Result: INSERT INTO "Foo bar" VALUES('O''Reilly')

SELECT format('INSERT INTO %I VALUES(%L)', 'locations', 'C:\Program Files');
Result: INSERT INTO locations VALUES('C:\Program Files')

Here are examples using width fields and the - flag:

SELECT format('|%10s|', 'foo');
Result: |       foo|

SELECT format('|%-10s|', 'foo');
Result: |foo       |

SELECT format('|%*s|', 10, 'foo');
Result: |       foo|

SELECT format('|%*s|', -10, 'foo');
Result: |foo       |

SELECT format('|%-*s|', 10, 'foo');
Result: |foo       |

SELECT format('|%-*s|', -10, 'foo');
Result: |foo       |

These examples show use of position fields:

SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
Result: Testing three, two, one

SELECT format('|%*2$s|', 'foo', 10, 'bar');
Result: |       bar|

SELECT format('|%1$*2$s|', 'foo', 10, 'bar');
Result: |       foo|

Unlike the standard C function sprintf, Postgres Pro's format function allows format specifiers with and without position fields to be mixed in the same format string. A format specifier without a position field always uses the next argument after the last argument consumed. In addition, the format function does not require all function arguments to be used in the format string. For example:

SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
Result: Testing three, two, three

The %I and %L format specifiers are particularly useful for safely constructing dynamic SQL statements. See Example 44.1.

Prev	Up	Next
9.3. Mathematical Functions and Operators	Home	9.5. Binary String Functions and Operators

9.4. Строковые функции и операторы

Примечание

9.4.1. format

9.4. String Functions and Operators

Note

9.4.1. format

9.4.1. `format`

9.4.1. `format`