Doc: update sections 9.5 and 9.6 for new function table layout.

Along the way, update the older examples for bytea to use "hex"
output format.  That lets us get rid of the lame disclaimer about
how the examples assume bytea_output = escape, which was only half
true anyway because none of the more-recently-added examples had
paid any attention to that.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6aaf454b4c803ee52c6335bf0836047bf35ef766..ca91c7f9154fdf1396d8a40fef2e9c5c694dc18e 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2978,7 +2978,6 @@ repeat('Pg', 4) PgPgPgPg
          substr
         
         substr ( string text, start integer , count integer  )
- )
         text
        
         Extracts the substring of string starting at
@@ -3335,146 +3334,151 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
     (see ).
    
 
-   
-    
-     The sample results shown on this page assume that the server parameter
-     bytea_output is set
-     to escape (the traditional PostgreSQL format).
-     The output will look different when using the default setting
-     (hex).
-    
-   
-
    
     <acronym>SQL</acronym> Binary String Functions and Operators
-    5">
+    1">
      
       
-       Function
-       Return Type
-       Description
-       Example
-       Result
+       
+        Function/OperatorDescriptionExample(s)
+       
       
      
 
      
       
-       bytes ||
-        bytes
-        bytea 
-       
-        Binary string concatenation
+       
         
          binary string
          concatenation
         
+        bytea || bytea
+        bytea
+       
+        Concatenates the two binary strings.
+       
+        '\x123456'::bytea || '\x789a00bcde'::bytea
+        \x123456789a00bcde
        
-       '\\Post'::bytea || '\047gres\000'::bytea
-       \\Post'gres\000
       
 
       
-       
+        role="functableentry">
         
          bit_length
         
-        bit_length(bytes)
+        bit_length ( bytea )
+        integer
+       
+        Returns number of bits in the binary string (8
+        times the octet_length).
+       
+        bit_length('\x123456'::bytea)
+        24
        
-       int
-       Number of bits in binary string
-       bit_length('jo\000se':bytea)
-       40
       
 
       
-       
+        role="functableentry">
         
          octet_length
         
-        octet_length(bytes)
+        octet_length ( bytea )
+        integer
+       
+        Returns number of bytes in the binary string.
+       
+        octet_length('\x123456'::bytea)
+        3
        
-       int
-       Number of bytes in binary string
-       octet_length('jo\000se'::bytea)
-       5
       
 
       
-       
+        role="functableentry">
         
          overlay
         
-        overlay(bytes placing bytes from int for int)
-       
-       bytea
-       
-        Replace substring
+        overlay ( bytes bytea PLACING newsubstring bytea FROM start integer  FOR count integer  )
+        bytea
+       
+        Replaces the substring of bytes that starts at
+        the start'th byte and extends
+        for count bytes
+        with newsubstring.
+        If count is omitted, it defaults to the length
+        of newsubstring.
+       
+        overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)
+        \x12020390
        
-       overlay('Th\000omas'::bytea placing '\002\003'::bytea from 2 for 3)
-       T\\002\\003mas
       
 
       
-       
+        role="functableentry">
         
          position
         
-        position(bytesubstring in bytes)
+        position ( substring bytea IN bytes bytea )
+        integer
+       
+        Returns starting index of specified substring
+        within bytes, or zero if it's not present.
+       
+        position('\x5678'::bytea in '\x1234567890'::bytea)
+        3
        
-       int
-       Location of specified substring
-      position('\000om'::bytea in 'Th\000omas'::bytea)
-       3
       
 
       
-       
+        role="functableentry">
         
          substring
         
-        substring(bytes from int for int)
-       
-       bytea
-       
-        Extract substring (provide at least one of from
-        and for)
+        substring ( bytes bytea  FROM start integer   FOR count integer  )
+        bytea
+       
+        Extracts the substring of bytes starting at
+        the start'th byte if that is specified,
+        and stopping after count bytes if that is
+        specified.  Provide at least one of start
+        and count.
+       
+        substring('\x1234567890'::bytea from 3 for 2)
+        \x5678
        
-       substring('Th\000omas'::bytea from 2 for 3)
-       h\000o
       
 
       
-       
+        role="functableentry">
         
          trim
         
