diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 99f5311fd2d..6aaf454b4c8 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2030,10 +2030,12 @@ repeat('Pg', 4) PgPgPgPg
This section describes functions and operators for examining and
manipulating string values. Strings in this context include values
of 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 automatic space-padding when using the
- character type.
+ and text. Except where noted, these functions and operators
+ are declared to accept and return type text. They will
+ interchangeably accept character varying arguments.
+ Values of type character will be converted
+ to text before the function or operator is applied, resulting
+ in stripping any trailing spaces in the character value.
@@ -2062,96 +2064,94 @@ repeat('Pg', 4) PgPgPgPg
<acronym>SQL</acronym> String Functions and Operators
-
+
- Function
- Return Type
- Description
- Example
- Result
+
+ Function/OperatorDescriptionExample(s)
+
- string ||
- string
- text
-
- String concatenation
+
character string
concatenation
+ text || text
+ text
+
+ Concatenates the two strings.
+
+ 'Post' || 'greSQL'
+ PostgreSQL
- 'Post' || 'greSQL'
- PostgreSQL
-
- string ||
- non-string
- or
- non-string ||
- string
+
+ text || anynonarray
+ or anynonarray || text
+ text
+
+ Converts the non-string input to text, then concatenates the two
+ strings. (The non-string input cannot be of an array type, because
+ that would create ambiguity with the array ||
+ operators. If you want to concatenate an array's text equivalent,
+ cast it to text explicitly.)
+
+ 'Value: ' || 42
+ Value: 42
- text
-
- String concatenation with one non-string input
-
- 'Value: ' || 42
- Value: 42
-
+
normalized
Unicode normalization
- string is not form normalized
-
- boolean
-
+ text IS NOT form NORMALIZED
+ boolean
+
Checks whether the string is in the specified Unicode normalization
- form. The optional parameter specifies the form:
- NFC (default), NFD,
- NFKC, NFKD. This expression can
- only be used if the server encoding is UTF8. Note
+ form. The optional form key word specifies the
+ form: NFC (the default), NFD,
+ NFKC, or NFKD. This expression can
+ only be used when the server encoding is UTF8. Note
that checking for normalization using this expression is often faster
than normalizing possibly already normalized strings.
+
+ U&'\0061\0308bc' IS NFD NORMALIZED
+ t
- U&'\0061\0308bc' IS NFD NORMALIZED
- true
-
+
bit_length
- bit_length(string)
+ bit_length ( text )
+ integer
+
+ Returns number of bits in the string (8
+ times the octet_length).
+
+ bit_length('jose')
+ 32
- int
- Number of bits in string
- bit_length('jose')
- 32
-
+
char_length
- char_length(string) or character_length(string)
-
- int
-
- Number of characters in string
character string
length
@@ -2161,175 +2161,224 @@ repeat('Pg', 4) PgPgPgPg
of a character string
character string, length
+ char_length ( text )
+ or character_length ( text )
+ integer
+
+ Returns number of characters in the string.
+
+ char_length('josé')
+ 4
- char_length('jose')
- 4
-
+
lower
- lower(string)
+ lower ( text )
+ text
+
+ Converts the string to all lower case, according to the rules of the
+ database's locale.
+
+ lower('TOM')
+ tom
- text
- Convert string to lower case
- lower('TOM')
- tom
-
+
normalize
Unicode normalization
- normalize(string text
- , form )
+ normalize ( text
+ , form )
+ text
+
+ Converts the string to the specified Unicode
+ normalization form. The optional form key word
+ specifies the form: NFC (the default),
+ NFD, NFKC, or
+ NFKD. This function can only be used when the
+ server encoding is UTF8.
+
+ normalize(U&'\0061\0308bc', NFC)
+ U&'\00E4bc'
- text
-
- Converts the string in the first argument to the specified Unicode
- normalization form. The optional second argument specifies the form
- as an identifier: NFC (default),
- NFD, NFKC,
- NFKD. This function can only be used if the server
- encoding is UTF8.
-
- normalize(U&'\0061\0308bc', NFC)
- U&'\00E4bc'
-
+
octet_length
- octet_length(string)
+ octet_length ( text )
+ integer
+
+ Returns number of bytes in the string.
+
+ octet_length('josé')
+ 5 (if server encoding is UTF8)
- int
- Number of bytes in string
- octet_length('jose')
- 4
-
+
+
+ octet_length
+
+ octet_length ( character )
+ integer
+
+ Returns number of bytes in the string. Since this version of the
+ function accepts type character directly, it will not
+ strip trailing spaces.
+
+ octet_length('abc '::character(4))
+ 4
+
+
+
+
+
overlay
- overlay(string placing string from int for int)
+ overlay ( string text PLACING newsubstring text FROM start integer FOR count integer )
+ text
+
+ Replaces the substring of string that starts at
+ the start'th character and extends
+ for count characters
+ with newsubstring.
+ If count is omitted, it defaults to the length
+ of newsubstring.
+
+ overlay('Txxxxas' placing 'hom' from 2 for 4)
+ Thomas
- text
-
- Replace substring
-
- overlay('Txxxxas' placing 'hom' from 2 for 4)
- Thomas
-
+
position
- position(substring in string)
+ position ( substring text IN string text )
+ integer
+
+ Returns starting index of specified substring
+ within string, or zero if it's not present.
+
+ position('om' in 'Thomas')
+ 3
- int
- Location of specified substring
- position('om' in 'Thomas')
- 3
-
+
substring
- substring(string from int for int)
+ substring ( string text FROM start integer FOR count integer )
+ text
+
+ Extracts the substring of string starting at
+ the start'th character if that is specified,
+ and stopping after count characters if that is
+ specified. Provide at least one of start
+ and count.
+
+ substring('Thomas' from 2 for 3)
+ hom
+
+ substring('Thomas' from 3)
+ omas
+
+ substring('Thomas' for 2)
+ Th
- text
-
- Extract substring (provide at least one of from
- and for)
-
- substring('Thomas' from 2 for 3)
- hom
- substring(string from pattern)
- text
-
- Extract substring matching POSIX regular expression (see
- for more information on pattern
- matching)
+
+ substring ( string text FROM pattern text )
+ text
+
+ Extracts substring matching POSIX regular expression; see
+ .
+
+ substring('Thomas' from '...$')
+ mas
- substring('Thomas' from '...$')
- mas
- substring(string from pattern for escape)
- text
-
- Extract substring matching SQL regular expression
- (see for more information on
- pattern matching)
+
+ substring ( string text FROM pattern text FOR escape text )
+ text
+
+ Extracts substring matching SQL regular expression;
+ see .
+
+ substring('Thomas' from '%#"o_a#"_' for '#')
+ oma
- substring('Thomas' from '%#"o_a#"_' for '#')
- oma
-
+
trim
- trim(leading | trailing | both
- characters from
- string)
-
- text
-
- Remove the longest string containing only characters in
+ trim ( LEADING | TRAILING | BOTH
+ characters text FROM
+ string text )
+ text
+
+ Removes the longest string containing only characters in
characters (a space by default) from the
- start, end, or both ends (both is the default)
- of string
+ start, end, or both ends (BOTH is the default)
+ of string.
+
+ trim(both 'xyz' from 'yxTomxx')
+ Tom
- trim(both 'xyz' from 'yxTomxx')
- Tom
-
- trim(leading | trailing
- | both from
- string ,
- characters)
+
+ trim ( LEADING | TRAILING | BOTH FROM
+ string text ,
+ characters text )
+ text
+
+ This is a non-standard syntax for trim().
+
+ trim(both from 'yxTomxx', 'xyz')
+ Tom
- text
-
- Non-standard syntax for trim()
-
- trim(both from 'yxTomxx', 'xyz')
- Tom
-
+
upper
- upper(string)
+ upper ( text )
+ text
+
+ Converts the string to all upper case, according to the rules of the
+ database's locale.
+
+ upper('tom')
+ TOM
- text
- Convert string to upper case
- upper('tom')
- TOM
@@ -2380,7 +2429,7 @@ repeat('Pg', 4) PgPgPgPg
, characters text )
text
- Removes the longest string consisting only of characters
+ Removes the longest string containing only characters
in characters (a space by default)
from the start and end of string.
@@ -2912,7 +2961,7 @@ repeat('Pg', 4) PgPgPgPg
strpos ( string text, substring text )
integer
- Returns location of specified substring
+ Returns starting index of specified substring
within string, or zero if it's not present.
(Same as position(substring in
string), but note the reversed
@@ -2932,7 +2981,8 @@ repeat('Pg', 4) PgPgPgPg
)
text
- Extracts substring starting at index start,
+ Extracts the substring of string starting at
+ the start'th character,
and extending for count characters if that is
specified. (Same
as substring(string