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[email protected]

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 2e64cc430c48bab1c34b168c8dfec74c851ebd5b..eca98dfd349b54bfdf8b78d929c5d78d0f0f1c48 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1534,11 +1534,12 @@
        
        text
        
-        Remove the longest string containing only the
+        Remove the longest string containing only characters from
         characters (a space by default) from the
-        start/end/both ends of the string
+        start, end, or both ends (both is the default)
+        of string
        
-       trim(both 'x' from 'xTomxx')
+       trim(both 'xyz' from 'yxTomxx')
        Tom
       
 
@@ -1547,14 +1548,14 @@
         trim(leading | trailing
         | both from
         string
-        , characters
+        , characters
         )
        
        text
        
-        Non-standard version of trim()
+        Non-standard syntax for trim()
        
-       trim(both from 'xTomxx', 'x')
+       trim(both from 'yxTomxx', 'xyz')
        Tom
       
 
@@ -1626,7 +1627,7 @@
         in characters (a space by default)
         from the start and end of string
        
-       btrim('xyxtrimyyx', 'xy')
+       btrim('xyxtrimyyx', 'xyz')
        trim
       
 
@@ -1895,8 +1896,8 @@
         characters (a space by default) from the start of
         string
        
-       ltrim('zzzytrim', 'xyz')
-       trim
+       ltrim('zzzytest', 'xyz')
+       test
       
 
       
@@ -2218,8 +2219,8 @@
         characters (a space by default) from the end of
         string
        
-       rtrim('trimxxxx', 'x')
-       trim
+       rtrim('testxxzx', 'xyz')
+       test
       
 
       
@@ -3484,11 +3485,11 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
        
        bytea
        
-        Remove the longest string containing only the bytes in
+        Remove the longest string containing only bytes appearing in
         bytes from the start
         and end of string
        
-       trim(E'\\000'::bytea from E'\\000Tom\\000'::bytea)
+       trim(E'\\000\\001'::bytea from E'\\000Tom\\001'::bytea)
        Tom
       
      
@@ -3527,11 +3528,11 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
        
        bytea
        
-        Remove the longest string consisting only of bytes
-        in bytes from the start and end of
+        Remove the longest string containing only bytes appearing in
+        bytes from the start and end of
         string
       
-      btrim(E'\\000trim\\000'::bytea, E'\\000'::bytea)
+      btrim(E'\\000trim\\001'::bytea, E'\\000\\001'::bytea)
       trim