-        trim(both
-        bytesremoved from
-        bytes)
-       
-       bytea
-       
-        Remove the longest string containing only bytes appearing in
+        trim (  BOTH 
+        bytesremoved bytea FROM
+        bytes bytea )
+        bytea
+       
+        Removes the longest string containing only bytes appearing in
         bytesremoved from the start
-        and end of bytes
+        and end of bytes.
+       
+        trim('\x9012'::bytea from '\x1234567890'::bytea)
+        \x345678
        
-       trim('\000\001'::bytea from '\000Tom\001'::bytea)
-       Tom
       
 
       
-       
-        trim(both from
-        bytes,
-        bytesremoved)
-       
-       bytea
-       
-        Non-standard syntax for trim()
+       
+        trim (  BOTH   FROM 
+        bytes bytea,
+        bytesremoved bytea )
+        bytea
+       
+        This is a non-standard syntax for trim().
+       
+        trim(both from '\x1234567890'::bytea, '\x9012'::bytea)
+        \x345678
        
-       trim(both from 'yxTomxx'::bytea, 'xyz'::bytea)
-       Tom
       
      
     
@@ -3490,78 +3494,73 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
 
    
     Other Binary String Functions
-    5">
+    1">
      
       
-       Function
-       Return Type
-       Description
-       Example
-       Result
+       
+        FunctionDescriptionExample(s)
+       
       
      
 
      
       
-       
+        role="functableentry">
         
          btrim
         
-        btrim(bytes
-        bytea, bytesremoved bytea)
-       
-       bytea
-       
-        Remove the longest string containing only bytes appearing in
+        btrim ( bytes bytea,
+        bytesremoved bytea )
+        bytea
+       
+        Removes the longest string containing only bytes appearing in
         bytesremoved from the start and end of
-        bytes
-       
-      btrim('\000trim\001'::bytea, '\000\001'::bytea)
-      trim
+        bytes.
+       
+       btrim('\x1234567890'::bytea, '\x9012'::bytea)
+       \x345678
+      
      
 
       
-       
+        role="functableentry">
         
          get_bit
         
-        get_bit(bytes bytea, offset bigint)
-       
-       int
-       
-        Extract n'th bit
-        from binary string
+        get_bit ( bytes bytea,
+        n bigint )
+        integer
+       
+        Extracts n'th bit
+        from binary string.
+       
+        get_bit('\x1234567890'::bytea, 30)
+        1
        
-       get_bit('Th\000omas'::bytea, 45)
-       1
       
 
       
-       
+        role="functableentry">
         
          get_byte
         
-        get_byte(bytes bytea, offset int)
-       
-       int
-       
-        Extract n'th byte
-        from binary string
+        get_byte ( bytes bytea,
+        n integer )
+        integer
+       
+        Extracts n'th byte
+        from binary string.
+       
+        get_byte('\x1234567890'::bytea, 4)
+        144
        
-       get_byte('Th\000omas'::bytea, 4)
-       109
       
 
       
-       
+        role="functableentry">
         
          length
         
-        length(bytes bytea)
-       
-       int
-       
-        Number of bytes in binary string
         
          binary string
          length
@@ -3571,149 +3570,165 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
          of a binary string
          binary strings, length
         
+        length ( bytea )
+        integer
+       
+        Returns the number of bytes in the binary string.
+       
+        length('\x1234567890'::bytea)
+        5
        
-       length('jo\000se'::bytea)
-       5
       
 
       
-       length(bytes bytea,
-        encoding name)
-       int
-       
-        Number of characters in bytes, assuming
-        that it is text in the given encoding
+       
+        length ( bytes bytea,
+        encoding name )
+        integer
+       
+        Returns the number of characters in the binary string, assuming
+        that it is text in the given encoding.
+       
+        length('jose'::bytea, 'UTF8')
+        4
        
-       length('jose'::bytea, 'UTF8')
-       4
       
 
       
-       
+        role="functableentry">
         
          md5
         
-        md5(bytes bytea)
-       
-       text
-       
-        MD5 hash, with
-        the result written in hexadecimal
+        md5 ( bytea )
+        text
+       
+        Computes the MD5 hash of
+        the binary string, with the result written in hexadecimal.
+       
+        md5('Th\000omas'::bytea)
+        8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1
        
-       md5('Th\000omas'::bytea)
-       8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1
       
 
       
-       
+        role="functableentry">
         
          set_bit
         
