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 9.5, “SQL String Functions and Operators”. These functions are also implemented using the regular syntax for function invocation. (See Table 9.6, “Other String Functions”.)
Table 9.5. SQL String Functions and Operators
Function | Return Type | Description | Example | Result |
---|---|---|---|---|
|
text |
String concatenation | 'Post' || 'greSQL' |
PostgreSQL |
|
int |
Number of bits in string | bit_length('jose') |
32 |
or
|
int |
Number of characters in string | char_length('jose') |
4 |
|
text |
Change encoding using specified conversion name. Conversions
can be defined by CREATE CONVERSION . Also
there are some pre-defined conversion names. See Table 9.7, “Built-in Conversions” for available conversion
names.
|
convert('PostgreSQL' using iso_8859_1_to_utf8) |
'PostgreSQL' in UTF8 (Unicode, 8-bit) encoding |
|
text |
Convert string to lower case | lower('TOM') |
tom |
|
int |
Number of bytes in string | octet_length('jose') |
4 |
|
text |
Replace substring | overlay('Txxxxas' placing 'hom' from 2 for 4) |
Thomas |
|
int |
Location of specified substring | position('om' in 'Thomas') |
3 |
|
text |
Extract substring | substring('Thomas' from 2 for 3) |
hom |
|
text |
Extract substring matching POSIX regular expression. See Section 9.7, “Pattern Matching” for more information on pattern matching. | substring('Thomas' from '...$') |
mas |
|
text |
Extract substring matching SQL regular expression. See Section 9.7, “Pattern Matching” for more information on pattern matching. | substring('Thomas' from '%#"o_a#"_' for '#') |
oma |
|
text |
Remove the longest string containing only the
characters (a space by default) from the
start/end/both ends of the string
|
trim(both 'x' from 'xTomxx') |
Tom |
|
text |
Convert string to uppercase | upper('tom') |
TOM |
Additional string manipulation functions are available and are listed in Table 9.6, “Other String Functions”. Some of them are used internally to implement the SQL-standard string functions listed in Table 9.5, “SQL String Functions and Operators”.
Table 9.6. Other String Functions
Function | Return Type | Description | Example | Result |
---|---|---|---|---|
|
int |
ASCII code of the first byte of the argument | ascii('x') |
120 |
|
text |
Remove the longest string consisting only of characters
in characters (a space by default)
from the start and end of string
|
btrim('xyxtrimyyx', 'xy') |
trim |
|
text |
Character with the given ASCII code | chr(65) |
A |
|
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_utf8', 'UTF8', 'LATIN1') |
text_in_utf8 represented in ISO 8859-1 encoding |
|
bytea |
Decode binary data from string previously
encoded with encode . Parameter type is same as in encode .
|
decode('MTIzAAE=', 'base64') |
123\000\001 |
|
text |
Encode binary data to ASCII-only representation. Supported
types are: base64 , hex , escape .
|
encode( E'123\\000\\001', 'base64') |
MTIzAAE= |
|
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. | initcap('hi THOMAS') |
Hi Thomas |
|
int |
Number of characters in string
|
length('jose') |
4 |
|
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 |
|
text |
Remove the longest string containing only characters from
characters (a space by default) from the start of
string
|
ltrim('zzzytrim', 'xyz') |
trim |
|
text |
Calculates the MD5 hash of string ,
returning the result in hexadecimal
|
md5('abc') |
900150983cd24fb0 d6963f7d28e17f72 |
|
name |
Current client encoding name | pg_client_encoding() |
SQL_ASCII |
|
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. | quote_ident('Foo bar') |
"Foo bar" |
|
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. | quote_literal( 'O\'Reilly') |
'O''Reilly' |
|
text |
Replace substring matching POSIX regular expression. See Section 9.7, “Pattern Matching” for more information on pattern matching. | regexp_replace('Thomas', '.[mN]a.', 'M') |
ThM |
|
text |
Repeat string the specified
number of times |
repeat('Pg', 4) |
PgPgPgPg |
|
text |
Replace all occurrences in string of substring
from with substring to
|
replace( 'abcdefabcdef', 'cd', 'XX') |
abXXefabXXef |
|
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 |
|
text |
Remove the longest string containing only characters from
characters (a space by default) from the end of
string
|
rtrim('trimxxxx', 'x') |
trim |
|
text |
Split string on delimiter
and return the given field (counting from one)
|
split_part('abc~@~def~@~ghi', '~@~', 2) |
def |
|
int |
Location of specified substring (same as
position( , but note the reversed
argument order)
|
strpos('high', 'ig') |
2 |
|
text |
Extract substring (same as
substring( )
|
substr('alphabet', 3, 2) |
ph |
|
text |
Convert string to ASCII from another encoding
(only supports conversion from LATIN1 , LATIN2 , LATIN9 ,
and WIN1250 encodings)
|
to_ascii('Karel') |
Karel |
|
text |
Convert number to its equivalent hexadecimal
representation
|
to_hex(2147483647) |
7fffffff |
|
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 |
Table 9.7. 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 |
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 |
[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 |