This page in other versions: 8.4 / 9.0 / 9.1 / 9.2 / 9.3  |  Development versions: devel  |  Unsupported versions: 7.1 / 7.2 / 7.3 / 7.4 / 8.0 / 8.1 / 8.2 / 8.3

6.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 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 6-6. These functions are also implemented using the regular syntax for function invocation. (See Table 6-7.)

Table 6-6. SQL String Functions and Operators

Function Return Type Description Example Result
string || string text String concatenation 'Post' || 'greSQL' PostgreSQL
bit_length(string) integer Number of bits in string bit_length('jose') 32
char_length(string) or character_length(string) integer Number of characters in string 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 6-8 for available conversion names. convert('PostgreSQL' using iso_8859_1_to_utf_8) 'PostgreSQL' in Unicode (UTF-8) encoding
lower(string) text Convert string to lower case lower('TOM') tom
octet_length(string) integer Number of bytes in string octet_length('jose') 4
overlay(string placing string from integer [for integer]) text Insert substring overlay('Txxxxas' placing 'hom' from 2 for 4) Thomas
position(substring in string) integer Location of specified substring position('om' in 'Thomas') 3
substring(string [from integer] [for integer]) text Extract substring substring('Thomas' from 2 for 3) hom
substring(string from pattern) text Extract substring matching POSIX regular expression substring('Thomas' from '...$') mas
substring(string from pattern for escape) text Extract substring matching SQL regular expression 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 beginning/end/both ends of the string trim(both 'x' from 'xTomxx') Tom
upper(string) text Convert string to upper case upper('tom') TOM

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

Table 6-7. Other String Functions