-        set_bit(bytes bytea,
-        offset bigint,
-        newvalue int)
-       
-       bytea
-       
-        Set n'th bit in
-        binary string
+        set_bit ( bytes bytea,
+        n bigint,
+        newvalue integer )
+        bytea
+       
+        Sets n'th bit in
+        binary string to newvalue.
+       
+        set_bit('\x1234567890'::bytea, 30, 0)
+        \x1234563890
        
-       set_bit('Th\000omas'::bytea, 45, 0)
-       Th\000omAs
       
 
       
-       
+        role="functableentry">
         
          set_byte
         
-        set_byte(bytes bytea,
-        offset int,
-        newvalue int)
-       
-       bytea
-       
-        Set n'th byte in
-        binary string
+        set_byte ( bytes bytea,
+        n integer,
+        newvalue integer )
+        bytea
+       
+        Sets n'th byte in
+        binary string to newvalue.
+       
+        set_byte('\x1234567890'::bytea, 4, 64)
+        \x1234567840
        
-       set_byte('Th\000omas'::bytea, 4, 64)
-       Th\000o@as
       
 
       
-       
+        role="functableentry">
         
          sha224
         
-        sha224(bytes bytea)
-       
-       bytea
-       
-        SHA-224 hash
+        sha224 ( bytea )
+        bytea
+       
+        Computes the SHA-224 hash
+        of the binary string.
+       
+        sha224('abc'::bytea)
+        \x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7
        
-       sha224('abc'::bytea)
-       \x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7
       
 
       
-       
+        role="functableentry">
         
          sha256
         
-        sha256(bytes bytea)
-       
-       bytea
-       
-        SHA-256 hash
+        sha256 ( bytea )
+        bytea
+       
+        Computes the SHA-256 hash
+        of the binary string.
+       
+        sha256('abc'::bytea)
+        \xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad
        
-       sha256('abc'::bytea)
-       \xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad
       
 
       
-       
+        role="functableentry">
         
          sha384
         
-        sha384(bytes bytea)
-       
-       bytea
-       
-        SHA-384 hash
+        sha384 ( bytea )
+        bytea
+       
+        Computes the SHA-384 hash
+        of the binary string.
+       
+        sha384('abc'::bytea)
+        \xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7
        
-       sha384('abc'::bytea)
-       \xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7
       
 
       
-       
+        role="functableentry">
         
          sha512
         
-        sha512(bytes bytea)
-       
-       bytea
-       
-         SHA-512 hash
+        sha512 ( bytea )
+        bytea
+       
+        Computes the SHA-512 hash
+        of the binary string.
+       
+        sha512('abc'::bytea)
+        \xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f
        
-       sha512('abc'::bytea)
-       \xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f
       
 
       
-       
+        role="functableentry">
         
          substr
         
-        substr(bytes bytea, from int , count int)
-       
-       bytea
-       
-        Extract substring (same as
-        substring(bytea from from for count))
+        substr ( bytes bytea, start integer , count integer  )
+        bytea
+       
+        Extracts the substring of bytes starting at
+        the start'th byte,
+        and extending for count bytes if that is
+        specified.  (Same
+        as substring(bytes
+        from start
+        for count).)
+       
+        substr('\x1234567890'::bytea, 3, 2)
+        \x5678
        
-       substr('alphabet', 3, 2)
-       ph
       
     
    
@@ -3760,116 +3775,112 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
 
   
    Text/Binary String Conversion Functions
-   5">
+   1">
     
      
-      Function
-      Return Type
-      Description
-      Example
-      Result
+      
+       FunctionDescriptionExample(s)
+      
      
     
 
     
      
-      
+       role="functableentry">
        
         convert
        
-       <literal>convert(bytes bytea,
+       <function>convert ( bytes bytea,
        src_encoding name,
-       dest_encoding name)
-      
-      bytea
-      
-       Convert binary string representing text in
+       dest_encoding name )
+       bytea
+      
+       Converts a binary string representing text in
        encoding src_encoding
        to a binary string in encoding dest_encoding
        (see  for
-       available conversions)
+       available conversions).
+      
+       convert('text_in_utf8', 'UTF8', 'LATIN1')
+       \x746578745f696e5f75746638
       
-      convert('text_in_utf8', 'UTF8', 'LATIN1')
-      text_in_utf8 represented in Latin-1 encoding
      
 
      
