database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-03 22:24:49 +03:00
Code

Update documentation for backslashes to mention escape string syntax

Browse Source 
more, and standard_conforming_strings less, because in the future non-E
strings will not treat backslashes specially.

Also use E'' strings where backslashes are used in examples. (The
existing examples would have drawn warnings.)

Backpatch to 8.2.X.
This commit is contained in:
Bruce Momjian 2007-01-30 22:29:40 +00:00
parent 08c17d6e56
commit e2d6898827
9 changed files with 82 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/src/sgml/array.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.52 2006/09/29 21:22:21 tgl Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.52.2.1 2007/01/30 22:29:40 momjian Exp $ -->
<sect1 id="arrays"> <sect1 id="arrays">
<title>Arrays</title> <title>Arrays</title>
@ -597,17 +597,17 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
</para> </para>
<para> <para>
As shown previously, when writing an array value you may write double As shown previously, when writing an array value you can write double
quotes around any individual array element. You <emphasis>must</> do so quotes around any individual array element. You <emphasis>must</> do so
if the element value would otherwise confuse the array-value parser. if the element value would otherwise confuse the array-value parser.
For example, elements containing curly braces, commas (or whatever the For example, elements containing curly braces, commas (or whatever the
delimiter character is), double quotes, backslashes, or leading or trailing delimiter character is), double quotes, backslashes, or leading or trailing
whitespace must be double-quoted. Empty strings and strings matching the whitespace must be double-quoted. Empty strings and strings matching the
word <literal>NULL</> must be quoted, too. To put a double quote or word <literal>NULL</> must be quoted, too. To put a double quote or
backslash in a backslash in a quoted array element value, use escape string syntax
quoted array element value, precede it with a backslash. Alternatively, you and precede it with a backslash. Alternatively, you can use
can use backslash-escaping to protect all data characters that would backslash-escaping to protect all data characters that would otherwise
otherwise be taken as array syntax. be taken as array syntax.
</para> </para>
<para> <para>
@ -625,16 +625,16 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
backslashes you need. For example, to insert a <type>text</> array backslashes you need. For example, to insert a <type>text</> array
value containing a backslash and a double quote, you'd need to write value containing a backslash and a double quote, you'd need to write
<programlisting> <programlisting>
INSERT ... VALUES ('{"\\\\","\\""}'); INSERT ... VALUES (E'{"\\\\","\\""}');
</programlisting> </programlisting>
The string-literal processor removes one level of backslashes, so that The escape string processor removes one level of backslashes, so that
what arrives at the array-value parser looks like <literal>{"\\","\""}</>. what arrives at the array-value parser looks like <literal>{"\\","\""}</>.
In turn, the strings fed to the <type>text</> data type's input routine In turn, the strings fed to the <type>text</> data type's input routine
become <literal>\</> and <literal>"</> respectively. (If we were working become <literal>\</> and <literal>"</> respectively. (If we were working
with a data type whose input routine also treated backslashes specially, with a data type whose input routine also treated backslashes specially,
<type>bytea</> for example, we might need as many as eight backslashes <type>bytea</> for example, we might need as many as eight backslashes
in the command to get one backslash into the stored array element.) in the command to get one backslash into the stored array element.)
Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) may be Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) can be
used to avoid the need to double backslashes. used to avoid the need to double backslashes.
</para> </para>
</note> </note>

