PostgreSQL
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. 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.9. PostgreSQL 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 | Return Type | Description | Example | Result |
|---|---|---|---|---|
`string |
`` `_`+string`_ |
|
String concatenation |
|
`+'Post' |
'greSQL'+` |
|
`string |
|
`` `_`+non-string |
`` `_`+string`_ |
|
||
String concatenation with one non-string input |
`+'Value: ' |
42+` |
|
|
|
|
Number of bits in string |
|
|
|
|
Number of characters in string |
|
|
|
|
Convert string to lower case |
|
|
|
|
Number of bytes in string |
|
|
|
|
Replace substring |
|
|
|
|
Location of specified substring |
|
|
|
|
Extract substring |
|
|
|
|
Extract substring matching POSIX regular expression. See Section 9.7 for more information on pattern matching. |
|
|
|
|
Extract substring matching SQL regular expression. See Section 9.7 for more information on pattern matching. |
|
|
|
trailing |
both+ |
|
Remove the longest string containing only characters from `characters |
|
|
|
trailing |
both+ |
|
Non-standard syntax for |
|
|
|
+
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 | Return Type | Description | Example | Result |
|---|---|---|---|---|
|
|
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. |
|
|
|
|
Remove the longest string consisting only of characters in `characters |
|
|
|
|
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. |
|
|
|
|
Concatenate the text representations of all the arguments. NULL arguments are ignored. |
|
|
|
|
Concatenate all but the first argument with separators. The first argument is used as the separator string. NULL arguments are ignored. |
|
|
|
|
Convert string to `dest_encoding |
|
|
|
|
Convert string to the database encoding. The original encoding is specified by `src_encoding |
|
|
|
|
Convert string to `dest_encoding`. |
|
|
|
|
Decode binary data from textual representation in `string |
|
|
|
|
Encode binary data into a textual representation. Supported formats are: |
|
|
|
|
Format arguments according to a format string. This function is similar to the C function |
|
|
|
|
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. |
|
|
|
|
Return first `n |
|
|
|
|
Number of characters in `string` |
|
|
|
|
Number of characters in `string |
|
|
|
|
Fill up the `string |
|
|
|
|
Remove the longest string containing only characters from `characters |
|
|
|
|
Calculates the MD5 hash of `string`, returning the result in hexadecimal |
|
|
|
|
Split `qualified_identifier |
|
|
|
|
Current client encoding name |
|
|
|
|
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 42.1. |
|
|
|
|
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 |
|
|
|
|
Coerce the given value to text and then quote it as a literal. Embedded single-quotes and backslashes are properly doubled. |
|
|
|
|
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 |
|
|
|
|
Coerce the given value to text and then quote it as a literal; or, if the argument is null, return |
|
|
|
|
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. |
|
|
|
|
Return captured substring(s) resulting from matching a POSIX regular expression to the `string`. See Section 9.7.3 for more information. |
|
(2 rows) |
|
|
Replace substring(s) matching a POSIX regular expression. See Section 9.7.3 for more information. |
|
|
|
|
Split `string` using a POSIX regular expression as the delimiter. See Section 9.7.3 for more information. |
|
|
|
|
Split `string` using a POSIX regular expression as the delimiter. See Section 9.7.3 for more information. |
|
(2 rows) |
|
|
Repeat `string |
|
|
|
|
Replace all occurrences in `string |
|
|
|
|
Return reversed string. |
|
|
|
|
Return last `n |
|
|
|
|
Fill up the `string |
|
|
|
|
Remove the longest string containing only characters from `characters |
|
|
|
|
Split `string |
|
|
|
|
Location of specified substring (same as |
|
|
|
|
Extract substring (same as |
|
|
|
|
Returns true if `string |
|
|
|
|
Convert `string |
|
|
|
|
Convert `number` to its equivalent hexadecimal representation |
|
|
|
|
Any character in `string |
|
|
+
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 37.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.11. Built-in Conversions
| Conversion Name [a] | Source Encoding | Destination Encoding |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[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 |
+
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]typewhere the component fields are:
- `position` (optional)
-
A string of the form `n
$` where `nis 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 __`+n_th 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, PostgreSQL’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, threeThe %I and %L format specifiers are particularly useful for safely constructing dynamic SQL statements. See Example 42.1.
| Prev | Up | Next |
|---|---|---|
9.3. Mathematical Functions and Operators |
9.5. Binary String Functions and Operators |
Submit correction
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.
Copyright © 1996-2023 The PostgreSQL Global Development Group