Skip to content

P
Postgres FD Implementation
Commit 9aece5cd authored by Tom Lane's avatar Tom Lane
Browse files
Options

Doc: update the rest of section 9.4 for new function table layout. 

Notably, this replaces the previous handwaving about these functions'
behavior with "character"-type inputs with some actual facts.
parent 0cacb2b7
Show whitespace changes
Inline Side-by-side
Showing with 200 additions and 150 deletions
doc/src/sgml/func.sgml
View file @ 9aece5cd
...@@ -2030,10 +2030,12 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue> ...@@ -2030,10 +2030,12 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
This section describes functions and operators for examining and This section describes functions and operators for examining and
manipulating string values. Strings in this context include values manipulating string values. Strings in this context include values
of the types <type>character</type>, <type>character varying</type>, of the types <type>character</type>, <type>character varying</type>,
and <type>text</type>. Unless otherwise noted, all and <type>text</type>. Except where noted, these functions and operators
of the functions listed below work on all of these types, but be are declared to accept and return type <type>text</type>. They will
wary of potential effects of automatic space-padding when using the interchangeably accept <type>character varying</type> arguments.
<type>character</type> type. Values of type <type>character</type> will be converted
to <type>text</type> before the function or operator is applied, resulting
in stripping any trailing spaces in the <type>character</type> value.
</para> </para>
<para> <para>
...@@ -2062,96 +2064,94 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue> ...@@ -2062,96 +2064,94 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<table id="functions-string-sql"> <table id="functions-string-sql">
<title><acronym>SQL</acronym> String Functions and Operators</title> <title><acronym>SQL</acronym> String Functions and Operators</title>
<tgroup cols="5"> <tgroup cols="1">
<thead> <thead>
<row> <row>
<entry>Function</entry> <entry role="functableentry">
<entry>Return Type</entry> Function/Operator<?br?>Description<?br?>Example(s)
<entry>Description</entry> </entry>
<entry>Example</entry>
<entry>Result</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry><literal><parameter>string</parameter> <literal>||</literal> <entry role="functableentry">
<parameter>string</parameter></literal></entry>
<entry> <type>text</type> </entry>
<entry>
String concatenation
<indexterm> <indexterm>
<primary>character string</primary> <primary>character string</primary>
<secondary>concatenation</secondary> <secondary>concatenation</secondary>
</indexterm> </indexterm>
<type>text</type> <literal>||</literal> <type>text</type>
<returnvalue>text</returnvalue>
<?br?>
Concatenates the two strings.
<?br?>
<literal>'Post' || 'greSQL'</literal>
<returnvalue>PostgreSQL</returnvalue>
</entry> </entry>
<entry><literal>'Post' || 'greSQL'</literal></entry>
<entry><literal>PostgreSQL</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<literal><parameter>string</parameter> <literal>||</literal> <type>text</type> <literal>||</literal> <type>anynonarray</type>
<parameter>non-string</parameter></literal> or <type>anynonarray</type> <literal>||</literal> <type>text</type>
or <returnvalue>text</returnvalue>
<literal><parameter>non-string</parameter> <literal>||</literal> <?br?>
<parameter>string</parameter></literal> Converts the non-string input to text, then concatenates the two
</entry> strings. (The non-string input cannot be of an array type, because
<entry> <type>text</type> </entry> that would create ambiguity with the array <literal>||</literal>
<entry> operators. If you want to concatenate an array's text equivalent,
String concatenation with one non-string input cast it to <type>text</type> explicitly.)
<?br?>
<literal>'Value: ' || 42</literal>
<returnvalue>Value: 42</returnvalue>
</entry> </entry>
<entry><literal>'Value: ' || 42</literal></entry>
<entry><literal>Value: 42</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>normalized</primary> <primary>normalized</primary>
</indexterm> </indexterm>
<indexterm> <indexterm>
<primary>Unicode normalization</primary> <primary>Unicode normalization</primary>
</indexterm> </indexterm>
<literal><parameter>string</parameter> is <optional>not</optional> <optional><parameter>form</parameter></optional> normalized</literal> <type>text</type> <literal>IS</literal> <optional><literal>NOT</literal></optional> <optional><parameter>form</parameter></optional> <literal>NORMALIZED</literal>
</entry> <returnvalue>boolean</returnvalue>
<entry><type>boolean</type></entry> <?br?>
<entry>
Checks whether the string is in the specified Unicode normalization Checks whether the string is in the specified Unicode normalization
form. The optional parameter specifies the form: form. The optional <parameter>form</parameter> key word specifies the
<literal>NFC</literal> (default), <literal>NFD</literal>, form: <literal>NFC</literal> (the default), <literal>NFD</literal>,
<literal>NFKC</literal>, <literal>NFKD</literal>. This expression can <literal>NFKC</literal>, or <literal>NFKD</literal>. This expression can
only be used if the server encoding is <literal>UTF8</literal>. Note only be used when the server encoding is <literal>UTF8</literal>. Note
that checking for normalization using this expression is often faster that checking for normalization using this expression is often faster
than normalizing possibly already normalized strings. than normalizing possibly already normalized strings.
<?br?>
<literal>U&amp;'\0061\0308bc' IS NFD NORMALIZED</literal>
<returnvalue>t</returnvalue>
</entry> </entry>
<entry><literal>U&amp;'\0061\0308bc' IS NFD NORMALIZED</literal></entry>
<entry><literal>true</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>bit_length</primary> <primary>bit_length</primary>
</indexterm> </indexterm>
<literal><function>bit_length(<parameter>string</parameter>)</function></literal> <function>bit_length</function> ( <type>text</type> )
<returnvalue>integer</returnvalue>
<?br?>
Returns number of bits in the string (8
times the <function>octet_length</function>).
<?br?>
<literal>bit_length('jose')</literal>
<returnvalue>32</returnvalue>
</entry> </entry>
<entry><type>int</type></entry>
<entry>Number of bits in string</entry>
<entry><literal>bit_length('jose')</literal></entry>
<entry><literal>32</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>char_length</primary> <primary>char_length</primary>
</indexterm> </indexterm>
<literal><function>char_length(<parameter>string</parameter>)</function></literal> or <literal><function>character_length(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>int</type></entry>
<entry>
Number of characters in string
<indexterm> <indexterm>
<primary>character string</primary> <primary>character string</primary>
<secondary>length</secondary> <secondary>length</secondary>
...@@ -2161,175 +2161,224 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue> ...@@ -2161,175 +2161,224 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<secondary sortas="character string">of a character string</secondary> <secondary sortas="character string">of a character string</secondary>
<see>character string, length</see> <see>character string, length</see>
</indexterm> </indexterm>
<function>char_length</function> ( <type>text</type> )
or <function>character_length</function> ( <type>text</type> )
<returnvalue>integer</returnvalue>
<?br?>
Returns number of characters in the string.
<?br?>
<literal>char_length('jos&eacute;')</literal>
<returnvalue>4</returnvalue>
</entry> </entry>
<entry><literal>char_length('jose')</literal></entry>
<entry><literal>4</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>lower</primary> <primary>lower</primary>
</indexterm> </indexterm>
<literal><function>lower(<parameter>string</parameter>)</function></literal> <function>lower</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
<?br?>
Converts the string to all lower case, according to the rules of the
database's locale.
<?br?>
<literal>lower('TOM')</literal>
<returnvalue>tom</returnvalue>
</entry> </entry>
<entry><type>text</type></entry>
<entry>Convert string to lower case</entry>
<entry><literal>lower('TOM')</literal></entry>
<entry><literal>tom</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>normalize</primary> <primary>normalize</primary>
</indexterm> </indexterm>
<indexterm> <indexterm>
<primary>Unicode normalization</primary> <primary>Unicode normalization</primary>
</indexterm> </indexterm>
<literal><function>normalize(<parameter>string</parameter> <type>text</type> <function>normalize</function> ( <type>text</type>
<optional>, <parameter>form</parameter> </optional>)</function></literal> <optional>, <parameter>form</parameter> </optional> )
<returnvalue>text</returnvalue>
<?br?>
Converts the string to the specified Unicode
normalization form. The optional <parameter>form</parameter> key word
specifies the form: <literal>NFC</literal> (the default),
<literal>NFD</literal>, <literal>NFKC</literal>, or
<literal>NFKD</literal>. This function can only be used when the
server encoding is <literal>UTF8</literal>.
<?br?>
<literal>normalize(U&amp;'\0061\0308bc', NFC)</literal>
<returnvalue>U&amp;'\00E4bc'</returnvalue>
</entry> </entry>
<entry><type>text</type></entry> </row>
<entry>
Converts the string in the first argument to the specified Unicode <row>
normalization form. The optional second argument specifies the form <entry role="functableentry">
as an identifier: <literal>NFC</literal> (default), <indexterm>
<literal>NFD</literal>, <literal>NFKC</literal>, <primary>octet_length</primary>
<literal>NFKD</literal>. This function can only be used if the server </indexterm>
encoding is <literal>UTF8</literal>. <function>octet_length</function> ( <type>text</type> )
<returnvalue>integer</returnvalue>
<?br?>
Returns number of bytes in the string.
<?br?>
<literal>octet_length('jos&eacute;')</literal>
<returnvalue>5</returnvalue> (if server encoding is UTF8)
</entry> </entry>
<entry><literal>normalize(U&amp;'\0061\0308bc', NFC)</literal></entry>
<entry><literal>U&amp;'\00E4bc'</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>octet_length</primary> <primary>octet_length</primary>
</indexterm> </indexterm>
<literal><function>octet_length(<parameter>string</parameter>)</function></literal> <function>octet_length</function> ( <type>character</type> )
<returnvalue>integer</returnvalue>
<?br?>
Returns number of bytes in the string. Since this version of the
function accepts type <type>character</type> directly, it will not
strip trailing spaces.
<?br?>
<literal>octet_length('abc '::character(4))</literal>
<returnvalue>4</returnvalue>
</entry> </entry>
<entry><type>int</type></entry>
<entry>Number of bytes in string</entry>
<entry><literal>octet_length('jose')</literal></entry>
<entry><literal>4</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>overlay</primary> <primary>overlay</primary>
</indexterm> </indexterm>
<literal><function>overlay(<parameter>string</parameter> placing <parameter>string</parameter> from <type>int</type> <optional>for <type>int</type></optional>)</function></literal> <function>overlay</function> ( <parameter>string</parameter> <type>text</type> <literal>PLACING</literal> <parameter>newsubstring</parameter> <type>text</type> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
</entry> <returnvalue>text</returnvalue>
<entry><type>text</type></entry> <?br?>
<entry> Replaces the substring of <parameter>string</parameter> that starts at
Replace substring the <parameter>start</parameter>'th character and extends
for <parameter>count</parameter> characters
with <parameter>newsubstring</parameter>.
If <parameter>count</parameter> is omitted, it defaults to the length
of <parameter>newsubstring</parameter>.
<?br?>
<literal>overlay('Txxxxas' placing 'hom' from 2 for 4)</literal>
<returnvalue>Thomas</returnvalue>
</entry> </entry>
<entry><literal>overlay('Txxxxas' placing 'hom' from 2 for 4)</literal></entry>
<entry><literal>Thomas</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>position</primary> <primary>position</primary>
</indexterm> </indexterm>
<literal><function>position(<parameter>substring</parameter> in <parameter>string</parameter>)</function></literal> <function>position</function> ( <parameter>substring</parameter> <type>text</type> <literal>IN</literal> <parameter>string</parameter> <type>text</type> )
<returnvalue>integer</returnvalue>
<?br?>
Returns starting index of specified <parameter>substring</parameter>
within <parameter>string</parameter>, or zero if it's not present.
<?br?>
<literal>position('om' in 'Thomas')</literal>
<returnvalue>3</returnvalue>
</entry> </entry>
<entry><type>int</type></entry>
<entry>Location of specified substring</entry>
<entry><literal>position('om' in 'Thomas')</literal></entry>
<entry><literal>3</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>substring</primary> <primary>substring</primary>
</indexterm> </indexterm>
<literal><function>substring(<parameter>string</parameter> <optional>from <type>int</type></optional> <optional>for <type>int</type></optional>)</function></literal> <function>substring</function> ( <parameter>string</parameter> <type>text</type> <optional> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> </optional> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
</entry> <returnvalue>text</returnvalue>
<entry><type>text</type></entry> <?br?>
<entry> Extracts the substring of <parameter>string</parameter> starting at
Extract substring (provide at least one of <literal>from</literal> the <parameter>start</parameter>'th character if that is specified,
and <literal>for</literal>) and stopping after <parameter>count</parameter> characters if that is
specified. Provide at least one of <parameter>start</parameter>
and <parameter>count</parameter>.
<?br?>
<literal>substring('Thomas' from 2 for 3)</literal>
<returnvalue>hom</returnvalue>
<?br?>
<literal>substring('Thomas' from 3)</literal>
<returnvalue>omas</returnvalue>
<?br?>
<literal>substring('Thomas' for 2)</literal>
<returnvalue>Th</returnvalue>
</entry> </entry>
<entry><literal>substring('Thomas' from 2 for 3)</literal></entry>
<entry><literal>hom</literal></entry>
</row> </row>
<row> <row>
<entry><literal><function>substring(<parameter>string</parameter> from <replaceable>pattern</replaceable>)</function></literal></entry> <entry role="functableentry">
<entry><type>text</type></entry> <function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>FROM</literal> <replaceable>pattern</replaceable> <type>text</type> )
<entry> <returnvalue>text</returnvalue>
Extract substring matching POSIX regular expression (see <?br?>
<xref linkend="functions-matching"/> for more information on pattern Extracts substring matching POSIX regular expression; see
matching) <xref linkend="functions-posix-regexp"/>.
<?br?>
<literal>substring('Thomas' from '...$')</literal>
<returnvalue>mas</returnvalue>
</entry> </entry>
<entry><literal>substring('Thomas' from '...$')</literal></entry>
<entry><literal>mas</literal></entry>
</row> </row>
<row> <row>
<entry><literal><function>substring(<parameter>string</parameter> from <replaceable>pattern</replaceable> for <replaceable>escape</replaceable>)</function></literal></entry> <entry role="functableentry">
<entry><type>text</type></entry> <function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>FROM</literal> <replaceable>pattern</replaceable> <type>text</type> <literal>FOR</literal> <replaceable>escape</replaceable> <type>text</type> )
<entry> <returnvalue>text</returnvalue>
Extract substring matching <acronym>SQL</acronym> regular expression <?br?>
(see <xref linkend="functions-matching"/> for more information on Extracts substring matching <acronym>SQL</acronym> regular expression;
pattern matching) see <xref linkend="functions-similarto-regexp"/>.
<?br?>
<literal>substring('Thomas' from '%#"o_a#"_' for '#')</literal>
<returnvalue>oma</returnvalue>
</entry> </entry>
<entry><literal>substring('Thomas' from '%#"o_a#"_' for '#')</literal></entry>
<entry><literal>oma</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>trim</primary> <primary>trim</primary>
</indexterm> </indexterm>
<literal><function>trim(<optional>leading | trailing | both</optional> <function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <literal>BOTH</literal> </optional>
<optional><parameter>characters</parameter></optional> from <optional> <parameter>characters</parameter> <type>text</type> </optional> <literal>FROM</literal>
<parameter>string</parameter>)</function></literal> <parameter>string</parameter> <type>text</type> )
</entry> <returnvalue>text</returnvalue>
<entry><type>text</type></entry> <?br?>
<entry> Removes the longest string containing only characters in
Remove the longest string containing only characters in
<parameter>characters</parameter> (a space by default) from the <parameter>characters</parameter> (a space by default) from the
start, end, or both ends (<literal>both</literal> is the default) start, end, or both ends (<literal>BOTH</literal> is the default)
of <parameter>string</parameter> of <parameter>string</parameter>.
<?br?>
<literal>trim(both 'xyz' from 'yxTomxx')</literal>
<returnvalue>Tom</returnvalue>
</entry> </entry>
<entry><literal>trim(both 'xyz' from 'yxTomxx')</literal></entry>
<entry><literal>Tom</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<literal><function>trim(<optional>leading | trailing <function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <literal>BOTH</literal> </optional> <optional> <literal>FROM</literal> </optional>
| both</optional> <optional>from</optional> <parameter>string</parameter> <type>text</type> <optional>,
<parameter>string</parameter> <optional>, <parameter>characters</parameter> <type>text</type> </optional> )
<parameter>characters</parameter></optional>)</function></literal> <returnvalue>text</returnvalue>
</entry> <?br?>
<entry><type>text</type></entry> This is a non-standard syntax for <function>trim()</function>.
<entry> <?br?>
Non-standard syntax for <function>trim()</function> <literal>trim(both from 'yxTomxx', 'xyz')</literal>
<returnvalue>Tom</returnvalue>
</entry> </entry>
<entry><literal>trim(both from 'yxTomxx', 'xyz')</literal></entry>
<entry><literal>Tom</literal></entry>
</row> </row>
<row> <row>
<entry> <entry role="functableentry">
<indexterm> <indexterm>
<primary>upper</primary> <primary>upper</primary>
</indexterm> </indexterm>
<literal><function>upper(<parameter>string</parameter>)</function></literal> <function>upper</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
<?br?>
Converts the string to all upper case, according to the rules of the
database's locale.
<?br?>
<literal>upper('tom')</literal>
<returnvalue>TOM</returnvalue>
</entry> </entry>
<entry><type>text</type></entry>
<entry>Convert string to upper case</entry>
<entry><literal>upper('tom')</literal></entry>
<entry><literal>TOM</literal></entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
...@@ -2380,7 +2429,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue> ...@@ -2380,7 +2429,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<optional>, <parameter>characters</parameter> <type>text</type> </optional> ) <optional>, <parameter>characters</parameter> <type>text</type> </optional> )
<returnvalue>text</returnvalue> <returnvalue>text</returnvalue>
<?br?> <?br?>
Removes the longest string consisting only of characters Removes the longest string containing only characters
in <parameter>characters</parameter> (a space by default) in <parameter>characters</parameter> (a space by default)
from the start and end of <parameter>string</parameter>. from the start and end of <parameter>string</parameter>.
<?br?> <?br?>
...@@ -2912,7 +2961,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue> ...@@ -2912,7 +2961,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<function>strpos</function> ( <parameter>string</parameter> <type>text</type>, <parameter>substring</parameter> <type>text</type> ) <function>strpos</function> ( <parameter>string</parameter> <type>text</type>, <parameter>substring</parameter> <type>text</type> )
<returnvalue>integer</returnvalue> <returnvalue>integer</returnvalue>
<?br?> <?br?>
Returns location of specified <parameter>substring</parameter> Returns starting index of specified <parameter>substring</parameter>
within <parameter>string</parameter>, or zero if it's not present. within <parameter>string</parameter>, or zero if it's not present.
(Same as <literal>position(<parameter>substring</parameter> in (Same as <literal>position(<parameter>substring</parameter> in
<parameter>string</parameter>)</literal>, but note the reversed <parameter>string</parameter>)</literal>, but note the reversed
...@@ -2932,7 +2981,8 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue> ...@@ -2932,7 +2981,8 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<type></type> ) <type></type> )
<returnvalue>text</returnvalue> <returnvalue>text</returnvalue>
<?br?> <?br?>
Extracts substring starting at index <parameter>start</parameter>, Extracts the substring of <parameter>string</parameter> starting at
the <parameter>start</parameter>'th character,
and extending for <parameter>count</parameter> characters if that is and extending for <parameter>count</parameter> characters if that is
specified. (Same specified. (Same
as <literal>substring(<parameter>string</parameter> as <literal>substring(<parameter>string</parameter>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment