From 3e80d0d2e5a0f6a7a971ddcb6e38cc8f0079aed7 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 7 Jul 2011 19:34:24 -0400
Subject: [PATCH] Update examples for string-related functions.

In the example for decode(), show the bytea result in hex format,
since that's now the default.  Use an E'' string in the example for
quote_literal(), so that it works regardless of the
standard_conforming_strings setting.  On the functions-for-binary-strings
page, leave the examples as-is for readability, but add a note pointing out
that they are shown in escape format.  Per comments from Thom Brown.

Also, improve the description for encode() and decode() a tad.

Backpatch to 9.0, where bytea_output was introduced.
---
 doc/src/sgml/func.sgml | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 8f223d6891..0b6a9d9542 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1482,15 +1482,15 @@
          <primary>decode</primary>
         </indexterm>
         <literal><function>decode(<parameter>string</parameter> <type>text</type>,
-        <parameter>type</parameter> <type>text</type>)</function></literal>
+        <parameter>format</parameter> <type>text</type>)</function></literal>
        </entry>
        <entry><type>bytea</type></entry>
        <entry>
-        Decode binary data from <parameter>string</parameter> previously
-        encoded with <function>encode</>.  Parameter type is same as in <function>encode</>.
+        Decode binary data from textual representation in <parameter>string</>.
+        Options for <parameter>format</> are same as in <function>encode</>.
        </entry>
        <entry><literal>decode('MTIzAAE=', 'base64')</literal></entry>
-       <entry><literal>123\000\001</literal></entry>
+       <entry><literal>\x3132330001</literal></entry>
       </row>
 
       <row>
@@ -1499,13 +1499,13 @@
          <primary>encode</primary>
         </indexterm>
         <literal><function>encode(<parameter>data</parameter> <type>bytea</type>,
-        <parameter>type</parameter> <type>text</type>)</function></literal>
+        <parameter>format</parameter> <type>text</type>)</function></literal>
        </entry>
        <entry><type>text</type></entry>
        <entry>
-        Encode binary data to different representation.  Supported
-        types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
-        <literal>Escape</> merely outputs null bytes as <literal>\000</> and
+        Encode binary data into a textual representation.  Supported
+        formats are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
+        <literal>escape</> merely outputs null bytes as <literal>\000</> and
         doubles backslashes.
        </entry>
        <entry><literal>encode(E'123\\000\\001', 'base64')</literal></entry>
@@ -1707,7 +1707,7 @@
         <function>quote_nullable</function> is often more suitable.
         See also <xref linkend="plpgsql-quote-literal-example">.
        </entry>
-       <entry><literal>quote_literal('O\'Reilly')</literal></entry>
+       <entry><literal>quote_literal(E'O\'Reilly')</literal></entry>
        <entry><literal>'O''Reilly'</literal></entry>
       </row>
 
@@ -2859,6 +2859,14 @@
     (see <xref linkend="functions-binarystring-other">).
    </para>
 
+   <note>
+    <para>
+     The sample results shown on this page assume that the server parameter
+     <link linkend="guc-bytea-output"><varname>bytea_output</></link> is set
+     to <literal>escape</literal> (the traditional PostgreSQL format).
+    </para>
+   </note>
+
    <table id="functions-binarystring-sql">
     <title><acronym>SQL</acronym> Binary String Functions and Operators</title>
     <tgroup cols="5">
-- 
2.40.0