-      
+       role="functableentry">
        
         convert_from
        
-       convert_from(bytes bytea,
-        src_encoding name)
-      
-      text
-      
-       Convert binary string representing text in
+       convert_from ( bytes bytea,
+       src_encoding name )
+       text
+      
+       Converts a binary string representing text in
        encoding src_encoding
        to text in the database encoding
        (see  for
-       available conversions)
+       available conversions).
+      
+       convert_from('text_in_utf8', 'UTF8')
+       text_in_utf8
       
-      convert_from('text_in_utf8', 'UTF8')
-      text_in_utf8 represented in the
-       database encoding
      
 
      
-      
+       role="functableentry">
        
         convert_to
        
-       convert_to(string text,
-        dest_encoding name)
-      
-      bytea
-      
-       Convert text (in the database encoding) to a binary
-       string encoded in encoding dest_encoding
+       convert_to ( string text,
+       dest_encoding name )
+       bytea
+      
+       Converts a text string (in the database encoding) to a
+       binary string encoded in encoding dest_encoding
        (see  for
-       available conversions)
+       available conversions).
+      
+       convert_to('some_text', 'UTF8')
+       \x736f6d655f74657874
       
-      convert_to('some text', 'UTF8')
-      some text represented in UTF8 encoding
      
 
      
-      
+       role="functableentry">
        
         encode
        
-       encode(bytes bytea,
-        format text)
-      
-      text
-      
-       Encode binary data into a textual representation; supported
+       encode ( bytes bytea,
+       format text )
+       text
+      
+       Encodes binary data into a textual representation; supported
        format values are:
        base64,
        escape,
-       hex
+       hex.
+      
+       encode('123\000\001', 'base64')
+       MTIzAAE=
       
-      encode('123\000\001', 'base64')
-      MTIzAAE=
      
 
      
-      
+       role="functableentry">
        
         decode
        
-       decode(string text,
-        format text)
-      
-      bytea
-      
-       Decode binary data from a textual representation given
-       in string; allowed
+       decode ( string text,
+       format text )
+       bytea
+      
+       Decodes binary data from a textual representation; supported
        format values are the same as
-       for encode
+       for encode.
+      
+       decode('MTIzAAE=', 'base64')
+       \x3132330001
       
-      decode('MTIzAAE=', 'base64')
-      \x3132330001
      
     
    
@@ -3963,102 +3974,281 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
    
     This section describes functions and operators for examining and
     manipulating bit strings, that is values of the types
-    bit and bit varying.  Aside from the
-    usual comparison operators, the operators
-    shown in  can be used.
-    Bit string operands of &, |,
-    and # must be of equal length.  When bit
-    shifting, the original length of the string is preserved, as shown
-    in the examples.
+    bit and bit varying.  (While only
+    type bit is mentioned in the tables, values of
+    type bit varying can be used interchangeably.)
+    Bit strings support the usual comparison operators shown in
+    , as well as the
+    operators shown in .
    
 
    
     Bit String Operators
-
-    
+    
      
       
-       Operator
-       Description
-       Example
-       Result
+       
+        OperatorDescriptionExample(s)
+       
       
      
 
      
       
-        || 
-       concatenation
-       B'10001' || B'011'
-       10001011
+       
+        bit || bit
+        bit
+       
+        Concatenation
+       
+        B'10001' || B'011'
+        10001011
+       
       
 
       
-        & 
-       bitwise AND
-       B'10001' & B'01101'
-       00001
+       
+        bit & bit
+        bit
+       
+        Bitwise AND (inputs must be of equal length)
+       
+        B'10001' & B'01101'
+        00001
+       
       
 
       
-        | 
-       bitwise OR
-       B'10001' | B'01101'
-       11101
+       
+        bit | bit
+        bit
+       
+        Bitwise OR (inputs must be of equal length)
+       
+        B'10001' | B'01101'
+        11101
+       
       
 
       
-        # 
-       bitwise XOR
-       B'10001' # B'01101'
-       11100
+       
+        bit # bit
+        bit
+       
+        Bitwise exclusive OR (inputs must be of equal length)
+       
+        B'10001' # B'01101'
+        11100
+       
       
 
       
-        ~ 
-       bitwise NOT
-       ~ B'10001'
-       01110
+       
+        ~ bit
+        bit
+       
+        Bitwise NOT
+       
+        ~ B'10001'
+        01110
+       
       
 
       