46
doc/src/sgml/datatype.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.181 2006/11/23 04:27:33 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.181.2.1 2007/01/30 22:29:40 momjian Exp $ -->
<chapter id="datatype"> <chapter id="datatype">
<title id="datatype-title">Data Types</title> <title id="datatype-title">Data Types</title>
@ -1103,11 +1103,9 @@ SELECT b, char_length(b) FROM test2;
of a string literal in an <acronym>SQL</acronym> statement. In of a string literal in an <acronym>SQL</acronym> statement. In
general, to escape an octet, it is converted into the three-digit general, to escape an octet, it is converted into the three-digit
octal number equivalent of its decimal octet value, and preceded octal number equivalent of its decimal octet value, and preceded
by two backslashes (or one backslash if by two backslashes. <xref linkend="datatype-binary-sqlesc">
<varname>standard_conforming_strings</> is <literal>off</>). shows the characters that must be escaped, and gives the alternate
<xref linkend="datatype-binary-sqlesc"> shows the characters escape sequences where applicable.
that must be escaped, and gives the alternate escape sequences
where applicable.
</para> </para>
<table id="datatype-binary-sqlesc"> <table id="datatype-binary-sqlesc">
@ -1127,32 +1125,32 @@ SELECT b, char_length(b) FROM test2;
<row> <row>
<entry>0</entry> <entry>0</entry>
<entry>zero octet</entry> <entry>zero octet</entry>
<entry><literal>'\\000'</literal></entry> <entry><literal>E'\\000'</literal></entry>
<entry><literal>SELECT '\\000'::bytea;</literal></entry> <entry><literal>SELECT E'\\000'::bytea;</literal></entry>
<entry><literal>\000</literal></entry> <entry><literal>\000</literal></entry>
</row> </row>
<row> <row>
<entry>39</entry> <entry>39</entry>
<entry>single quote</entry> <entry>single quote</entry>
<entry><literal>'\''</literal> or <literal>'\\047'</literal></entry> <entry><literal>''''</literal> or <literal>E'\\047'</literal></entry>
<entry><literal>SELECT '\''::bytea;</literal></entry> <entry><literal>SELECT E'\''::bytea;</literal></entry>
<entry><literal>'</literal></entry> <entry><literal>'</literal></entry>
</row> </row>
<row> <row>
<entry>92</entry> <entry>92</entry>
<entry>backslash</entry> <entry>backslash</entry>
<entry><literal>'\\\\'</literal> or <literal>'\\134'</literal></entry> <entry><literal>E'\\\\'</literal> or <literal>E'\\134'</literal></entry>
<entry><literal>SELECT '\\\\'::bytea;</literal></entry> <entry><literal>SELECT E'\\\\'::bytea;</literal></entry>
<entry><literal>\\</literal></entry> <entry><literal>\\</literal></entry>
</row> </row>
<row> <row>
<entry>0 to 31 and 127 to 255</entry> <entry>0 to 31 and 127 to 255</entry>
<entry><quote>non-printable</quote> octets</entry> <entry><quote>non-printable</quote> octets</entry>
<entry><literal>'\\<replaceable>xxx'</></literal> (octal value)</entry> <entry><literal>E'\\<replaceable>xxx'</></literal> (octal value)</entry>
<entry><literal>SELECT '\\001'::bytea;</literal></entry> <entry><literal>SELECT E'\\001'::bytea;</literal></entry>
<entry><literal>\001</literal></entry> <entry><literal>\001</literal></entry>
</row> </row>
@ -1175,18 +1173,18 @@ SELECT b, char_length(b) FROM test2;
string written as a string literal must pass through two parse string written as a string literal must pass through two parse
phases in the <productname>PostgreSQL</productname> server. phases in the <productname>PostgreSQL</productname> server.
The first backslash of each pair is interpreted as an escape The first backslash of each pair is interpreted as an escape
character by the string-literal parser (assuming character by the string-literal parser (assuming escape string
<varname>standard_conforming_strings</> is <literal>off</>) syntax is used) and is therefore consumed, leaving the second backslash of the
and is therefore consumed, leaving the second backslash of the pair. (Dollar-quoted strings can be used to avoid this level
pair. The remaining backslash is then recognized by the of escaping.) The remaining backslash is then recognized by the
<type>bytea</type> input function as starting either a three <type>bytea</type> input function as starting either a three
digit octal value or escaping another backslash. For example, digit octal value or escaping another backslash. For example,
a string literal passed to the server as <literal>'\\001'</literal> a string literal passed to the server as <literal>E'\\001'</literal>
becomes <literal>\001</literal> after passing through the becomes <literal>\001</literal> after passing through the
string-literal parser. The <literal>\001</literal> is then sent escape string parser. The <literal>\001</literal> is then sent
to the <type>bytea</type> input function, where it is converted to the <type>bytea</type> input function, where it is converted
to a single octet with a decimal value of 1. Note that the to a single octet with a decimal value of 1. Note that the
apostrophe character is not treated specially by <type>bytea</type>, single-quote character is not treated specially by <type>bytea</type>,
so it follows the normal rules for string literals. (See also so it follows the normal rules for string literals. (See also
<xref linkend="sql-syntax-strings">.) <xref linkend="sql-syntax-strings">.)
</para> </para>
@ -1220,7 +1218,7 @@ SELECT b, char_length(b) FROM test2;
<entry>92</entry> <entry>92</entry>
<entry>backslash</entry> <entry>backslash</entry>
<entry><literal>\\</literal></entry> <entry><literal>\\</literal></entry>
<entry><literal>SELECT '\\134'::bytea;</literal></entry> <entry><literal>SELECT E'\\134'::bytea;</literal></entry>
<entry><literal>\\</literal></entry> <entry><literal>\\</literal></entry>
</row> </row>
@ -1228,7 +1226,7 @@ SELECT b, char_length(b) FROM test2;
<entry>0 to 31 and 127 to 255</entry> <entry>0 to 31 and 127 to 255</entry>
<entry><quote>non-printable</quote> octets</entry> <entry><quote>non-printable</quote> octets</entry>
<entry><literal>\<replaceable>xxx</></literal> (octal value)</entry> <entry><literal>\<replaceable>xxx</></literal> (octal value)</entry>
<entry><literal>SELECT '\\001'::bytea;</literal></entry> <entry><literal>SELECT E'\\001'::bytea;</literal></entry>
<entry><literal>\001</literal></entry> <entry><literal>\001</literal></entry>
</row> </row>
@ -1236,7 +1234,7 @@ SELECT b, char_length(b) FROM test2;
<entry>32 to 126</entry> <entry>32 to 126</entry>
<entry><quote>printable</quote> octets</entry> <entry><quote>printable</quote> octets</entry>
<entry>client character set representation</entry> <entry>client character set representation</entry>
<entry><literal>SELECT '\\176'::bytea;</literal></entry> <entry><literal>SELECT E'\\176'::bytea;</literal></entry>
<entry><literal>~</literal></entry> <entry><literal>~</literal></entry>
</row> </row>

50
doc/src/sgml/func.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.347.2.2 2007/01/30 02:32:04 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.347.2.3 2007/01/30 22:29:40 momjian Exp $ -->
<chapter id="functions"> <chapter id="functions">
<title>Functions and Operators</title> <title>Functions and Operators</title>
@ -1329,7 +1329,7 @@
Encode binary data to <acronym>ASCII</acronym>-only representation. Supported Encode binary data to <acronym>ASCII</acronym>-only representation. Supported
types are: <literal>base64</>, <literal>hex</>, <literal>escape</>. types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
</entry> </entry>
<entry><literal>encode( '123\\000\\001', 'base64')</literal></entry> <entry><literal>encode( E'123\\000\\001', 'base64')</literal></entry>
<entry><literal>MTIzAAE=</literal></entry> <entry><literal>MTIzAAE=</literal></entry>
</row> </row>
@ -1429,7 +1429,7 @@
<entry> <entry>
Return the given string suitably quoted to be used as a string literal Return the given string suitably quoted to be used as a string literal
in an <acronym>SQL</acronym> statement string. in an <acronym>SQL</acronym> statement string.
Embedded quotes and backslashes are properly doubled. Embedded single-quotes and backslashes are properly doubled.
</entry> </entry>
<entry><literal>quote_literal( 'O\'Reilly')</literal></entry> <entry><literal>quote_literal( 'O\'Reilly')</literal></entry>
<entry><literal>'O''Reilly'</literal></entry> <entry><literal>'O''Reilly'</literal></entry>
@ -2383,7 +2383,7 @@
<secondary>concatenation</secondary> <secondary>concatenation</secondary>
</indexterm> </indexterm>
</entry> </entry>
<entry><literal>'\\\\Post'::bytea || '\\047gres\\000'::bytea</literal></entry> <entry><literal>E'\\\\Post'::bytea || E'\\047gres\\000'::bytea</literal></entry>
<entry><literal>\\Post'gres\000</literal></entry> <entry><literal>\\Post'gres\000</literal></entry>
</row> </row>
@ -2396,7 +2396,7 @@
<primary>get_bit</primary> <primary>get_bit</primary>
</indexterm> </indexterm>
</entry> </entry>
<entry><literal>get_bit('Th\\000omas'::bytea, 45)</literal></entry> <entry><literal>get_bit(E'Th\\000omas'::bytea, 45)</literal></entry>
<entry><literal>1</literal></entry> <entry><literal>1</literal></entry>
</row> </row>
@ -2409,7 +2409,7 @@
<primary>get_byte</primary> <primary>get_byte</primary>
</indexterm> </indexterm>
</entry> </entry>
<entry><literal>get_byte('Th\\000omas'::bytea, 4)</literal></entry> <entry><literal>get_byte(E'Th\\000omas'::bytea, 4)</literal></entry>
<entry><literal>109</literal></entry> <entry><literal>109</literal></entry>
</row> </row>
@ -2417,7 +2417,7 @@
<entry><literal><function>octet_length</function>(<parameter>string</parameter>)</literal></entry> <entry><literal><function>octet_length</function>(<parameter>string</parameter>)</literal></entry>
<entry><type>int</type></entry> <entry><type>int</type></entry>
<entry>Number of bytes in binary string</entry> <entry>Number of bytes in binary string</entry>
<entry><literal>octet_length( 'jo\\000se'::bytea)</literal></entry> <entry><literal>octet_length( E'jo\\000se'::bytea)</literal></entry>
<entry><literal>5</literal></entry> <entry><literal>5</literal></entry>
</row> </row>
@ -2425,7 +2425,7 @@
<entry><literal><function>position</function>(<parameter>substring</parameter> in <parameter>string</parameter>)</literal></entry> <entry><literal><function>position</function>(<parameter>substring</parameter> in <parameter>string</parameter>)</literal></entry>
<entry><type>int</type></entry> <entry><type>int</type></entry>
<entry>Location of specified substring</entry> <entry>Location of specified substring</entry>
<entry><literal>position('\\000om'::bytea in 'Th\\000omas'::bytea)</literal></entry> <entry><literal>position(E'\\000om'::bytea in E'Th\\000omas'::bytea)</literal></entry>
<entry><literal>3</literal></entry> <entry><literal>3</literal></entry>
</row> </row>
@ -2439,7 +2439,7 @@
<primary>set_bit</primary> <primary>set_bit</primary>
</indexterm> </indexterm>
</entry> </entry>
<entry><literal>set_bit('Th\\000omas'::bytea, 45, 0)</literal></entry> <entry><literal>set_bit(E'Th\\000omas'::bytea, 45, 0)</literal></entry>
<entry><literal>Th\000omAs</literal></entry> <entry><literal>Th\000omAs</literal></entry>
</row> </row>
@ -2453,7 +2453,7 @@
<primary>set_byte</primary> <primary>set_byte</primary>
</indexterm> </indexterm>
</entry> </entry>
<entry><literal>set_byte('Th\\000omas'::bytea, 4, 64)</literal></entry> <entry><literal>set_byte(E'Th\\000omas'::bytea, 4, 64)</literal></entry>
<entry><literal>Th\000o@as</literal></entry> <entry><literal>Th\000o@as</literal></entry>
</row> </row>
@ -2466,7 +2466,7 @@
<primary>substring</primary> <primary>substring</primary>
</indexterm> </indexterm>
</entry> </entry>
<entry><literal>substring('Th\\000omas'::bytea from 2 for 3)</literal></entry> <entry><literal>substring(E'Th\\000omas'::bytea from 2 for 3)</literal></entry>
<entry><literal>h\000o</literal></entry> <entry><literal>h\000o</literal></entry>
</row> </row>
@ -2482,7 +2482,7 @@
<parameter>bytes</parameter> from the start <parameter>bytes</parameter> from the start
and end of <parameter>string</parameter> and end of <parameter>string</parameter>
</entry> </entry>
<entry><literal>trim('\\000'::bytea from '\\000Tom\\000'::bytea)</literal></entry> <entry><literal>trim(E'\\000'::bytea from E'\\000Tom\\000'::bytea)</literal></entry>
<entry><literal>Tom</literal></entry> <entry><literal>Tom</literal></entry>
</row> </row>
</tbody> </tbody>
@ -2520,7 +2520,7 @@
in <parameter>bytes</parameter> from the start and end of in <parameter>bytes</parameter> from the start and end of
<parameter>string</parameter> <parameter>string</parameter>
</entry> </entry>
<entry><literal>btrim('\\000trim\\000'::bytea, '\\000'::bytea)</literal></entry> <entry><literal>btrim(E'\\000trim\\000'::bytea, E'\\000'::bytea)</literal></entry>
<entry><literal>trim</literal></entry> <entry><literal>trim</literal></entry>
</row> </row>
@ -2534,7 +2534,7 @@
Decode binary string from <parameter>string</parameter> previously Decode binary string from <parameter>string</parameter> previously
encoded with <function>encode</>. Parameter type is same as in <function>encode</>. encoded with <function>encode</>. Parameter type is same as in <function>encode</>.
</entry> </entry>
<entry><literal>decode('123\\000456', 'escape')</literal></entry> <entry><literal>decode(E'123\\000456', 'escape')</literal></entry>
<entry><literal>123\000456</literal></entry> <entry><literal>123\000456</literal></entry>
</row> </row>
@ -2548,7 +2548,7 @@
Encode binary string to <acronym>ASCII</acronym>-only representation. Supported Encode binary string to <acronym>ASCII</acronym>-only representation. Supported
types are: <literal>base64</>, <literal>hex</>, <literal>escape</>. types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
</entry> </entry>
<entry><literal>encode('123\\000456'::bytea, 'escape')</literal></entry> <entry><literal>encode(E'123\\000456'::bytea, 'escape')</literal></entry>
<entry><literal>123\000456</literal></entry> <entry><literal>123\000456</literal></entry>
</row> </row>
@ -2567,7 +2567,7 @@
<see>binary strings, length</see> <see>binary strings, length</see>
</indexterm> </indexterm>
</entry> </entry>
<entry><literal>length('jo\\000se'::bytea)</literal></entry> <entry><literal>length(E'jo\\000se'::bytea)</literal></entry>
<entry><literal>5</literal></entry> <entry><literal>5</literal></entry>
</row> </row>
@ -2578,7 +2578,7 @@
Calculates the MD5 hash of <parameter>string</parameter>, Calculates the MD5 hash of <parameter>string</parameter>,
returning the result in hexadecimal returning the result in hexadecimal
</entry> </entry>
<entry><literal>md5('Th\\000omas'::bytea)</literal></entry> <entry><literal>md5(E'Th\\000omas'::bytea)</literal></entry>
<entry><literal>8ab2d3c9689aaf18 b4958c334c82d8b1</literal></entry> <entry><literal>8ab2d3c9689aaf18 b4958c334c82d8b1</literal></entry>
</row> </row>
</tbody> </tbody>
@ -2802,7 +2802,8 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
<para> <para>
Note that the backslash already has a special meaning in string Note that the backslash already has a special meaning in string
literals, so to write a pattern constant that contains a backslash literals, so to write a pattern constant that contains a backslash
you must write two backslashes in an SQL statement. Thus, writing a pattern you must write two backslashes in an SQL statement (assuming escape
string syntax is used). Thus, writing a pattern
that actually matches a literal backslash means writing four backslashes that actually matches a literal backslash means writing four backslashes
in the statement. You can avoid this by selecting a different escape in the statement. You can avoid this by selecting a different escape
character with <literal>ESCAPE</literal>; then a backslash is not special character with <literal>ESCAPE</literal>; then a backslash is not special
@ -3096,7 +3097,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
substring matching the entire pattern should be inserted. Write substring matching the entire pattern should be inserted. Write
<literal>\\</> if you need to put a literal backslash in the replacement <literal>\\</> if you need to put a literal backslash in the replacement
text. (As always, remember to double backslashes written in literal text. (As always, remember to double backslashes written in literal
constant strings.) constant strings, assuming escape string syntax is used.)
The <replaceable>flags</> parameter is an optional text The <replaceable>flags</> parameter is an optional text
string containing zero or more single-letter flags that change the string containing zero or more single-letter flags that change the
function's behavior. Flag <literal>i</> specifies case-insensitive function's behavior. Flag <literal>i</> specifies case-insensitive
@ -3111,7 +3112,7 @@ regexp_replace('foobarbaz', 'b..', 'X')
<lineannotation>fooXbaz</lineannotation> <lineannotation>fooXbaz</lineannotation>
regexp_replace('foobarbaz', 'b..', 'X', 'g') regexp_replace('foobarbaz', 'b..', 'X', 'g')
<lineannotation>fooXX</lineannotation> <lineannotation>fooXX</lineannotation>
regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g') regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g')
<lineannotation>fooXarYXazY</lineannotation> <lineannotation>fooXarYXazY</lineannotation>
</programlisting> </programlisting>
</para> </para>
@ -3273,7 +3274,8 @@ regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
Remember that the backslash (<literal>\</literal>) already has a special Remember that the backslash (<literal>\</literal>) already has a special
meaning in <productname>PostgreSQL</> string literals. meaning in <productname>PostgreSQL</> string literals.
To write a pattern constant that contains a backslash, To write a pattern constant that contains a backslash,
you must write two backslashes in the statement. you must write two backslashes in the statement, assuming escape
string syntax is used.
</para> </para>
</note> </note>
@ -3584,7 +3586,7 @@ regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
Keep in mind that an escape's leading <literal>\</> will need to be Keep in mind that an escape's leading <literal>\</> will need to be
doubled when entering the pattern as an SQL string constant. For example: doubled when entering the pattern as an SQL string constant. For example:
<programlisting> <programlisting>
'123' ~ '^\\d{3}' <lineannotation>true</lineannotation> '123' ~ E'^\\d{3}' <lineannotation>true</lineannotation>
</programlisting> </programlisting>
</para> </para>
</note> </note>
@ -4746,10 +4748,10 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem> <listitem>
<para> <para>
If you want to have a double quote in the output you must If you want to have a double quote in the output you must
precede it with a backslash, for example <literal>'\\"YYYY precede it with a backslash, for example <literal>E'\\"YYYY
Month\\"'</literal>. <!-- "" font-lock sanity :-) --> Month\\"'</literal>. <!-- "" font-lock sanity :-) -->
(Two backslashes are necessary because the backslash already (Two backslashes are necessary because the backslash already
has a special meaning in a string constant.) has a special meaning when using the escape string syntax.)
</para> </para>
</listitem> </listitem>

6
doc/src/sgml/libpq.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.220 2006/11/10 22:15:26 tgl Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.220.2.1 2007/01/30 22:29:40 momjian Exp $ -->
<chapter id="libpq"> <chapter id="libpq">
<title><application>libpq</application> - C Library</title> <title><application>libpq</application> - C Library</title>
@ -910,7 +910,7 @@ in a numeric form that is much easier to compare against.
<para> <para>
If no value for <literal>standard_conforming_strings</> is reported, If no value for <literal>standard_conforming_strings</> is reported,
applications may assume it is <literal>false</>, that is, backslashes applications may assume it is <literal>off</>, that is, backslashes
are treated as escapes in string literals. Also, the presence of this are treated as escapes in string literals. Also, the presence of this
parameter may be taken as an indication that the escape string syntax parameter may be taken as an indication that the escape string syntax
(<literal>E'...'</>) is accepted. (<literal>E'...'</>) is accepted.
@ -2488,7 +2488,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn,
of a <type>bytea</type> literal in an <acronym>SQL</acronym> of a <type>bytea</type> literal in an <acronym>SQL</acronym>
statement. In general, to escape a byte, it is converted into the statement. In general, to escape a byte, it is converted into the
three digit octal number equal to the octet value, and preceded by three digit octal number equal to the octet value, and preceded by
one or two backslashes. The single quote (<literal>'</>) and backslash usually two backslashes. The single quote (<literal>'</>) and backslash
(<literal>\</>) characters have special alternative escape (<literal>\</>) characters have special alternative escape
sequences. See <xref linkend="datatype-binary"> for more sequences. See <xref linkend="datatype-binary"> for more
information. <function>PQescapeByteaConn</function> performs this information. <function>PQescapeByteaConn</function> performs this

10
doc/src/sgml/plperl.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.59 2006/11/13 17:13:56 adunstan Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.59.2.1 2007/01/30 22:29:40 momjian Exp $ -->
<chapter id="plperl"> <chapter id="plperl">
<title>PL/Perl - Perl Procedural Language</title> <title>PL/Perl - Perl Procedural Language</title>
@ -80,10 +80,10 @@ $$ LANGUAGE plperl;
the function body to be written as a string constant. It is usually the function body to be written as a string constant. It is usually
most convenient to use dollar quoting (see <xref most convenient to use dollar quoting (see <xref
linkend="sql-syntax-dollar-quoting">) for the string constant. linkend="sql-syntax-dollar-quoting">) for the string constant.
If you choose to use regular single-quoted string constant syntax, If you choose to use escape string syntax <literal>E''</>,
you must escape single quote marks (<literal>'</>) and backslashes you must double the single quote marks (<literal>'</>) and backslashes
(<literal>\</>) used in the body of the function, typically by (<literal>\</>) used in the body of the function
doubling them (see <xref linkend="sql-syntax-strings">). (see <xref linkend="sql-syntax-strings">).
</para> </para>
<para> <para>

12
doc/src/sgml/plpgsql.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.101 2006/10/23 18:10:31 petere Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.101.2.1 2007/01/30 22:29:40 momjian Exp $ -->
<chapter id="plpgsql"> <chapter id="plpgsql">
<title><application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language</title> <title><application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language</title>
@ -288,7 +288,8 @@ $$ LANGUAGE plpgsql;
<command>CREATE FUNCTION</command> as a string literal. If you <command>CREATE FUNCTION</command> as a string literal. If you
write the string literal in the ordinary way with surrounding write the string literal in the ordinary way with surrounding
single quotes, then any single quotes inside the function body single quotes, then any single quotes inside the function body
must be doubled; likewise any backslashes must be doubled. must be doubled; likewise any backslashes must be doubled (assuming
escape string syntax is used).
Doubling quotes is at best tedious, and in more complicated cases Doubling quotes is at best tedious, and in more complicated cases
the code can become downright incomprehensible, because you can the code can become downright incomprehensible, because you can
easily find yourself needing half a dozen or more adjacent quote marks. easily find yourself needing half a dozen or more adjacent quote marks.
@ -434,13 +435,6 @@ a_output := a_output || $$ if v_$$ || referrer_keys.kind || $$ like '$$
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<para>
A variant approach is to escape quotation marks in the function body
with a backslash rather than by doubling them. With this method
you'll find yourself writing things like <literal>\'\'</> instead
of <literal>''''</>. Some find this easier to keep track of, some
do not.
</para>
</sect2> </sect2>
</sect1> </sect1>

