Tom Lane wrote:
> The discussion of bytea in section 8.4,
> http://developer.postgresql.org/pgdocs/postgres/datatype-binary.html
> is obsolete because it assumes that standard_conforming_strings is
> always OFF. It could be very much simpler and shorter if
> standard_conforming_strings were always ON, but that's not reality
> either. Anyone have an idea on how to rewrite it in a way that
> isn't awkward, incomprehensible, or both?
I added two "(assuming <varname>standard_conforming_strings</> is
<literal>off</>)" clauses in the bytea docs. Patch attached, sorry for
the new wrapping.
--
Bruce Momjian bruce@momjian.us
EnterpriseDB http://www.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/datatype.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v
retrieving revision 1.180
diff -c -c -r1.180 datatype.sgml
*** doc/src/sgml/datatype.sgml 23 Oct 2006 18:10:30 -0000 1.180
--- doc/src/sgml/datatype.sgml 23 Nov 2006 04:21:46 -0000
***************
*** 1097,1111 ****
</para>
<para>
! When entering <type>bytea</type> values, octets of certain values
! <emphasis>must</emphasis> be escaped (but all octet values
! <emphasis>can</emphasis> be escaped) when used as part of a string
! literal in an <acronym>SQL</acronym> statement. In general, to
! escape an octet, it is converted into the three-digit octal number
! equivalent of its decimal octet value, and preceded by two
! backslashes. <xref linkend="datatype-binary-sqlesc"> shows the
! characters that must be escaped, and gives the alternate escape
! sequences where applicable.
</para>
<table id="datatype-binary-sqlesc">
--- 1097,1113 ----
</para>
<para>
! When entering <type>bytea</type> values, octets of certain
! values <emphasis>must</emphasis> be escaped (but all octet
! values <emphasis>can</emphasis> be escaped) when used as part
! of a string literal in an <acronym>SQL</acronym> statement. In
! general, to escape an octet, it is converted into the three-digit
! octal number equivalent of its decimal octet value, and preceded
! by two backslashes (or one backslash if
! <varname>standard_conforming_strings</> is <literal>off</>).
! <xref linkend="datatype-binary-sqlesc"> shows the characters
! that must be escaped, and gives the alternate escape sequences
! where applicable.
</para>
<table id="datatype-binary-sqlesc">
***************
*** 1168,1191 ****
</para>
<para>
! The reason that you have to write so many backslashes, as shown in
! <xref linkend="datatype-binary-sqlesc">, is that an input string
! written as a string literal must pass through two parse phases in
! the <productname>PostgreSQL</productname> server. The first
! backslash of each pair is interpreted as an escape character by
! the string-literal parser and is therefore consumed, leaving the
! second backslash of the pair. The remaining backslash is then
! recognized by the <type>bytea</type> input function as starting
! either a three digit octal value or escaping another backslash.
! For example, a string literal passed to the server as
! <literal>'\\001'</literal> becomes <literal>\001</literal> after
! passing through the string-literal parser. The
! <literal>\001</literal> is then sent to the <type>bytea</type>
! input function, where it is converted to a single octet with a
! decimal value of 1. Note that the apostrophe character is not
! treated specially by <type>bytea</type>, so it follows the normal
! rules for string literals. (See also <xref
! linkend="sql-syntax-strings">.)
</para>
<para>
--- 1170,1194 ----
</para>
<para>
! The reason that you have to write so many backslashes, as shown
! in <xref linkend="datatype-binary-sqlesc">, is that an input
! string written as a string literal must pass through two parse
! phases in the <productname>PostgreSQL</productname> server.
! The first backslash of each pair is interpreted as an escape
! character by the string-literal parser (assuming
! <varname>standard_conforming_strings</> is <literal>off</>)
! and is therefore consumed, leaving the second backslash of the
! pair. The remaining backslash is then recognized by the
! <type>bytea</type> input function as starting either a three
! digit octal value or escaping another backslash. For example,
! a string literal passed to the server as <literal>'\\001'</literal>
! becomes <literal>\001</literal> after passing through the
! string-literal parser. The <literal>\001</literal> is then sent
! to the <type>bytea</type> input function, where it is converted
! to a single octet with a decimal value of 1. Note that the
! apostrophe character is not treated specially by <type>bytea</type>,
! so it follows the normal rules for string literals. (See also
! <xref linkend="sql-syntax-strings">.)
</para>
<para>