Function Return Type Description Example Result
ascii(text) integer ASCII code of the first character of the argument. ascii('x') 120
btrim(string text, trim text) text Remove (trim) the longest string consisting only of characters in trim from the start and end of string btrim('xyxtrimyyx','xy') trim
chr(integer) text Character with the given ASCII code 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. convert('text_in_unicode', 'UNICODE', 'LATIN1') text_in_unicode represented in ISO 8859-1
decode(string text, type text) bytea Decode binary data from string previously encoded with encode(). Parameter type is same as in encode(). 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. encode('123\\000\\001', 'base64') MTIzAAE=
initcap(text) text Convert first letter of each word (whitespace separated) to upper case initcap('hi thomas') Hi Thomas
length(string) integer Length of string length('jose') 4
lpad(string text, length integer [, 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, text text) text Remove the longest string containing only characters from trim from the start of the string. ltrim('zzzytrim','xyz') trim
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 query 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. quote_ident('Foo') "Foo"
quote_literal(string text) text Return the given string suitably quoted to be used as a literal in an SQL query string. Embedded quotes and backslashes are properly doubled. quote_literal('O\'Reilly') 'O''Reilly'
repeat(text, integer) text Repeat text a 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
rpad(string text, length integer [, 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, trim text) text Remove the longest string containing only characters from trim from the end of the string. rtrim('trimxxxx','x') trim
split_part(string text, delimiter text, column integer) text Split string on delimiter returning the resulting (one based) column number. split_part('abc~@~def~@~ghi','~@~',2) def
strpos(string, substring) int Locate specified substring (same as position(substring in string), but note the reversed argument order) strpos('high','ig') 2
substr(string, from [, count]) text Extract specified substring (same as substring(string from from for count)) substr('alphabet', 3, 2) ph
to_ascii(text [, encoding]) text Convert text to ASCII from other encoding [a] to_ascii('Karel') Karel
to_hex(number integer or bigint) text Convert number to its equivalent hexadecimal representation to_hex(9223372036854775807::bigint) 7fffffffffffffff
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. translate('12345', '14', 'ax') a23x5
Notes:
a. The to_ascii function supports conversion from LATIN1, LATIN2, and WIN1250 only.

Table 6-8. Built-in Conversions

Conversion Name [a] Source Encoding Destination Encoding
ascii_to_mic SQL_ASCII MULE_INTERNAL
ascii_to_utf_8 SQL_ASCII UNICODE
big5_to_euc_tw BIG5 EUC_TW
big5_to_mic BIG5 MULE_INTERNAL
big5_to_utf_8 BIG5 UNICODE
euc_cn_to_mic EUC_CN MULE_INTERNAL
euc_cn_to_utf_8 EUC_CN UNICODE
euc_jp_to_mic EUC_JP MULE_INTERNAL
euc_jp_to_sjis EUC_JP SJIS
euc_jp_to_utf_8 EUC_JP UNICODE
euc_kr_to_mic EUC_KR MULE_INTERNAL
euc_kr_to_utf_8 EUC_KR UNICODE
euc_tw_to_big5 EUC_TW BIG5
euc_tw_to_mic EUC_TW MULE_INTERNAL
euc_tw_to_utf_8 EUC_TW UNICODE
gb18030_to_utf_8 GB18030 UNICODE
gbk_to_utf_8 GBK UNICODE
iso_8859_10_to_utf_8 LATIN6 UNICODE
iso_8859_13_to_utf_8 LATIN7 UNICODE
iso_8859_14_to_utf_8 LATIN8 UNICODE
iso_8859_15_to_utf_8 LATIN9 UNICODE
iso_8859_16_to_utf_8 LATIN10 UNICODE
iso_8859_1_to_mic LATIN1 MULE_INTERNAL
iso_8859_1_to_utf_8 LATIN1 UNICODE
iso_8859_2_to_mic LATIN2 MULE_INTERNAL
iso_8859_2_to_utf_8 LATIN2 UNICODE
iso_8859_2_to_windows_1250 LATIN2 WIN1250
iso_8859_3_to_mic LATIN3 MULE_INTERNAL
iso_8859_3_to_utf_8 LATIN3 UNICODE
iso_8859_4_to_mic LATIN4 MULE_INTERNAL
iso_8859_4_to_utf_8 LATIN4 UNICODE
iso_8859_5_to_koi8_r ISO_8859_5 KOI8
iso_8859_5_to_mic ISO_8859_5 MULE_INTERNAL
iso_8859_5_to_utf_8 ISO_8859_5 UNICODE
iso_8859_5_to_windows_1251 ISO_8859_5 WIN
iso_8859_5_to_windows_866 ISO_8859_5 ALT
iso_8859_6_to_utf_8 ISO_8859_6 UNICODE
iso_8859_7_to_utf_8 ISO_8859_7 UNICODE
iso_8859_8_to_utf_8 ISO_8859_8 UNICODE
iso_8859_9_to_utf_8 LATIN5 UNICODE
johab_to_utf_8 JOHAB UNICODE
koi8_r_to_iso_8859_5 KOI8 ISO_8859_5
koi8_r_to_mic KOI8 MULE_INTERNAL
koi8_r_to_utf_8 KOI8 UNICODE
koi8_r_to_windows_1251 KOI8 WIN
koi8_r_to_windows_866 KOI8 ALT
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 WIN
mic_to_windows_866 MULE_INTERNAL ALT
sjis_to_euc_jp SJIS EUC_JP
sjis_to_mic SJIS MULE_INTERNAL
sjis_to_utf_8 SJIS UNICODE
tcvn_to_utf_8 TCVN UNICODE
uhc_to_utf_8 UHC UNICODE
utf_8_to_ascii UNICODE SQL_ASCII
utf_8_to_big5 UNICODE BIG5
utf_8_to_euc_cn UNICODE EUC_CN
utf_8_to_euc_jp UNICODE EUC_JP
utf_8_to_euc_kr UNICODE EUC_KR
utf_8_to_euc_tw UNICODE EUC_TW
utf_8_to_gb18030 UNICODE GB18030
utf_8_to_gbk UNICODE GBK
utf_8_to_iso_8859_1 UNICODE LATIN1
utf_8_to_iso_8859_10 UNICODE LATIN6
utf_8_to_iso_8859_13 UNICODE LATIN7
utf_8_to_iso_8859_14 UNICODE LATIN8
utf_8_to_iso_8859_15 UNICODE LATIN9
utf_8_to_iso_8859_16 UNICODE LATIN10
utf_8_to_iso_8859_2 UNICODE LATIN2
utf_8_to_iso_8859_3 UNICODE LATIN3
utf_8_to_iso_8859_4 UNICODE LATIN4
utf_8_to_iso_8859_5 UNICODE ISO_8859_5
utf_8_to_iso_8859_6 UNICODE ISO_8859_6
utf_8_to_iso_8859_7 UNICODE ISO_8859_7
utf_8_to_iso_8859_8 UNICODE ISO_8859_8
utf_8_to_iso_8859_9 UNICODE LATIN5
utf_8_to_johab UNICODE JOHAB
utf_8_to_koi8_r UNICODE KOI8
utf_8_to_sjis UNICODE SJIS
utf_8_to_tcvn UNICODE TCVN
utf_8_to_uhc UNICODE UHC
utf_8_to_windows_1250 UNICODE WIN1250
utf_8_to_windows_1251 UNICODE WIN
utf_8_to_windows_1256 UNICODE WIN1256
utf_8_to_windows_866 UNICODE ALT
utf_8_to_windows_874 UNICODE WIN874
windows_1250_to_iso_8859_2 WIN1250 LATIN2
windows_1250_to_mic WIN1250 MULE_INTERNAL
windows_1250_to_utf_8 WIN1250 UNICODE
windows_1251_to_iso_8859_5 WIN ISO_8859_5
windows_1251_to_koi8_r WIN KOI8
windows_1251_to_mic WIN MULE_INTERNAL
windows_1251_to_utf_8 WIN UNICODE
windows_1251_to_windows_866 WIN ALT
windows_1256_to_utf_8 WIN1256 UNICODE
windows_866_to_iso_8859_5 ALT ISO_8859_5
windows_866_to_koi8_r ALT KOI8
windows_866_to_mic ALT MULE_INTERNAL
windows_866_to_utf_8 ALT UNICODE
windows_866_to_windows_1251 ALT WIN
windows_874_to_utf_8 WIN874 UNICODE
Notes:
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 equally processed destination encoding name. Therefore the names might deviate from the customary encoding names.

Comments


Feb. 10, 2003, 8:06 p.m.

I\'ve found that trim has more to it than the documentation states:

# select \'.\' || trim(both \'\\r\\n\' from \' things\\n\\r\') || \'.\' ;
?column?
-----------
. things.
(1 row)

You can specify a number of characters which must be trimmed.


June 25, 2003, 11:02 p.m.

FWIW, if you cat a NULL value with a known value, it is correct (but annoying) to return a NULL value. [Unknown] || \'foo\' is still [Unknown]


Sept. 18, 2003, 9:14 p.m.

ACTUAL LENGTH() OF CHAR(N) VALUES

The functions char_length() and length(), if applied to a fixed-width \'CHAR\' column, always return the fixed length of that column including the BLANK padding.

For example, if you declare a column as type CHAR(20) when creating your table and then try to apply either of these functions to values contained in that column, you will ALWAYS get back a value of 20.

The REAL length of the field has all the BLANKS on the RIGHT side removed. So, use RTRIM(COLUMN) to remove them before asking from the LENGTH().

BPWORD CHAR(20)...

=> select length(bpword), length(rtrim(bpword)), bpword
-> from words;

length | length | bpword
--------+--------+----------------------
20 | 9 | something
20 | 2 | or
20 | 7 | another
20 | 9 | spaced
(4 rows)

See TRIM() or LTRIM() for other options.


Oct. 10, 2003, 2:49 p.m.

You can use the following sentence to skip the problem concatenating NULL values.

SELECT COALESCE(\'aaa\', \'\')||COALESCE(null, \'\')

?column?
----------
aaa

1 Row(s) affected

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group