12
doc/src/sgml/pltcl.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.42 2006/09/16 00:30:15 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.42.2.1 2007/01/30 22:29:40 momjian Exp $ -->
<chapter id="pltcl"> <chapter id="pltcl">
<title>PL/Tcl - Tcl Procedural Language</title> <title>PL/Tcl - Tcl Procedural Language</title>
@ -387,11 +387,11 @@ CREATE FUNCTION t1_count(integer, integer) RETURNS integer AS $$
$$ LANGUAGE pltcl; $$ LANGUAGE pltcl;
</programlisting> </programlisting>
We need backslashes inside the query string given to We need backslashes inside the query string given to
<function>spi_prepare</> to ensure that the <function>spi_prepare</> to ensure that the
<literal>$<replaceable>n</replaceable></> markers will be passed <literal>$<replaceable>n</replaceable></> markers will be passed
through to <function>spi_prepare</> as-is, and not replaced by Tcl through to <function>spi_prepare</> as-is, and not replaced by Tcl
variable substitution. variable substitution.
</para> </para>
</listitem> </listitem>

7
doc/src/sgml/rowtypes.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.6 2005/11/04 23:14:01 petere Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.6.4.1 2007/01/30 22:29:40 momjian Exp $ -->
<sect1 id="rowtypes"> <sect1 id="rowtypes">
<title>Composite Types</title> <title>Composite Types</title>
@ -294,11 +294,12 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
<para> <para>
Remember that what you write in an SQL command will first be interpreted Remember that what you write in an SQL command will first be interpreted
as a string literal, and then as a composite. This doubles the number of as a string literal, and then as a composite. This doubles the number of
backslashes you need. For example, to insert a <type>text</> field backslashes you need (assuming escape string syntax is used).
For example, to insert a <type>text</> field
containing a double quote and a backslash in a composite containing a double quote and a backslash in a composite
value, you'd need to write value, you'd need to write
<programlisting> <programlisting>
INSERT ... VALUES ('("\\"\\\\")'); INSERT ... VALUES (E'("\\"\\\\")');
</programlisting> </programlisting>
The string-literal processor removes one level of backslashes, so that The string-literal processor removes one level of backslashes, so that
what arrives at the composite-value parser looks like what arrives at the composite-value parser looks like

8
doc/src/sgml/xfunc.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.120 2006/11/23 05:43:32 neilc Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.120.2.1 2007/01/30 22:29:40 momjian Exp $ -->
<sect1 id="xfunc"> <sect1 id="xfunc">
<title>User-Defined Functions</title> <title>User-Defined Functions</title>
@ -147,9 +147,9 @@ SELECT clean_emp();
most convenient to use dollar quoting (see <xref most convenient to use dollar quoting (see <xref
linkend="sql-syntax-dollar-quoting">) for the string constant. linkend="sql-syntax-dollar-quoting">) for the string constant.
If you choose to use regular single-quoted string constant syntax, If you choose to use regular single-quoted string constant syntax,
you must escape single quote marks (<literal>'</>) and backslashes you must double single quote marks (<literal>'</>) and backslashes
(<literal>\</>) used in the body of the function, typically by (<literal>\</>) (assuming escape string syntax) in the body of
doubling them (see <xref linkend="sql-syntax-strings">). the function (see <xref linkend="sql-syntax-strings">).
</para> </para>
<para> <para>