postgres.git / summary / log / commit / refs

commit    523bb1de834e9c05fec0f0d85330cfa15a3000b7
Author:   Tom Lane <tgl@sss.pgh.pa.us>
Date:     Wed Nov 30 18:34:14 2016 +0000

    Doc: improve description of trim() and related functions.
    
    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


 doc/src/sgml/func.sgml | 33 +++++++++++++++++----------------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 79d25d84198..01e9489ddcf 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1306,11 +1306,12 @@
        </entry>
        <entry><type>text</type></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
-        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><literal>trim(both 'x' from 'xTomxx')</literal></entry>
+       <entry><literal>trim(both 'xyz' from 'yxTomxx')</literal></entry>
        <entry><literal>Tom</literal></entry>
       </row>
 
@@ -1319,14 +1320,14 @@
         <literal><function>trim(<optional>leading | trailing
         | both</optional> <optional>from</optional>
         <parameter>string</parameter>
-        <optional><parameter>, characters</parameter></optional>
+        <optional>, <parameter>characters</parameter></optional>
         )</function></literal>
        </entry>
        <entry><type>text</type></entry>
        <entry>
-        Non-standard version of <function>trim()</>
+        Non-standard syntax for <function>trim()</>
        </entry>
-       <entry><literal>trim(both from 'xTomxx', 'x')</literal></entry>
+       <entry><literal>trim(both from 'yxTomxx', 'xyz')</literal></entry>
        <entry><literal>Tom</literal></entry>
       </row>
 
@@ -1398,7 +1399,7 @@
         in <parameter>characters</parameter> (a space by default)
         from the start and end of <parameter>string</parameter>
        </entry>
-       <entry><literal>btrim('xyxtrimyyx', 'xy')</literal></entry>
+       <entry><literal>btrim('xyxtrimyyx', 'xyz')</literal></entry>
        <entry><literal>trim</literal></entry>
       </row>
 
@@ -1667,8 +1668,8 @@
         <parameter>characters</parameter> (a space by default) from the start of
         <parameter>string</parameter>
        </entry>
-       <entry><literal>ltrim('zzzytrim', 'xyz')</literal></entry>
-       <entry><literal>trim</literal></entry>
+       <entry><literal>ltrim('zzzytest', 'xyz')</literal></entry>
+       <entry><literal>test</literal></entry>
       </row>
 
       <row>
@@ -1950,8 +1951,8 @@
         <parameter>characters</parameter> (a space by default) from the end of
         <parameter>string</parameter>
        </entry>
-       <entry><literal>rtrim('trimxxxx', 'x')</literal></entry>
-       <entry><literal>trim</literal></entry>
+       <entry><literal>rtrim('testxxzx', 'xyz')</literal></entry>
+       <entry><literal>test</literal></entry>
       </row>
 
       <row>
@@ -3215,11 +3216,11 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
        </entry>
        <entry><type>bytea</type></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
         and end of <parameter>string</parameter>
        </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>
       </row>
      </tbody>
@@ -3258,11 +3259,11 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
        </entry>
        <entry><type>bytea</type></entry>
        <entry>
-        Remove the longest string consisting only of bytes
-        in <parameter>bytes</parameter> from the start and end of
+        Remove the longest string containing only bytes appearing in
+        <parameter>bytes</parameter> from the start and end of
         <parameter>string</parameter>
       </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>
      </row>
 


[parent: be0b98fc2164]