November 21, 2024: PostgreSQL 17.2, 16.6, 15.10, 14.15, 13.18, and 12.22 Released!
Supported Versions: Current (17) / 16 / 15 / 14 / 13
Development Versions: devel
Unsupported versions: 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1
This documentation is for an unsupported version of PostgreSQL.
You may want to view the same page for the current version, or one of the other supported versions listed above instead.
PostgreSQL 7.2.8 Documentation
Prev Chapter 4. Functions and Operators Next

4.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 keywords rather than commas are used to separate the arguments. Details are in Table 4-6. These functions are also implemented using the regular syntax for function invocation. (See Table 4-7.)

Table 4-6. SQL String Functions and Operators

Function Return Type Description Example Result
string || string text string concatenation 'Postgre' || 'SQL' 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
lower(string) text Convert string to lower case. lower('TOM') tom
octet_length(string) integer number of bytes in string octet_length('jose') 4
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
trim([leading | trailing | both] [characters] from string) text Removes 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 below. Some of them are used internally to implement the SQL-standard string functions listed above.

Table 4-7. Other String Functions

Function Return Type Description Example Result
ascii(text) integer Returns the 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 Returns the character with the given ASCII code. chr(65) A
convert(string text, [src_encoding name,] dest_encoding name) text Converts string using 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
initcap(text) text Converts 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 Fills 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, trim text) text Removes the longest string containing only characters from trim from the start of the string. ltrim('zzzytrim','xyz') trim
pg_client_encoding() name Returns current client encoding name. pg_client_encoding() SQL_ASCII
repeat(text, integer) text Repeat text a number of times. repeat('Pg', 4) PgPgPgPg
rpad(string text, length integer [, fill text]) text Fills 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 Removes the longest string containing only characters from trim from the end of the string. rtrim('trimxxxx','x') trim
strpos(string, substring) text Locates specified substring. (same as position(substring in string), but note the reversed argument order) strpos('high','ig') 2
substr(string, from [, count]) text Extracts specified substring. (same as substring(string from from for count)) substr('alphabet', 3, 2) ph
to_ascii(text [, encoding]) text Converts text from multibyte encoding to ASCII. to_ascii('Karel') Karel
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
encode(data bytea, type text) text Encodes binary data to ASCII-only representation. Supported types are: 'base64', 'hex', 'escape'. encode('123\\000\\001', 'base64') MTIzAAE=
decode(string text, type text) bytea Decodes binary data from string previously encoded with encode(). Parameter type is same as in encode(). decode('MTIzAAE=', 'base64') 123\000\001

The to_ascii function supports conversion from LATIN1, LATIN2, WIN1250 (CP1250) only.

Prev Home Next
Mathematical Functions and Operators Up Binary String Functions and Operators