PostgreSQL 8.0.0rc4 Documentation
Prev | Fast Backward | Chapter 9. Functions and Operators | Fast Forward | Next

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

Table 9-5. 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 9-7 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` | Replace 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 start/end/both ends of the `string`. | `trim(both 'x' from 'xTomxx')` | `Tom`
``upper`(`string`)` | `text` | Convert string to uppercase | `upper('tom')` | `TOM`

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

Table 9-6. 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` [, `characters` `text`])` | `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`
``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 encoding
``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 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`
``length`(`string` `text`)` | `integer` | Number of characters in `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` [, `characters` `text`])` | `text` | Remove the longest string containing only characters from `characters` (a space by default) from the start of `string`. | `ltrim('zzzytrim', 'xyz')` | `trim`
``md5`(`string` `text`)` | `text` | Calculates the MD5 hash of `string`, returning the result in hexadecimal. | `md5('abc')` | `900150983cd24fb0 d6963f7d28e17f72`
``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 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"`
``quote_literal`(`string` text)` | `text` | Return the given string suitably quoted to be used as a string literal in an SQL statement string. Embedded quotes and backslashes are properly doubled. | `quote_literal( 'O\'Reilly')` | `'O''Reilly'`
``repeat`(`string` `text`, `number` `integer`)` | `text` | Repeat `string` the specified `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` [, `characters` `text`])` | `text` | Remove the longest string containing only characters from `characters` (a space by default) from the end of `string`. | `rtrim('trimxxxx', 'x')` | `trim`
``split_part`(`string` `text`, `delimiter` `text`, `field` `integer`)` | `text` | Split `string` on `delimiter` and return the given field (counting from one) | `split_part( 'abc~@~def~@~ghi', '~@~', 2)` | `def`
``strpos`(`string`, `substring`)` | `text` | Location of specified substring (same as `position(`substring` in `string`)`, but note the reversed argument order) | `strpos('high', 'ig')` | `2`
``substr`(`string`, `from` [, `count`])` | `text` | Extract substring (same as `substring(`string` from `from` for `count`)`) | `substr('alphabet', 3, 2)` | `ph`
``to_ascii`(`text` [, `encoding`])` | `text` | Convert `text` to ASCII from another encoding [a] | `to_ascii('Karel')` | `Karel`
``to_hex`(`number` `integer` or `bigint`)` | `text` | Convert `number` to its equivalent hexadecimal representation | `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. | `translate('12345', '14', 'ax')` | `a23x5`
Notes: a. The `to_ascii` function supports conversion from `LATIN1`, `LATIN2`, `LATIN9`, and `WIN1250` encodings only.

Table 9-7. 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.

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