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.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 99f5311fd2d62bb6f21db3c1e68dbde2c848cf6f..6aaf454b4c803ee52c6335bf0836047bf35ef766 100644 (file)
--- 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
-    5">
+    1">
      
       
-       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 
-       
-        String concatenation with one non-string input
+       
+        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
        
-       'Value: ' || 42
-       Value: 42
       
 
       
-       
+        role="functableentry">
         
          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
       
 
       
-       
+        role="functableentry">
         
          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
       
 
       
-       
+        role="functableentry">
         
          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
       
 
       
-       
+        role="functableentry">
         
          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
       
 
       
-       
+        role="functableentry">
         
          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.
+      
+
+      
+       
+        
+         octet_length
+        
+        octet_length ( text )
+        integer
+       
+        Returns number of bytes in the string.
+       
+        octet_length('josé')
+        5 (if server encoding is UTF8)
        
-       normalize(U&'\0061\0308bc', NFC)
-       U&'\00E4bc'
       
 
       
-       
+        role="functableentry">
         
          octet_length
         
-        octet_length(string)
+        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
        
-       int
-       Number of bytes in string
-       octet_length('jose')
-       4
       
 
       
-       
+        role="functableentry">
         
          overlay
         
-        overlay(string placing string from int for int)
-       
-       text
-       
-        Replace substring
+        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
        
-       overlay('Txxxxas' placing 'hom' from 2 for 4)
-       Thomas
       
 
       
-       
+        role="functableentry">
         
          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
       
 
       
-       
+        role="functableentry">
         
          substring
         
-        substring(string from int for int)
-       
-       text
-       
-        Extract substring (provide at least one of from
-        and for)
+        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
        
-       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
       
 
       
-       
+        role="functableentry">
         
          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)
-       
-       text
-       
-        Non-standard syntax for trim()
+       
+        trim (  LEADING | TRAILING | BOTH   FROM 
+        string text ,
+        characters text  )
+        text
+       
+        This is a non-standard syntax for trim().
+       
+        trim(both from 'yxTomxx', 'xyz')
+        Tom
        
-       trim(both from 'yxTomxx', 'xyz')
-       Tom
       
 
       
-       
+        role="functableentry">
         
          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