PostgreSQL - SQL Language Reference - String Functions and Operators

PostgreSQL Reference Manual - Volume 1 - SQL Language Reference
by The PostgreSQL Global Development Group
Paperback (6"x9"), 716 pages
ISBN 0954612027
RRP £32.00 ($49.95)

Sales of this book support the PostgreSQL project! Get a printed copy>>>

PostgreSQL Reference Manual
Volume 1

Buy the book here! >>>
only $49.95

7.4 String Functions and Operators

This section describes functions and operators for examining and manipulating string values. Strings in this context include values of all 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 the automatic padding when using the character type. Generally, the functions described here also work on data of non-string types by converting that data to a string representation first. Some functions also exist natively for the bit-string types.

SQL defines some string functions with a special syntax where certain key words rather than commas are used to separate the arguments. Details are in Table 7-5. These functions are also implemented using the regular syntax for function invocation. (See Table 7-6.)

Table 7-5: SQL String Functions and Operators

Function	Return Type	Description
`string \|\| string`	`text`	String concatenation e.g. `'Post' \|\| 'greSQL'` => `PostgreSQL`
`bit_length(string)`	`int`	Number of bits in string e.g. `bit_length('jose')` => `32`
`char_length(string)` or `character_length(string)`	`int`	Number of characters in string e.g. `char_length('jose')` => `4`
`convert(string using conversion_name)`	`text`	Change encoding using specified conversion name. Conversions can be defined by `CREATE CONVERSION`. Also there are some pre-defined conversion names. See Table 7-7 for available conversion names. e.g. `convert('PostgreSQL' using iso_8859_1_to_utf8)` => `'PostgreSQL'` in UTF8 (Unicode, 8-bit) encoding
`lower(string)`	`text`	Convert string to lower case e.g. `lower('TOM')` => `tom`
`octet_length(string)`	`int`	Number of bytes in string e.g. `octet_length('jose')` => `4`
`overlay(string placing string from int [for int])`	`text`	Replace substring e.g. `overlay('Txxxxas' placing 'hom' from 2 for 4)` => `Thomas`
`position(substring in string)`	`int`	Location of specified substring e.g. `position('om' in 'Thomas')` => `3`
`substring(string [from int] [for int])`	`text`	Extract substring e.g. `substring('Thomas' from 2 for 3)` => `hom`
`substring(string from pattern)`	`text`	Extract substring matching POSIX regular expression. See section 7.7 Pattern Matching for more information on pattern matching. e.g. `substring('Thomas' from '...$')` => `mas`
`substring(string from pattern for escape)`	`text`	Extract substring matching SQL regular expression. See section 7.7 Pattern Matching for more information on pattern matching. e.g. `substring('Thomas' from '%#"o_a#"_' for '#')` => `oma`
`trim([leading \| trailing \| both] [characters] from string)`	`text`	Remove the longest string containing only the `characters` (a space by default) from the start/end/both ends of the `string` e.g. `trim(both 'x' from 'xTomxx')` => `Tom`
`upper(string)`	`text`	Convert string to uppercase e.g. `upper('tom')` => `TOM`

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

Table 7-6: Other String Functions

Function	Return Type	Description
`ascii(string)`	`int`	ASCII code of the first byte of the argument e.g. `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` e.g. `btrim('xyxtrimyyx', 'xy')` => `trim`
`chr(int)`	`text`	Character with the given ASCII code e.g. `chr(65)` => `A`
`convert(string text, [src_encoding name,] dest_encoding name)`	`text`	Convert string to `dest_encoding`. The original encoding is specified by `src_encoding`. If `src_encoding` is omitted, database encoding is assumed. e.g. `convert( 'text_in_utf8', 'UTF8', 'LATIN1')` => `text_in_utf8` represented in ISO 8859-1 encoding
`decode(string text, type text)`	`bytea`	Decode binary data from `string` previously encoded with `encode`. Parameter type is same as in `encode`. e.g. `decode('MTIzAAE=', 'base64')` => `123\000\001`
`encode(data bytea, type text)`	`text`	Encode binary data to ASCII-only representation. Supported types are: `base64`, `hex`, `escape`. e.g. `encode( E'123\\000\\001', 'base64')` => `MTIzAAE=`
`initcap(string)`	`text`	Convert the first letter of each word to uppercase and the rest to lowercase. Words are sequences of alphanumeric characters separated by non-alphanumeric characters. e.g. `initcap('hi THOMAS')` => `Hi Thomas`
`length(string)`	`int`	Number of characters in `string` e.g. `length('jose')` => `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). e.g. `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` e.g. `ltrim('zzzytrim', 'xyz')` => `trim`
`md5(string)`	`text`	Calculates the MD5 hash of `string`, returning the result in hexadecimal e.g. `md5('abc')` => `900150983cd24fb0 d6963f7d28e17f72`
`pg_client_encoding()`	`name`	Current client encoding name e.g. `pg_client_encoding()` => `SQL_ASCII`
`quote_ident(string)`	`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. e.g. `quote_ident('Foo bar')` => `"Foo bar"`
`quote_literal(string)`	`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. e.g. `quote_literal( 'O\'Reilly')` => `'O''Reilly'`
`regexp_replace(string text, pattern text, replacement text [,flags text])`	`text`	Replace substring matching POSIX regular expression. See section 7.7 Pattern Matching for more information on pattern matching. e.g. `regexp_replace('Thomas', '.[mN]a.', 'M')` => `ThM`
`repeat(string text, number int)`	`text`	Repeat `string` the specified `number` of times e.g. `repeat('Pg', 4)` => `PgPgPgPg`
`replace(string text, from text, to text)`	`text`	Replace all occurrences in `string` of substring `from` with substring `to` e.g. `replace( 'abcdefabcdef', 'cd', 'XX')` => `abXXefabXXef`
`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. e.g. `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` e.g. `rtrim('trimxxxx', 'x')` => `trim`
`split_part(string text, delimiter text, field int)`	`text`	Split `string` on `delimiter` and return the given field (counting from one) e.g. `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) e.g. `strpos('high', 'ig')` => `2`
`substr(string, from [, count])`	`text`	Extract substring (same as `substring(string from from for count)`) e.g. `substr('alphabet', 3, 2)` => `ph`
`to_ascii(string text [, encoding text])`	`text`	Convert `string` to ASCII from another encoding (only supports conversion from `LATIN1`, `LATIN2`, `LATIN9`, and `WIN1250` encodings) e.g. `to_ascii('Karel')` => `Karel`
`to_hex(number int or bigint)`	`text`	Convert `number` to its equivalent hexadecimal representation e.g. `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 e.g. `translate('12345', '14', 'ax')` => `a23x5`

Table 7-7: Built-in Conversions

Conversion Name ⁽²⁾	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`	`KOI8`
`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`	`KOI8`	`ISO_8859_5`
`koi8_r_to_mic`	`KOI8`	`MULE_INTERNAL`
`koi8_r_to_utf8`	`KOI8`	`UTF8`
`koi8_r_to_windows_1251`	`KOI8`	`WIN1251`
`koi8_r_to_windows_866`	`KOI8`	`WIN866`
`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`	`KOI8`
`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`
`tcvn_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`	`KOI8`
`utf8_to_sjis`	`UTF8`	`SJIS`
`utf8_to_tcvn`	`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`	`KOI8`
`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`	`KOI8`
`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`

PostgreSQL Reference Manual - Volume 1 - SQL Language Reference

See the print edition