9.4. Строковые функции и операторы
В этом разделе описаны функции и операторы для работы с текстовыми строками. Под строками в данном контексте подразумеваются значения типов character, character varying и text. Если не отмечено обратное, эти функции и операторы принимают и возвращают тип text. С тем же успехом в аргументах может передаваться тип character varying. Аргументы же типа character до вызова оператора или функции приводятся к типу text, вследствие чего завершающие пробелы в значении character будут обрезаться.
В SQL определены несколько строковых функций, в которых аргументы разделяются не запятыми, а ключевыми словами. Они перечислены в Таблице 9.9. Postgres Pro также предоставляет варианты этих функций с синтаксисом, обычным для функций (см. Таблицу 9.10).
Примечание
До версии 8.3 в PostgreSQL эти функции также прозрачно принимали значения некоторых не строковых типов, неявно приводя эти значения к типу text. Сейчас такие приведения исключены, так как они часто приводили к неожиданным результатам. Однако оператор конкатенации строк (||) по-прежнему принимает не только строковые данные, если хотя бы один аргумент имеет строковый тип, как показано в Таблице 9.9. Во всех остальных случаях для повторения предыдущего поведения потребуется добавить явное преобразование в text.
Таблица 9.9. Строковые функции и операторы языка SQL
Функция/оператор Описание Пример(ы) |
|---|
Соединяет две строки.
|
Преобразует нестроковый аргумент в текст, а затем соединяет две строки. (Нестроковый аргумент не должен быть массивом, иначе возникает неоднозначность с операторами массивов
|
Проверяет, соответствует ли строка определённой форме нормализации Юникода. Форма указывается в необязательном ключевом слове
|
Возвращает число бит в строке (это число в 8 раз больше
|
Возвращает число символов в строке.
|
Переводит символы строки в нижний регистр в соответствии с правилами локали базы данных.
|
Переводит строку в заданную форму нормализации Unicode. Форма указывается в необязательном ключевом слове
|
Возвращает число байт в строке.
|
Возвращает число байт в строке. Так как эта вариация функции принимает непосредственно тип
|
Заменяет подстроку в
|
Возвращает начальную позицию первого вхождения
|
Извлекает из
|
Извлекает первую подстроку, соответствующую регулярному выражению в стиле POSIX; см. Подраздел 9.7.3.
|
Извлекает первую подстроку, соответствующую регулярному выражению в стиле SQL; см. Подраздел 9.7.2.
|
Удаляет наибольшую подстроку, содержащую только символы
|
Это нестандартный синтаксис вызова
|
Переводит символы строки в верхний регистр, в соответствии с правилами локали базы данных.
|
Кроме этого, в PostgreSQL есть и другие функции для работы со строками, перечисленные в Таблице 9.10. Некоторые из них используются в качестве внутренней реализации стандартных строковых функций SQL, приведённых в Таблице 9.9.
Таблица 9.10. Другие строковые функции
Функция Описание Пример(ы) |
|---|
Возвращает числовой код первого символа аргумента. Для UTF8 возвращает код символа в Unicode. Для других многобайтных кодировок аргумент должен быть ASCII-символом.
|
Удаляет наибольшую подстроку, содержащую только символы
|
Возвращает символ с данным кодом. Для UTF8 аргумент воспринимается как код символа Unicode, а для других кодировок он должен указывать на ASCII-символ. Эта функция не может выдать
|
Соединяет текстовые представления всех аргументов, игнорируя NULL.
|
Соединяет вместе все аргументы, кроме первого, через разделитель. Разделитель задаётся в первом аргументе и должен быть отличен от NULL. В других аргументах значение NULL игнорируется.
|
Форматирует аргументы в соответствии со строкой формата; см. Подраздел 9.4.1. Эта функция работает подобно
|
Переводит первую букву каждого слова в строке в верхний регистр, а остальные — в нижний. Словами считаются последовательности алфавитно-цифровых символов, разделённые любыми другими символами.
|
Возвращает первые
|
Возвращает число символов в строке.
|
Дополняет строку
|
Удаляет наибольшую подстроку, содержащую только символы
|
Вычисляет MD5-хеш аргумента и выдаёт результат в шестнадцатеричном виде.
|
Раскладывает полный идентификатор, задаваемый параметром
|
Возвращает имя текущей клиентской кодировки.
|
Преобразует аргумент в строку, подходящую для использования в качестве идентификатора в SQL-операторе. При необходимости идентификатор заключается в кавычки (например, если он содержит символы, недопустимые в открытом виде, или буквы в разных регистрах). Если переданная строка содержит кавычки, они дублируются. См. также Пример 41.1.
|
Преобразует аргумент в строку, подходящую для использования в качестве текстовой константы в SQL-операторе. Внутренние символы апостроф и обратная косая черта при этом дублируются. Заметьте, что
|
Переводит данное значение в текстовый вид и заключает в апострофы как текстовую строку. Символы апостроф и обратная косая черта при этом дублируются.
|
Преобразует аргумент в строку, подходящую для использования в качестве текстовой константы в SQL-операторе; при этом для аргумента NULL возвращается строка
|
Переводит данное значение в текстовый вид и заключает в апострофы как текстовую строку, при этом для аргумента NULL возвращается строка
|
Возвращает подходящие подстроки, полученные из первого вхождения регулярного выражения POSIX в строке
|
Возвращает подходящие подстроки, полученные из первого вхождения регулярного выражения POSIX в строке
{bar}
{baz} |
Заменяет подходящие подстроки, полученные из первого вхождения регулярного выражения POSIX или подходящие подстроки из нескольких вхождений, если использован флаг
|
Разделяет содержимое
|
Разделяет содержимое
hello world |
Повторяет содержимое
|
Заменяет все вхождения в
|
Переставляет символы в строке в обратном порядке.
|
Возвращает последние
|
Дополняет строку
|
Удаляет наибольшую подстроку, содержащую только символы
|
Разделяет строку
|
Возвращает начальную позицию первого вхождения
|
Извлекает из
|
Возвращает
|
Преобразует
|
Преобразует число в шестнадцатеричное представление.
|
Заменяет каждый символ в
|
Функции concat, concat_ws и format принимают переменное число аргументов, так что им для объединения или форматирования можно передавать значения в виде массива, помеченного ключевым словом VARIADIC (см. Подраздел 36.5.5). Элементы такого массива обрабатываются, как если бы они были обычными аргументами функции. Если вместо массива в соответствующем аргументе передаётся NULL, функции concat и concat_ws возвращают NULL, а format воспринимает NULL как массив нулевого размера.
Также обратите внимание на агрегатную функцию string_agg в Разделе 9.21 и функции для преобразования текста в bytea и наоборот в Таблице 9.13.
9.4.1. format
Функция format выдаёт текст, отформатированный в соответствии со строкой формата, подобно функции sprintf в C.
format(formatstrtext[,formatarg"any"[, ...] ])
formatstr — строка, определяющая, как будет форматироваться результат. Обычный текст в строке формата непосредственно копируется в результат, за исключением спецификаторов формата. Спецификаторы формата представляют собой местозаполнители, определяющие, как должны форматироваться и выводиться в результате аргументы функции. Каждый аргумент formatarg преобразуется в текст по правилам вывода своего типа данных, а затем форматируется и вставляется в результирующую строку согласно спецификаторам формата.
Спецификаторы формата предваряются символом % и имеют форму
%[position][flags][width]type
Здесь:
position(необязательный)Строка вида
n$n— индекс выводимого аргумента. Индекс, равный 1, выбирает первый аргумент послеformatstr. Еслиpositionопускается, по умолчанию используется следующий аргумент по порядку.flags(необязательный)Дополнительные флаги, управляющие форматированием данного спецификатора. В настоящее время поддерживается только знак минус (
-), который выравнивает результат спецификатора по левому краю. Этот флаг работает, только если также определено полеwidth.width(необязательный)Задаёт минимальное число символов, которое будет занимать результат данного спецификатора. Выводимое значение выравнивается по правой или левой стороне (в зависимости от флага
-) с дополнением необходимым числом пробелов. Если ширина слишком мала, она просто игнорируется, т. е. результат не усекается. Ширину можно обозначить положительным целым, звёздочкой (*), тогда ширина будет получена из следующего аргумента функции, или строкой вида*, тогда ширина будет задаваться вn$n-м аргументе функции.Если ширина передаётся в аргументе функции, этот аргумент выбирается до аргумента, используемого для спецификатора. Если аргумент ширины отрицательный, результат выравнивается по левой стороне (как если бы был указан флаг
-) в рамках поля длиныabs(width).type(обязательный)Тип спецификатора определяет преобразование соответствующего выводимого значения. Поддерживаются следующие типы:
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')
Следующие примеры иллюстрируют использование поля width и флага -:
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 |
Эти примеры показывают применение полей position:
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 позволяет комбинировать в одной строке спецификаторы с полями position и без них. Спецификатор формата без поля position всегда использует следующий аргумент после последнего выбранного. Кроме того, функция format не требует, чтобы в строке формата использовались все аргументы функции. Пример этого поведения:
SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
Результат: Testing three, two, three
Спецификаторы формата %I и %L особенно полезны для безопасного составления динамических операторов SQL. См. Пример 41.1.
9.4. String Functions and Operators
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. Except where noted, these functions and operators are declared to accept and return type text. They will interchangeably accept character varying arguments. Values of type character will be converted to text before the function or operator is applied, resulting in stripping any trailing spaces in the character value.
SQL defines some string functions that use key words, rather than commas, to separate arguments. Details are in Table 9.9. Postgres Pro also provides versions of these functions that use the regular function invocation syntax (see Table 9.10).
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.9. For other cases, insert an explicit coercion to text if you need to duplicate the previous behavior.
Table 9.9. SQL String Functions and Operators
Function/Operator Description Example(s) |
|---|
Concatenates the two strings.
|
Converts the non-string input to text, then concatenates the two strings. (The non-string input cannot be of an array type, because that would create ambiguity with the array
|
Checks whether the string is in the specified Unicode normalization form. The optional
|
Returns number of bits in the string (8 times the
|
Returns number of characters in the string.
|
Converts the string to all lower case, according to the rules of the database's locale.
|
Converts the string to the specified Unicode normalization form. The optional
|
Returns number of bytes in the string.
|
Returns number of bytes in the string. Since this version of the function accepts type
|
Replaces the substring of
|
Returns first starting index of the specified
|
Extracts the substring of
|
Extracts the first substring matching POSIX regular expression; see Section 9.7.3.
|
Extracts the first substring matching SQL regular expression; see Section 9.7.2.
|
Removes the longest string containing only characters in
|
This is a non-standard syntax for
|
Converts the string to all upper case, according to the rules of the database's locale.
|
Additional string manipulation functions are available and are listed in Table 9.10. Some of them are used internally to implement the SQL-standard string functions listed in Table 9.9.
Table 9.10. Other String Functions
Function Description Example(s) |
|---|
Returns the numeric code of the first character of the argument. In UTF8 encoding, returns the Unicode code point of the character. In other multibyte encodings, the argument must be an ASCII character.
|
Removes the longest string containing only characters in
|
Returns the character with the given code. In UTF8 encoding the argument is treated as a Unicode code point. In other multibyte encodings the argument must designate an ASCII character.
|
Concatenates the text representations of all the arguments. NULL arguments are ignored.
|
Concatenates all but the first argument, with separators. The first argument is used as the separator string, and should not be NULL. Other NULL arguments are ignored.
|
Formats arguments according to a format string; see Section 9.4.1. This function is similar to the C function
|
Converts 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.
|
Returns first
|
Returns the number of characters in the string.
|
Extends the
|
Removes the longest string containing only characters in
|
Computes the MD5 hash of the argument, with the result written in hexadecimal.
|
Splits
|
Returns current client encoding name.
|
Returns 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 41.1.
|
Returns 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
|
Converts the given value to text and then quotes it as a literal. Embedded single-quotes and backslashes are properly doubled.
|
Returns the given string suitably quoted to be used as a string literal in an SQL statement string; or, if the argument is null, returns
|
Converts the given value to text and then quotes it as a literal; or, if the argument is null, returns
|
Returns captured substrings resulting from the first match of a POSIX regular expression to the
|
Returns captured substrings resulting from the first match of a POSIX regular expression to the
{bar}
{baz}
|
Replaces substrings resulting from the first match of a POSIX regular expression, or multiple substring matches if the
|
Splits
|
Splits
hello world |
Repeats
|
Replaces all occurrences in
|
Reverses the order of the characters in the string.
|
Returns last
|
Extends the
|
Removes the longest string containing only characters in
|
Splits
|
Returns first starting index of the specified
|
Extracts the substring of
|
Returns true if
|
Converts
|
Converts the number to its equivalent hexadecimal representation.
|
Replaces each character in
|
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 36.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.21, and the functions for converting between strings and the bytea type in Table 9.13.
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(formatstrtext[,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$nis the index of the argument to print. Index 1 means the first argument afterformatstr. If thepositionis 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 thewidthfield 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*to use then$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 lengthabs(width).type(required)The type of format conversion to use to produce the format specifier's output. The following types are supported:
sformats the argument value as a simple string. A null value is treated as an empty string.Itreats the argument value as an SQL identifier, double-quoting it if necessary. It is an error for the value to be null (equivalent toquote_ident).Lquotes the argument value as an SQL literal. A null value is displayed as the stringNULL, without quotes (equivalent toquote_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 41.1.
