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

FunctionReturn TypeDescriptionExampleResult
string || string text string concatenation 'Postgre' || 'SQL'PostgreSQL
bit_length(string)integernumber of bits in stringbit_length('jose')32
char_length(string) or character_length(string)integer number of characters in string char_length('jose')4
lower(string)textConvert string to lower case.lower('TOM')tom
octet_length(string)integernumber of bytes in stringoctet_length('jose')4
position(substring in string)integerlocation of specified substringposition('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)textConvert 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

FunctionReturn TypeDescriptionExampleResult
ascii(text)integerReturns 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)textReturns 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)textConverts 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)textRepeat 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])textConverts 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.