-        << 
-       bitwise shift left
-       B'10001' << 3
-       01000
+       
+        bit << integer
+        bit
+       
+        Bitwise shift left
+        (string length is preserved)
+       
+        B'10001' << 3
+        01000
+       
       
 
       
-        >> 
-       bitwise shift right
-       B'10001' >> 2
-       00100
+       
+        bit >> integer
+        bit
+       
+        Bitwise shift right
+        (string length is preserved)
+       
+        B'10001' >> 2
+        00100
+       
       
      
     
    
 
    
-    Some of the binary-string functions shown in
-     and
-     are also available
-    for bit strings, specifically:
-    length,
-    bit_length,
-    octet_length,
-    position,
-    substring,
-    overlay,
-    get_bit,
-    set_bit.
-    When working with a bit string, get_bit
-    and set_bit number the first
-    (leftmost) bit of the string as bit 0.
+    Some of the functions available for binary strings are also available
+    for bit strings, as shown in .
    
 
+   
+    Bit String Functions
+    
+     
+      
+       
+        FunctionDescriptionExample(s)
+       
+      
+     
+
+     
+      
+       
+        
+         bit_length
+        
+        bit_length ( bit )
+        integer
+       
+        Returns number of bits in the bit string.
+       
+        bit_length(B'10111')
+        5
+       
+      
+
+      
+       
+        
+         length
+        
+        
+         bit string
+         length
+        
+        length ( bit )
+        integer
+       
+        Returns number of bits in the bit string.
+       
+        length(B'10111')
+        5
+       
+      
+
+      
+       
+        
+         octet_length
+        
+        octet_length ( bit )
+        integer
+       
+        Returns number of bytes in the bit string.
+       
+        octet_length(B'1011111011')
+        2
+       
+      
+
+      
+       
+        
+         overlay
+        
+        overlay ( bits bit PLACING newsubstring bit FROM start integer  FOR count integer  )
+        bit
+       
+        Replaces the substring of bits that starts at
+        the start'th bit and extends
+        for count bits
+        with newsubstring.
+        If count is omitted, it defaults to the length
+        of newsubstring.
+       
+        overlay(B'01010101010101010' placing B'11111' from 2 for 3)
+        0111110101010101010
+       
+      
+
+      
+       
+        
+         position
+        
+        position ( substring bit IN bits bit )
+        integer
+       
+        Returns starting index of specified substring
+        within bits, or zero if it's not present.
+       
+        position(B'010' in B'000001101011')
+        8
+       
+      
+
+      
+       
+        
+         substring
+        
+        substring ( bits bit  FROM start integer   FOR count integer  )
+        bit
+       
+        Extracts the substring of bits starting at
+        the start'th bit if that is specified,
+        and stopping after count bits if that is
+        specified.  Provide at least one of start
+        and count.
+       
+        substring(B'110010111111' from 3 for 2)
+        00
+       
+      
+
+      
+       
+        
+         get_bit
+        
+        get_bit ( bits bit,
+        n integer )
+        integer
+       
+        Extracts n'th bit
+        from bit string; the first (leftmost) bit is bit 0.
+       
+        get_bit(B'101010101010101010', 6)
+        1
+       
+      
+
+      
+       
+        
+         set_bit
+        
+        set_bit ( bits bit,
+        n integer,
+        newvalue integer )
+        bit
+       
+        Sets n'th bit in
+        bit string to newvalue;
+        the first (leftmost) bit is bit 0.
+       
+        set_bit(B'101010101010101010', 6, 0)
+        101010001010101010
+       
+      
+     
+    
+   
+
    
     In addition, it is possible to cast integral values to and from type
     bit.
+    Casting an integer to bit(n) copies the rightmost
+    n bits.  Casting an integer to a bit string width wider
+    than the integer itself will sign-extend on the left.
     Some examples:
 
 44::bit(10)                    0000101100
@@ -4070,15 +4260,6 @@ cast(-44 as bit(12))           111111010100
     bit(1), and so will deliver only the least significant
     bit of the integer.
    
-
-    
-     
-      Casting an integer to bit(n) copies the rightmost
-      n bits.  Casting an integer to a bit string width wider
-      than the integer itself will sign-extend on the left.
-     
-    
-