rdelaage/postgresql
1
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2024-10-01 20:41:20 +02:00
Code Issues Packages Projects Releases Wiki Activity

Doc: improve description of trim() and related functions.

Browse Source 
Per bug #14441 from Mark Pether, the documentation could be misread,
mainly because some of the examples failed to show what happens with
a multicharacter "characters to trim" string.  Also, while the text
description in most of these entries was fairly clear that the
"characters" argument is a set of characters not a substring to match,
some of them used variant wording that was a bit less clear.
trim() itself suffered from both deficiencies and was thus pretty
misinterpretable.

Also fix failure to explain which of LEADING/TRAILING/BOTH is the
default.

Discussion: https://postgr.es/m/20161130011710.6539.53657@wrigleys.postgresql.org
This commit is contained in:
Tom Lane 2016-11-30 13:34:14 -05:00
parent 6c1a257fc6
commit bb389ad8cd
1 changed files with 17 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
doc/src/sgml/func.sgml
View File

@ -1321,11 +1321,12 @@
</entry> </entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry> <entry>
Remove the longest string containing only the Remove the longest string containing only characters from
<parameter>characters</parameter> (a space by default) from the <parameter>characters</parameter> (a space by default) from the
start/end/both ends of the <parameter>string</parameter> start, end, or both ends (<literal>both</> is the default)
of <parameter>string</parameter>
</entry> </entry>
<entry><literal>trim(both 'x' from 'xTomxx')</literal></entry> <entry><literal>trim(both 'xyz' from 'yxTomxx')</literal></entry>
<entry><literal>Tom</literal></entry> <entry><literal>Tom</literal></entry>
</row> </row>
@ -1334,14 +1335,14 @@
<literal><function>trim(<optional>leading | trailing <literal><function>trim(<optional>leading | trailing
| both</optional> <optional>from</optional> | both</optional> <optional>from</optional>
<parameter>string</parameter> <parameter>string</parameter>
<optional><parameter>, characters</parameter></optional> <optional>, <parameter>characters</parameter></optional>
)</function></literal> )</function></literal>
</entry> </entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry> <entry>
Non-standard version of <function>trim()</> Non-standard syntax for <function>trim()</>
</entry> </entry>
<entry><literal>trim(both from 'xTomxx', 'x')</literal></entry> <entry><literal>trim(both from 'yxTomxx', 'xyz')</literal></entry>
<entry><literal>Tom</literal></entry> <entry><literal>Tom</literal></entry>
</row> </row>
@ -1413,7 +1414,7 @@
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>
</entry> </entry>
<entry><literal>btrim('xyxtrimyyx', 'xy')</literal></entry> <entry><literal>btrim('xyxtrimyyx', 'xyz')</literal></entry>
<entry><literal>trim</literal></entry> <entry><literal>trim</literal></entry>
</row> </row>
@ -1682,8 +1683,8 @@
<parameter>characters</parameter> (a space by default) from the start of <parameter>characters</parameter> (a space by default) from the start of
<parameter>string</parameter> <parameter>string</parameter>
</entry> </entry>
<entry><literal>ltrim('zzzytrim', 'xyz')</literal></entry> <entry><literal>ltrim('zzzytest', 'xyz')</literal></entry>
<entry><literal>trim</literal></entry> <entry><literal>test</literal></entry>
</row> </row>
<row> <row>
@ -1965,8 +1966,8 @@
<parameter>characters</parameter> (a space by default) from the end of <parameter>characters</parameter> (a space by default) from the end of
<parameter>string</parameter> <parameter>string</parameter>
</entry> </entry>
<entry><literal>rtrim('trimxxxx', 'x')</literal></entry> <entry><literal>rtrim('testxxzx', 'xyz')</literal></entry>
<entry><literal>trim</literal></entry> <entry><literal>test</literal></entry>
</row> </row>
<row> <row>
@ -3231,11 +3232,11 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
</entry> </entry>
<entry><type>bytea</type></entry> <entry><type>bytea</type></entry>
<entry> <entry>
Remove the longest string containing only the bytes in Remove the longest string containing only bytes appearing in
<parameter>bytes</parameter> from the start <parameter>bytes</parameter> from the start
and end of <parameter>string</parameter> and end of <parameter>string</parameter>
</entry> </entry>
<entry><literal>trim(E'\\000'::bytea from E'\\000Tom\\000'::bytea)</literal></entry> <entry><literal>trim(E'\\000\\001'::bytea from E'\\000Tom\\001'::bytea)</literal></entry>
<entry><literal>Tom</literal></entry> <entry><literal>Tom</literal></entry>
</row> </row>
</tbody> </tbody>
@ -3274,11 +3275,11 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
</entry> </entry>
<entry><type>bytea</type></entry> <entry><type>bytea</type></entry>
<entry> <entry>
Remove the longest string consisting only of bytes Remove the longest string containing only bytes appearing in
in <parameter>bytes</parameter> from the start and end of <parameter>bytes</parameter> from the start and end of
<parameter>string</parameter> <parameter>string</parameter>
</entry> </entry>
<entry><literal>btrim(E'\\000trim\\000'::bytea, E'\\000'::bytea)</literal></entry> <entry><literal>btrim(E'\\000trim\\001'::bytea, E'\\000\\001'::bytea)</literal></entry>
<entry><literal>trim</literal></entry> <entry><literal>trim</literal></entry>
</row> </row>